Passer au contenu principal
L’argent circule à travers deux objets : les propositions (soumissions que l’acheteur approuve avant que le travail se poursuive) et les factures (la facturation pour le travail terminé). Les fournisseurs créent les deux via cette API.
Aucun de ces endpoints n’est disponible pour les clés d’équipes de service internes; la soumission et la facturation sont pour les fournisseurs tiers qui facturent un acheteur.
Tous les exemples supposent :

L’argent en chaînes, par sections

Les propositions et les factures partagent une structure de postes. Les montants sont des chaînes qui doivent s’analyser comme des nombres (« 450.00 », pas 450.00 en flottant; vous devriez formater à deux décimales et analyser comme décimales). Les sections sont main-d’œuvre, matériel, déplacement, fret et divers (les propositions ajoutent les coûts engagés). Chaque section porte ses propres postes, son taux de taxe et son ...TotalBeforeTax, et les sections se totalisent en avant taxe, taxe et après taxe. Les lignes de déplacement, de fret et divers sont de simples objets { "description", "amount" }.

Propositions (soumissions)

POST /v1/supplier/quote/proposals crée la proposition directement au statut pending sous votre établissement; il n’y a pas d’étape de soumission distincte. Requis : workOrderId et totalAfterTax.
Comportement à connaître :
  • locationId, buyerFacilityId et buyerCompanyId sont dérivés du bon de travail; vous ne pouvez pas les définir.
  • Les champs de taxe et les totaux de section non définis sont par défaut à "0".
  • requestForProposalId prend par défaut la RFP du bon de travail lorsqu’il est omis.
  • proposalPdfLink, s’il est envoyé, doit être une URL valide. attachments prend des FileDetails de l’endpoint de téléversement de fichier.
  • Passer un id met à jour une proposition existante.
Suivez le résultat en récupérant à nouveau : status passe de pending à awarded ou declined (les raisons de refus apparaissent dans declineNotes). Listez avec GET /v1/supplier/quote/proposals (voir filtrer les listes), lisez-en une avec GET /v1/supplier/quote/proposals/{id}.

Factures

Le cycle de vie

Les factures commencent comme draft (invisible pour l’acheteur), sont publiées en pending, puis l’acheteur les fait avancer à travers approved et processing jusqu’à paid (ou les conteste). Votre intégration crée le brouillon et le publie; à partir de pending, vous lisez surtout le statut.

Créer le brouillon

POST /v1/supplier/invoice/invoices requiert workOrderId; locationId, buyerFacilityId, buyerCompanyId, spendCategoryId et problemTypeId en sont tous dérivés.
Comportement à connaître :
  • poNumber prend par défaut le numéro de BC du bon de travail.
  • serviceCallIds prend par défaut tous les appels de service du bon de travail lorsqu’il est omis ou vide; définissez-le explicitement lorsque vous facturez un sous-ensemble de visites.
  • OpenWrench valide taxLineItems contre les types de taxe permis pour la devise de la facture et rejette tout autre type. Actuellement, seul le CAD les prend en charge (GST/HST/PST).
  • invoicePDFLink (une URL valide) devient la seule entrée PDF de la facture si vous hébergez le PDF vous-même; la plupart des intégrations utilisent plutôt l’endpoint de téléversement ci-dessous.
  • autoPublishOnApproval inscrit cette facture à la publication automatique lorsque le bon de travail se termine.
  • Sauvegarder une facture peut faire passer le statut du bon de travail associé selon la correspondance facture-vers-bon-de-travail. Un échec de validation au niveau de la sauvegarde renvoie 406.
  • Passer un id met à jour une facture existante (en pratique, seulement les brouillons; les statuts côté acheteur ne vous appartiennent pas).

Téléverser le PDF et publier

POST /v1/supplier/invoice/file/upload_and_publish/{invoiceId} fait les deux étapes en même temps : le PDF téléversé (partie multipart file, maximum 512 Mo) devient le seul PDF de la facture, et le statut passe à pending.
L’endpoint renvoie 400 si une précondition n’est pas satisfaite : votre établissement doit posséder la facture, le bon de travail associé doit être au statut d’affichage Completed, et la configuration de l’acheteur doit permettre la modification de facture par le fournisseur.

Lire et réconcilier

GET /v1/supplier/invoice/invoices (filtrable, voir filtrer les listes) et GET /v1/supplier/invoice/invoices/{id}. Les fournisseurs tiers voient des fiches masquées, les champs privés à l’acheteur étant vidés. Sondez le statut pour piloter votre grand livre des comptes clients : approvedAt, processedAt et markedPaidAt horodatent la progression de l’acheteur.

Filtrer les listes

GET /v1/supplier/quote/proposals et GET /v1/supplier/invoice/invoices prennent offset, limit (par défaut 10, maximum 25), sort_by et order, en plus des filtres ci-dessous. Les filtres se combinent avec ET, et se combinent toujours avec la portée de locataire de votre clé, donc vous ne voyez que les propositions et les factures de votre établissement. Aucune des deux listes n’a d’endpoint de comptage; le count de la réponse est le nombre total de correspondances.
Les deux listes Propositions seulement Factures seulement Règles des valeurs :
  • Tri. Les deux listes se trient par createdAt, id, workOrderId, locationId, supplierFacilityId ou buyerFacilityId; les factures se trient aussi par invoiceTotalAfterTax, et les propositions par updatedAt et totalAfterTax. Dès que vous définissez sort_by, order est asc par défaut, alors envoyez order=desc pour obtenir les plus récentes en premier. Sans sort_by, les factures arrivent des plus récentes aux plus anciennes et les propositions dans l’ordre des id (les plus anciennes en premier). Un sort_by non pris en charge sur les propositions revient aussi à l’ordre des id.
  • Les listes prennent des virgules, sans espaces. Une clé au singulier (status) prend une seule valeur; la clé au pluriel prend une liste séparée par des virgules. status=pending,approved cherche un unique statut portant ce nom littéral et ne renvoie rien. Une espace après une virgule 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. 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 valeurs doivent être bien formées. Un id non numérique, ou un booléen autre que true ou false, peut faire échouer la requête avec un 500 plutôt qu’un 400.
  • Les filtres non reconnus sont ignorés, et votre portée de locataire ne peut pas être contournée : supplierFacilityId est toujours défini à partir de votre clé d’API.
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 :

Flux de facturation de bout en bout

  1. Le bon de travail atteint l’étape de soumission : soumettez une proposition, attendez awarded.
  2. Complétez le travail via le départ d’appel de service.
  3. Créez le brouillon de facture; générez votre PDF.
  4. Une fois que le bon de travail affiche Completed, upload_and_publish.
  5. Sondez le statut de la facture jusqu’à paid, et réconciliez contre markedPaidAt.