Passer au contenu principal
Les fournisseurs facturent les bons de travail terminés au moyen de factures; l’API Acheteur est l’endroit où votre intégration comptes fournisseurs les lit, les fait progresser dans l’approbation et les marque payées. Les factures peuvent aussi être rattachées à un projet plutôt qu’à un bon de travail. Les mêmes statuts et endpoints de paiement s’appliquent, avec les différences précisées ci-dessous. Tous les exemples supposent :

Statuts de facture

Les factures portent un status en minuscules : Le chemin contrôlé par l’acheteur est pending → approved → processing → paid. Chaque déplacement a un endpoint dédié; il n’y a pas de setter de statut générique.

Lire les factures

Une facture est reliée à son supplierFacilityId en plus d’exactement un de workOrderId ou projectId (l’autre est null, tout comme l’objet hydraté workOrder / project). Les factures de bon de travail portent toujours locationId et buyerFacilityId; les factures de projet ne les portent que si le client les a fournis, alors les deux peuvent être null. La facture porte la ventilation monétaire en sections (main-d’œuvre, matériel, déplacement, fret, divers), chacune avec des postes, un taxRate et un totalBeforeTax. Ces sections se totalisent à invoiceTotalBeforeTax, invoiceTax et invoiceTotalAfterTax. Les valeurs monétaires sont sérialisées en chaînes de caractères. Un court résumé de la portée dérivé par IA peut apparaître dans title. Le PDF rendu se trouve dans invoicePDFs; les fichiers de soutien sont dans attachments (voir Fichiers et pièces jointes).

Lister, filtrer et compter

GET /invoices, /invoices/count_by et /invoices/download prennent les mêmes filtres de la référence des filtres ci-dessous. Les filtres se combinent avec ET, et se combinent toujours avec la portée de locataire dérivée de votre clé. Les brouillons des fournisseurs et les factures annulées ne sont jamais retournés, peu importe vos filtres.
  • Tri. sort_by prend en charge createdAt, invoiceTotalAfterTax, id, workOrderId, locationId, supplierFacilityId et buyerFacilityId. Sans sort_by, les résultats sont triés du plus récent au plus ancien. Dès que vous définissez sort_by, order est asc par défaut, alors envoyez order=desc pour un tri décroissant. Les autres champs, comme publishedAt, ne sont pas triables; filtrez plutôt sur une fenêtre publishedAt.
  • Les filtres non reconnus sont ignorés. Tout paramètre de requête absent de la référence des filtres est ignoré plutôt que rejeté, et la requête aboutit quand même. Avant de vous appuyer sur un nouveau filtre, comparez count_by avec et sans lui.

Référence des filtres

Les clés sont sensibles à la casse. Une clé au singulier (status) prend une seule valeur; la clé au pluriel (statuses) prend une liste séparée par des virgules et correspond à l’une ou l’autre des valeurs. Statut Quoi et où Qui et comptabilité Dates

Règles des valeurs de filtre

  • Utilisez la clé au pluriel pour plusieurs valeurs, sans espaces. statuses=approved,processing correspond à l’un ou l’autre statut. status=approved,processing cherche un unique statut portant ce nom littéral et ne renvoie rien. Une espace après une virgule dans une liste d’ids peut faire échouer la requête.
  • Une valeur par clé. Si vous répétez un paramètre, seul le premier est utilisé.
  • Les dates utilisent MM/dd/yyyy HH:mm:ss, par exemple 08/01/2026 00:00:00. La valeur est une heure locale, lue dans le fuseau que vous passez dans timezone, ou en UTC sans celui-ci. L’heure est obligatoire. La borne de début est incluse à l’heure que vous envoyez. La borne de fin couvre toute la journée de fin dans ce fuseau : OpenWrench remplace son heure par 23:59:59. Encodez la valeur pour l’URL (curl -G --data-urlencode le fait pour vous). N’ajoutez pas de décalage comme -05:00 à la valeur : OpenWrench l’ignore.
  • Une date qui ne peut pas être analysée renvoie 400 avec Invalid <key>. Expected format MM/dd/yyyy HH:mm:ss. Cela inclut les valeurs ISO 8601 (2026-10-09T00:00:00), les dates sans heure (10/09/2026) et les valeurs composées uniquement d’espaces. OpenWrench lit encore une valeur vide comme le 1er janvier 1970.
  • timezone prend un nom de fuseau IANA, comme America/Chicago ou UTC. Les décalages fixes (-05:00, GMT-5), les abréviations (CST) et les noms inconnus renvoient 400. Consultez Formats de date pour l’heure avancée.
  • Les booléens sont true ou false. Toute autre valeur, ou un id non numérique, peut faire échouer la requête avec un 500 plutôt qu’un 400.
  • La portée de locataire ne peut pas être contournée. buyerCompanyId est toujours défini à partir de votre clé d’API, alors le passer n’a aucun effet.
Pour cibler une seule journée locale, envoyez la même date pour les deux bornes avec votre fuseau. Cette requête renvoie les factures marquées payées le 9 octobre 2026, heure du Centre :

