/v1/supplier/work_order/ pour recevoir des travaux, y répondre et tenir les acheteurs informés pendant la progression du travail. La planification des visites et l’achèvement du travail se font via les appels de service.
Tous les exemples supposent :
Lire votre file
Le modèle qui passe à l’échelle est la poussée, puis la récupération par id :offset, limit par défaut 10 max 25, sort_by, 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 tout est restreint à votre établissement.
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. L’endpoint de comptage exécute la même requête que la liste, alors les deux concordent toujours. Comportement à connaître :
- 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. Encadrez la valeur de guillemets doubles 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,assignedAt,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. Votre propre changement fraîchement écrit, ou un bon de travail affecté il y a quelques secondes, 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. - Masquage de données. Si vous êtes un fournisseur tiers (pas l’équipe de service interne d’un acheteur), les champs privés à l’acheteur sont vidés sur les bons de travail, les emplacements et les factures avant que la réponse soit retournée. Les champs manquants sont généralement du masquage, pas des bogues. Voir Données de référence pour les détails.
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=TechScheduled,TechRescheduledcorrespond à l’un ou l’autre statut.status=TechScheduled,TechRescheduledcherche 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=TechScheduled&statuses=TechRescheduled), 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.unscheduledOrPastSchedulen’agit 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. La visibilité d’établissement appliquée à partir de votre clé d’API s’applique toujours, quels que soient les filtres que vous passez.
00:00:00 et 23:59:59 à la même date avec votre fuseau. Cette requête renvoie les bons de travail complétés le 9 octobre 2026, heure du Centre :
Accepter ou refuser
Accepter avecPOST /v1/supplier/work_order/work_orders/status_update/confirm, qui définit le statut à ConfirmedByServiceProvider. Un bon de travail déjà à un statut d’affichage terminé ou clôturé ne peut pas être accepté (400).
POST .../status_update/decline. Seuls les contacts de l’établissement fournisseur affecté au bon de travail peuvent refuser. Le bon de travail quitte votre file via le flux de changement de fournisseur : son statut revient à PendingApproval, ou un fournisseur du réseau privé est choisi automatiquement, selon la configuration de l’acheteur. Le text de la note est enregistré comme raison du refus et se reflète dans ce que voit l’acheteur, alors soyez précis.
Les deux appels prennent { "id": ..., "note": { ... } } et retournent le bon de travail mis à jour. id est l’id numérique du bon de travail (un int64 qui doit exister), et non la chaîne d’affichage woNumber. Envoyez-le comme un nombre JSON, et non comme une chaîne entre guillemets. Pour vérifier la valeur avant l’envoi, récupérez-la avec GET /v1/supplier/work_order/work_orders/{id}.
Il n’existe aucun endpoint status_update de bon de travail pour compléter un travail. Vous complétez le travail par le départ de l’appel de service.
Tenir l’acheteur informé
Trois signaux légers pendant que le travail est en cours : Suivi des pièces. Trois endpoints de statut, avec la même forme de corps{ id, note } que ci-dessus :
Lorsque les équipes internes ne peuvent pas mettre les bons de travail en attente
Un acheteur peut empêcher son équipe de service interne de mettre des bons de travail en attente. Le paramètre par équipe estallowToPlaceWorkOrdersOnHold. Il est activé par défaut, et l’acheteur peut le désactiver pour une équipe interne.
Lorsque le paramètre est désactivé, les clés de l’API Fournisseur qui appartiennent à cette équipe interne ne peuvent pas faire passer un bon de travail à un statut En attente. Les statuts En attente sont WaitingForProposal, WaitingForProposalApproval, PartsRequested, PartsOnOrder et DelayedByThirdParty. Le blocage s’applique à :
POST .../status_update/parts_requestedetPOST .../status_update/parts_ordered.- Le départ de l’appel de service et le départ à distance avec un
checkOutStatusEn attente.
403 et ne modifie rien :
- Changements à l’intérieur ou hors de En attente. Un bon de travail déjà en attente peut passer à un autre statut En attente, par exemple de
PartsRequestedàPartsOnOrder. Il peut aussi sortir de En attente, par exemple avecparts_received. - Fournisseurs tiers. Les clés des fournisseurs tiers ne sont jamais restreintes. Les équipes internes sans ce paramètre ne sont pas restreintes non plus.
- Autres flux. La création de bons de travail, les statuts de sous-traitance et les flux automatiques, comme les demandes de proposition et les soumissions, ne sont pas touchés.
PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date ne lit que estimatedCompletionDate (ISO 8601) dans le corps :
PATCH /v1/supplier/work_order/work_orders/{id}/append_supplier_attachments ajoute des références de fichiers à supplierAttachments, en préservant ce qui s’y trouve déjà. Téléversez d’abord le fichier (voir Fichiers et utilisateurs), puis :
Notes
Ajoutez au fil partagé acheteur-fournisseur avecPATCH /v1/supplier/work_order/work_orders/append_notes ({ "id": ..., "note": { "text", "noteAddedBy", "noteAddedAt" } }), et lisez le fil d’un bon de travail avec GET /v1/supplier/work_order/work_order_notes/{woId}. La lecture met à jour les accusés de lecture pour votre contact, et une lecture refusée retourne une liste vide plutôt qu’une erreur.
Pour @mentionner des personnes sur la note, ajoutez taggedUsers à côté de note : une liste de courriels de contacts. 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/supplier/work_order/work_orders/append_notes/bulk avec { "id": ..., "notes": [ ... ] }. Chaque note doit porter une URL photo et aucun autre contenu : text doit être vide et video, audio, otherFile et elements doivent être absents. Une requête accepte 1 à 25 notes, les URL de photo en double sont rejetées avec 400, et le lot conserve son ordre sous un seul noteAddedAt défini par le serveur. Les abonnés reçoivent une seule notification groupée au lieu d’une notification par photo.
Étiquettes
Les étiquettes de bons de travail sont des marqueurs légers (un nom et une couleur optionnelle) servant à découper la file. Via l’API, vous pouvez lire le catalogue d’étiquettes 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 OpenWrench. Le catalogue que vous voyez dépend de votre clé : une clé appartenant à l’équipe de service interne d’un acheteur voit le catalogue de cette entreprise acheteuse, et la clé d’un fournisseur tiers voit le catalogue de son propre établissement. Parcourir le catalogue avecGET /v1/supplier/work_order/work_order_labels, ou en récupérer une avec GET /v1/supplier/work_order/work_order_labels/{id}. La liste est paginée à 10 par page par défaut et 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.
Remplacer les étiquettes d’un bon de travail avec PUT /v1/supplier/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.
- Chaque id doit être une étiquette active de votre propre catalogue; un
idsmanquant ou qui n’est pas un tableau, un id non entier, et les ids inconnus ou d’un autre locataire sont tous rejetés avec400. - L’écriture requiert la permission d’écriture sur les bons de travail : une clé qui peut seulement voir le bon de travail (un soumissionnaire, ou un établissement avec visibilité en lecture seule) obtient
400. Sur un bon de travail non affecté, seul un établissement avec visibilité en lecture-écriture peut l’étiqueter. - Un id de bon de travail inconnu, supprimé ou étranger répond le même
400qu’une écriture refusée, pas un404.
Créer un bon de travail à l’initiative du fournisseur
Les fournisseurs peuvent ouvrir eux-mêmes des bons de travail (un technicien remarque une porte brisée pendant qu’il est sur place pour autre chose).POST /v1/supplier/work_order/work_orders requiert title et locationId; l’emplacement détermine l’établissement et l’entreprise acheteuse.
problemTypeId retombe sur le premier type de problème feuille de l’entreprise acheteuse de l’emplacement, et woPriorityId sur une priorité par défaut pour cette entreprise. Un assetId, s’il est fourni, doit exister, et son secteur est hérité lorsque areaId n’est pas défini. Le champ est needApproval (sans « s ») sur ce corps de création. Un id dans le corps est ignoré : cet appel crée toujours un nouveau bon de travail.
Le serveur fixe le statut initial. Pour une clé de fournisseur tiers, tout status ou isSupplierInitiated dans le corps est ignoré. Le serveur crée le bon de travail en SupplierInitiatedPendingApproval avec isSupplierInitiated: true. La configuration d’approbation de l’acheteur décide ensuite de sa destination. Lorsque l’acheteur approuve automatiquement les bons de travail à l’initiative du fournisseur, OpenWrench le confirme immédiatement à votre établissement en ConfirmedByServiceProvider. Sinon, il reste en SupplierInitiatedPendingApproval jusqu’à ce qu’un acheteur l’approuve. Les clés appartenant à l’équipe de service interne d’un acheteur, ainsi que les fournisseurs payants qui créent un bon de travail sur l’emplacement d’un client qu’ils gèrent, peuvent définir status. Si ces clés omettent status, OpenWrench dérive le statut initial de la configuration de l’entreprise acheteuse. Une équipe interne arrive en AssignedToInternalTech.
Transferts par l’équipe interne. Une clé d’équipe de service interne peut créer un bon de travail pour un autre établissement fournisseur en envoyant le supplierFacilityId de cet établissement. Cela ne fonctionne que si la configuration de votre établissement autorise le transfert de travail. OpenWrench traite alors la création comme un transfert. Si la requête n’envoie aucun status, ou envoie SupplierInitiatedPendingApproval (comme le fait toujours l’application mobile des sous-traitants), OpenWrench fixe PendingConfirmationByServiceProvider. Le bon de travail va au fournisseur de destination pour confirmation, au lieu de la file d’approbation des travaux à l’initiative du fournisseur de l’acheteur. Un établissement de destination privé correspond toujours à AssignedToInternalTech. OpenWrench conserve le status tel qu’envoyé dans ces cas :
- La requête envoie un autre
statusexplicite. - Le
supplierFacilityIdest votre propre établissement. - La configuration de votre établissement n’autorise pas le transfert de travail.
Types de problèmes
GET /v1/supplier/work_order/problem_types liste les types de problèmes à travers vos entreprises acheteuses liées (non limité en débit). Utilisez-le pour classer correctement les bons de travail à l’initiative du fournisseur, par acheteur.
Boucle d’intégration typique
- Enregistrez un endpoint webhook pour
workorder.createetworkorder.status_update. À chaque livraison, récupérez le bon de travail par id. Faites le chargement initial unique depuis l’endpoint de liste, et gardez celui-ci hors de la boucle en régime permanent, sauf comme sondage filet de sécurité peu fréquent et étroitement filtré. confirmoudeclinedans votre entente de service.- Planifiez la visite via les appels de service; publiez des statuts de pièces et une date d’achèvement estimée au fil des développements.
- Complétez via le départ, puis facturez via soumissions et facturation.