/v1/buyer/work_order/ : la création de bons de travail, leur interrogation, les actions de statut côté acheteur, le fil de notes, les étiquettes et les types de problèmes.
Tous les exemples supposent ces variables shell :
L’objet bon de travail
Un bon de travail retourné par l’API porte, entre autres champs :Créer un bon de travail
POST /v1/buyer/work_order/work_orders exige plus que les champs évidents. Contrairement à la plupart des endpoints acheteur, buyerFacilityId, buyerCompanyId et createdBy doivent être fournis dans le corps; ils ne sont pas dérivés de votre clé d’API sur cet endpoint. Utilisez GET /v1/buyer/me pour rechercher une fois vos ids d’entreprise et d’établissement et les mettre en cache.
Champs requis : title, locationId, problemTypeId, buyerFacilityId, buyerCompanyId et createdBy (le courriel du contact créateur).
- Statut initial. Si
statusest omis, le statut initial est calculé à partir de la configuration de votre entreprise. Les demandes de service commencent généralement enPendingApproval; les bons de travail sont par défautUnassigned. Si vous passez unstatus, il est tout de même résolu par rapport à la configuration de l’entreprise, alors le statut effectif peut différer de ce que vous avez envoyé. - Répartition à la création. Passer
supplierFacilityIdaffecte le fournisseur immédiatement. UnsupplierFacilityId,assetIdouproblemTypeIdinconnu est rejeté avec400. - Sous-actifs.
subAssetIdsest un tableau optionnel d’ids de sous-actifs attachés en plus de l’assetIdprincipal. Les sous-actifs sont des actifs créés avec unparentId; voir Actifs. - Drapeau d’approbation. Le champ est
needApproval, pasneedsApproval. L’objet de réponse utiliseneedsApproval; la requête de création utiliseneedApproval. - Liaison à une visite d’inspection.
walkThroughIdetsiteSurveyTaskTitleIddoivent être fournis ensemble ou pas du tout. Voir Visites d’inspection de site. - Upserts. Passer un
idmet à jour ce bon de travail existant au lieu d’en créer un nouveau.
Lister, filtrer et compter
offset, limit (par défaut 10, maximum 25), sort_by et order. Tout autre paramètre de requête est lu comme un filtre 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é, donc vous ne voyez jamais que les bons de travail de votre entreprise.
La liste et le comptage déterminent quels bons de travail correspondent dans l’index de recherche d’OpenWrench, puis chargent les enregistrements complets depuis la base de données. Cela change quelques comportements :
- Recherche plein texte.
search=correspond aux mots (avec correspondance par préfixe et par radical) dans le titre, la description, le nom de l’emplacement, les notes, les notes d’arrivée et de départ des appels de service, et le nom du type de problème. Il correspond aussi aux numéros de référence comme le numéro de bon de travail, le numéro de bon de commande et le numéro de série d’actif. Mettez la valeur entre guillemets (search="walk-in cooler") pour exiger la phrase exacte. - Tri.
sort_byprend en chargecreatedAt,locationName,woPriority(selon le délai de résolution attendu de la priorité) etlastServiceCallServiceScheduledAt. Toute autre valeur, ou l’absence desort_by, trie parcreatedAtdécroissant. - Les filtres non reconnus sont ignorés. Seules les clés de la référence des filtres ci-dessous sont prises en charge. Tout autre paramètre de requête est ignoré plutôt que rejeté, et la requête aboutit quand même. Cela inclut les clés mal orthographiées ainsi que
updatedAtStartDate,updatedAtEndDate,statusChangedAt,buyerFacilityIdetwalkthroughId, qui ne figurent pas dans l’index de recherche. Avant de vous appuyer sur un nouveau filtre, comparezcount_byavec et sans lui. - Fraîcheur. Les mises à jour de l’index de recherche et du réplica accusent un léger retard sur les écritures, alors un bon de travail créé il y a quelques millisecondes peut être brièvement absent des résultats de liste et des comptages.
- Profondeur de pagination.
offset + limitne peut pas dépasser la fenêtre de résultats de recherche de 10 000. Resserrez le filtre plutôt que de paginer aussi profondément.
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; notStatuses exclut chaque statut listé. Les filtres de date sont expliqués sous règles des valeurs de filtre.
Statut
Quoi et où
Qui
Dates et échéances
Règles des valeurs de filtre
- Utilisez la clé au pluriel pour plusieurs valeurs.
statuses=Unassigned,PendingApprovalcorrespond à l’un ou l’autre statut.status=Unassigned,PendingApprovalcherche un unique statut portant ce nom littéral et ne renvoie rien. - Une valeur par clé. Si vous répétez un paramètre (
statuses=Unassigned&statuses=PendingApproval), seul le premier est utilisé. Séparez plutôt les valeurs par des virgules. - Les dates utilisent
MM/dd/yyyy HH:mm:ss, par exemple08/01/2026 00:00:00. La valeur est une heure locale, lue dans le fuseau que vous passez danstimezone, ou en UTC sans celui-ci. L’heure est obligatoire, et les deux bornes d’une fenêtre sont incluses. Les bornes de fin sont exactes : OpenWrench ne les arrondit pas à la fin de la journée, alors envoyez23:59:59pour inclure toute une journée. Encodez la valeur pour l’URL (curl -G --data-urlencodele 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
400avecInvalid <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. timezoneprend un nom de fuseau IANA, commeAmerica/ChicagoouUTC. Les décalages fixes (-05:00,GMT-5), les abréviations (CST) et les noms inconnus renvoient400. Consultez Formats de date pour l’heure avancée.- Les booléens sont
trueoufalse.isStaleetunscheduledOrPastSchedulen’agissent que surtrue. - Les valeurs doivent être bien formées. Un id non numérique, ou un booléen autre que
trueoufalse, peut faire échouer la requête avec un500plutôt qu’un400. - La portée de locataire ne peut pas être contournée.
buyerCompanyIdest toujours défini à partir de votre clé d’API, alors le passer n’a aucun effet.
00:00:00 et 23:59:59 à la même date avec votre fuseau. Cette requête renvoie les bons de travail créés le 9 octobre 2026, heure du Centre :
GET /v1/buyer/work_order/work_orders/{id}.
Réaffecter un fournisseur
PATCH /v1/buyer/work_order/work_orders/{id} est délibérément restreint : seuls supplierFacilityId et supplierPrimaryContactEmail sont lus depuis le corps. Tous les autres champs que vous envoyez sont silencieusement ignorés plutôt que rejetés.
supplierPrimaryContactEmailne s’applique que dans le cadre d’une réaffectation. L’envoyer sans changement d’établissement fournisseur rend l’ensemble du patch inopérant : rien n’est enregistré et le bon de travail courant est retourné.- Un id inexistant et un refus de permission renvoient tous deux la même réponse
400non autorisée, alors n’utilisez pas cet endpoint pour sonder l’existence d’un bon de travail.
Actions de statut acheteur
Quatre endpoints dédiés font progresser un bon de travail à travers les parties du cycle de vie appartenant à l’acheteur. Chacun prend le même corps : l’id du bon de travail et une note optionnelle qui est ajoutée au fil en même temps que le changement de statut.
Verrou d’annulation pendant qu’un technicien est sur place
Les entreprises peuvent activer un verrou d’annulation qui garde les bons de travail ouverts pendant qu’un technicien est sur place. Avec le verrou activé, OpenWrench rejette toute annulation avec409 Conflict si un technicien est activement arrivé (check-in) sur l’un des appels de service du bon de travail. Cela couvre les visites du bon de travail lui-même et les visites de ses bons de travail sous-traités. OpenWrench bloque de la même façon l’annulation d’un sous-contrat dont le statut se propage au bon de travail racine, et n’enregistre rien sur aucun des deux bons.
Le verrou se configure par entreprise acheteuse avec deux paramètres :
Le message d’erreur
409 identifie le technicien sur place par son courriel lorsque la visite l’a enregistré :
409, attendez que le technicien enregistre son départ (ou que l’arrivée devienne périmée) et réessayez, ou demandez au fournisseur de terminer la visite d’abord. Le verrou fait partie de la configuration des bons de travail de votre entreprise acheteuse dans OpenWrench.
Le modèle de statut
Valeurs destatus que vous verrez et définirez via l’API :
Les transitions appartenant au fournisseur arrivent via sa propre intégration ou les applications OpenWrench; votre côté les observe via les webhooks ou en récupérant le bon de travail (
statusChanges contient l’historique complet) et agit sur celles qui vous appartiennent.
Notes
Les bons de travail portent un fil de notes partagé entre acheteur et fournisseur. Ajouter avecPATCH /v1/buyer/work_order/work_orders/append_notes. Le corps est { "id": <woId>, "note": { ... } } où la note a besoin de text et noteAddedBy. Le serveur écrase noteAddedAt avec sa propre horloge, et le courriel de l’auteur est ajouté à la liste des abonnés acheteur du bon de travail afin qu’il reçoive les notifications subséquentes.
taggedUsers à côté de note : une liste de courriels de contacts à @mentionner. OpenWrench intègre chaque courriel dans note.elements comme un élément user, la même forme que les applications écrivent pour une @mention, vous n’avez donc pas à construire la structure elements vous-même. Les contacts étiquetés sont ajoutés à la liste des abonnés du bon de travail s’ils ne sont pas déjà abonnés.
taggedUsers :
- Les courriels sont épurés et mis en minuscules avant la correspondance. Une note peut mentionner au plus 25 utilisateurs.
- Les courriels en double dans la liste, et les utilisateurs déjà étiquetés dans
note.elements, sont ignorés plutôt que mentionnés deux fois. - Une entrée qui n’est pas un courriel valide, ou une liste de plus de 25 courriels, est rejetée avec un
400de typeinvalidInputDataException. Rien n’est persisté. - Une liste vide est ignorée. Envoyer
taggedUserssans objetnoteest rejeté avec400.
PATCH /v1/buyer/work_order/work_orders/append_notes/bulk. Utilisez-le lorsque vous avez un lot de photos à publier (le jeu avant/après d’un technicien, par exemple) : les abonnés reçoivent une seule notification groupée au lieu d’une notification par photo. Le corps est { "id": <woId>, "notes": [ ... ] } avec 1 à 25 notes, et chaque note doit porter une URL photo et aucun autre contenu : text doit être vide et video, audio, otherFile et elements doivent être absents. Répéter la même URL de photo dans une requête est rejeté avec 400. Le serveur horodate chaque note du lot avec le même noteAddedAt et préserve l’ordre d’envoi.
GET /v1/buyer/work_order/work_order_notes/{woId}. Cela retourne uniquement le fil racine acheteur-fournisseur (les fils sous-traitant et interne sont séparés), et la lecture marque les notes comme lues pour votre contact. Une lecture refusée retourne une liste vide plutôt qu’une erreur.
Étiquettes
Les étiquettes sont des marqueurs légers que votre équipe définit dans l’application OpenWrench (un nom et une couleur optionnelle). Via l’API, vous pouvez lire le catalogue et remplacer les étiquettes appliquées à un bon de travail. La création et la modification des étiquettes elles-mêmes restent dans l’application. Parcourir le catalogue avecGET /v1/buyer/work_order/work_order_labels, ou en récupérer une avec GET /v1/buyer/work_order/work_order_labels/{id}. La liste est restreinte aux étiquettes de votre entreprise et paginée à 10 par page par défaut. Elle accepte les filtres search et label sur le texte de l’étiquette. Passez no_pagination=true pour récupérer tout le catalogue en un seul appel (le tri s’applique toujours).
PUT /v1/buyer/work_order/work_orders/{woId}/labels. Le corps est { "ids": [...] } et il s’agit d’un remplacement complet : les étiquettes non listées sont retirées, et un tableau vide les efface toutes. La réponse liste les associations d’étiquettes désormais actives sur le bon de travail.
- Un
idsmanquant ou qui n’est pas un tableau, ou un id qui n’est pas un nombre entier, est rejeté avec400. - Chaque id doit être une étiquette active de votre propre catalogue. Les ids inconnus ou d’un autre locataire répondent
400avec la liste des ids fautifs. - L’écriture requiert la permission d’écriture sur les bons de travail. Un id de bon de travail inconnu, supprimé ou étranger répond le même
400qu’une écriture refusée, pas un404.
Types de problèmes
GET /v1/buyer/work_order/problem_types liste les types de problèmes configurés pour votre entreprise. Mettez-le en cache : vous avez besoin d’un problemTypeId valide pour chaque bon de travail que vous créez, et l’endpoint classé de fournisseurs en prend un aussi.
Assembler le tout
Une intégration de répartition typique :- Mettez en cache
me, les types de problèmes et les emplacements au démarrage. - Créez le bon de travail avec
supplierFacilityIddéfini (ou créez-le sans fournisseur affecté, puis classez les fournisseurs et effectuez l’affectation parPATCH). - Suivez la progression du fournisseur via les webhooks (
workorder.status_update), en récupérant chaque bon de travail par id à l’arrivée d’un événement. Gardez un appel de liste étroitement filtré (GET /work_orders?isActive=true&locationId=...) comme passe de réconciliation peu fréquente, pas comme signal principal. - Lorsque le fournisseur atteint
WaitingForReview, vérifiez le travail (voir Appels de service pour les preuves de visite) et postezwork_reviewed_and_completed, ouwork_unsatisfactoryavec une note. - Réconciliez le côté monétaire via Soumissions et propositions et Factures.