Passer au contenu principal
Lorsqu’un travail doit être chiffré avant d’être exécuté, les fournisseurs soumettent des propositions (soumissions) contre le bon de travail. Via l’API Acheteur, les propositions sont en lecture seule : vous les listez, inspectez les postes et les réconciliez avec les factures. Approuver ou refuser une proposition se fait dans l’application OpenWrench. Tous les exemples supposent :

Statuts de proposition

Les statuts sont conservés en minuscules.

Lire les propositions

Règles de portée à connaître :
  • Les brouillons non soumis des fournisseurs sont toujours exclus des listes.
  • Si le contact associé à votre clé d’API est restreint par emplacement, vous ne voyez que les propositions pour les emplacements accessibles. Un contact avec un ensemble d’accès vide obtient une page vide, pas une erreur.
  • La lecture unique renvoie 404 pour les propositions supprimées de façon logique, les brouillons et les propositions hors de votre portée d’emplacement. Traitez 404 comme « non visible pour vous », pas nécessairement « n’existe pas ».

Référence des filtres

La liste prend 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 et d’emplacement de votre clé. Il n’y a pas d’endpoint de comptage : le count de la réponse de liste est le nombre total de correspondances, alors demandez limit=1 lorsque vous n’avez besoin que du nombre.
Règles des valeurs :
  • Tri. sort_by prend en charge createdAt, updatedAt, totalAfterTax, id, workOrderId, locationId, supplierFacilityId et buyerFacilityId. Sans sort_by, ou avec toute autre valeur, les résultats sont triés par id croissant (les plus anciennes en premier). 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.
  • 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. Une espace après une virgule peut faire échouer la requête.
  • 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 la portée de locataire ne peut pas être contournée : buyerCompanyId est toujours défini à partir de votre clé d’API, et les brouillons sont exclus même si vous demandez status=draft.
Pour cibler une seule journée locale, envoyez la même date pour les deux bornes avec votre fuseau. Cette requête renvoie les propositions octroyées le 9 octobre 2026, heure du Centre :

À l’intérieur d’une proposition

L’argent est réparti dans les mêmes sections que les factures : laborLineItems, materialLineItems, travelLineItems, freightLineItems et miscLineItems, chaque section avec son propre taux de taxe et ...TotalBeforeTax, se totalisant à totalBeforeTax, tax et totalAfterTax. Les valeurs monétaires sont sérialisées en chaînes; analysez-les comme décimales, non comme flottants, si vous faites de l’arithmétique. Autres champs utiles : workOrderId, supplierFacilityId, workOrderNTEBeforeApproval (le montant à ne pas dépasser du bon de travail au moment de la soumission), proposalPdfLink, attachments, submittedAt et approvedAt.

Où les propositions s’inscrivent dans le flux

  1. Le fournisseur soumet une proposition; le bon de travail se met généralement en pause en attente d’approbation.
  2. Vos approbateurs l’accordent ou la refusent dans l’application. L’octroi relève le plafond de dépenses effectif du travail.
  3. Lorsque la facture finale arrive, comparez invoiceTotalAfterTax au totalAfterTax de la proposition octroyée avant d’approuver le paiement. Signalez les écarts au-delà de votre tolérance pour révision humaine.
Une boucle de sondage pratique pour un tableau de bord des achats : filtrez par status=pending, triez avec sort_by=createdAt&order=desc et paginez avec limit=25, en respectant la limite de débit de 10 requêtes par fenêtre de 20 secondes.