Export aplati

GET /v1/buyer/invoice/invoices/download retourne les mêmes données en lignes plates (une ligne par facture avec les totaux dénormalisés), conçu pour l’export en tableur et les importations vers les systèmes de comptes fournisseurs. Mêmes filtres que l’endpoint de liste. Sur les lignes de factures de projet, workOrderId, workOrderTitle, problemTypeId, problemTypeName, locationId et locationName sont null; projectId est renseigné.

Faire progresser une facture dans l’approbation

Chaque endpoint de transition ne prend que l’id de la facture :
Les quatre endpoints sont status/pending, status/approved, status/processing et status/paid. Comportement partagé :
  • Chaque transition efface le drapeau de contestation de la facture, puis propage un changement de statut correspondant au bon de travail associé.
  • Si la correspondance de statut de bon de travail échoue, la facture est annulée et l’appel renvoie 400. Traitez un 400 ici comme « récupérer à nouveau et inspecter », pas « réessayer ».
  • Un échec de validation au niveau de la sauvegarde renvoie 406.

Marquer payée par id de bon de travail

Lorsque votre système comptes fournisseurs connaît le bon de travail mais pas l’id de facture OpenWrench, bouclez la boucle avec :
La recherche essaie d’abord workOrderId puis retombe sur externalWorkOrderId, toujours à l’intérieur de votre entreprise. Les factures déjà paid sont retournées inchangées (sécuritaire à réessayer); les factures approved ou processing sont marquées payées; une facture dans tout autre statut renvoie 400 avec « Invoice not found ».

Factures de projet

Les factures de projet sont rattachées à un projet (projectId) plutôt qu’à un bon de travail (workOrderId), et contournent le volet bon de travail du pipeline. Pour une facture sans workOrderId, OpenWrench saute :
  • La vérification NTE à la création et à la mise à jour.
  • La dérivation du code GL à partir du bon de travail.
  • La répercussion des dépenses de budget et des dépenses d’actifs.
  • La synchronisation de statut du bon de travail qui s’exécute normalement à chaque transition de statut (une transition de statut sur une facture de projet n’annule jamais et ne retourne pas 400 pour une correspondance BT rompue).
  • L’annexion de la page de détail du bon de travail dans l’utilitaire de PDF de facture.
  • Les hiérarchies d’approbation rattachées au BT et leurs notifications d’approbation, de rappel et d’escalade.
  • La vérification de doublons « une facture par fournisseur » par BT.
  • La validation à portée devise sur taxLineItems (les montants sont tout de même validés comme numériques).
Les analyses de coût par emplacement et de coût par établissement n’incluent que les factures qui portent le champ correspondant. Une facture de projet créée sans locationId ou buyerFacilityId n’apparaît pas dans ces rapports. Le raccourci POST status/paid/by_work_order_id ne correspond qu’aux factures de bon de travail; pour une facture de projet, marquez-la payée par id via POST status/paid.

Utilitaires

Annexer la page de détail du bon de travail au PDF. PATCH /v1/buyer/invoice/file/invoice_pdf/add_work_order_detail_page/{invoiceId} régénère le PDF de la facture avec la page de détail du bon de travail annexée et retourne le nouveau lien du PDF (enveloppe de type UpdatedInvoicePdf). Aucun corps de requête; non limité en débit. Mise à jour en lot avec filtres. PATCH /v1/buyer/invoice/bulk_update_with_filters applique une mise à jour de colonne à chaque facture correspondant à un filtre, toujours restreint à votre entreprise. Les deux mappings sont des colonne→valeur libres :
Il retourne le nombre de factures mises à jour. C’est un outil puissant qui contourne les effets secondaires des transitions par facture, alors préférez les endpoints de statut à moins d’avoir vraiment besoin d’un balayage. Non limité en débit. Publier les brouillons des bons de travail terminés. PATCH /v1/buyer/invoice/publish_draft_invoices_if_wo_complete_and_auto_publish_enabled publie les brouillons de factures fournisseur dont le bon de travail est terminé, pour les fournisseurs qui ont activé la publication automatique. Il requiert une clé d’API acheteur super-admin et renvoie 403 pour une clé normale. Prévu pour les tâches d’entretien planifiées.

Modèle de synchronisation des comptes fournisseurs

Une synchronisation robuste des comptes fournisseurs :
  1. Sondez GET /invoices?status=pending (ou des fenêtres publishedAt) selon un horaire.
  2. Récupérez chaque facture. Pour les factures de bon de travail, comparez les totaux à la proposition approuvée et au nte du bon de travail. Pour les factures de projet, comparez plutôt à votre budget de projet. La vérification NTE ne s’exécute pas côté serveur pour les factures de projet.
  3. POST status/approved, exportez vers votre système de comptes fournisseurs, puis POST status/processing.
  4. Au règlement, POST status/paid par id, ou status/paid/by_work_order_id en fonction de la référence de bon de travail que porte votre système de comptes fournisseurs.
  5. Journalisez le traceId de l’enveloppe sur tout 400/406 afin que le soutien puisse retracer la requête exacte.