Bons de travail dans l'API Acheteur

export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"        # X-API-KEY header
export SECRET="<shared-secret>"    # OW-KEY header

​

L’objet bon de travail

​

Créer un bon de travail

curl -X POST "$BASE/v1/buyer/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Walk-in cooler not holding temperature",
    "description": "Temp reading 48F, product at risk.",
    "locationId": 1204,
    "assetId": 5511,
    "problemTypeId": 17,
    "woPriorityId": 3,
    "nte": 500,
    "buyerFacilityId": 88,
    "buyerCompanyId": 12,
    "createdBy": "ops@example.com",
    "supplierFacilityId": 3021
  }'

• Statut initial. Si status est omis, le statut initial est calculé à partir de la configuration de votre entreprise. Les demandes de service commencent généralement en PendingApproval; les bons de travail sont par défaut Unassigned. Si vous passez un status, 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 supplierFacilityId affecte le fournisseur immédiatement. Un supplierFacilityId, assetId ou problemTypeId inconnu est rejeté avec 400.
• Sous-actifs. subAssetIds est un tableau optionnel d’ids de sous-actifs attachés en plus de l’assetId principal. Les sous-actifs sont des actifs créés avec un parentId; voir Actifs.
• Drapeau d’approbation. Le champ est needApproval, pas needsApproval. L’objet de réponse utilise needsApproval; la requête de création utilise needApproval.
• Liaison à une visite d’inspection. walkThroughId et siteSurveyTaskTitleId doivent être fournis ensemble ou pas du tout. Voir Visites d’inspection de site.
• Upserts. Passer un id met à jour ce bon de travail existant au lieu d’en créer un nouveau.

​

Lister, filtrer et compter

# Most recent work orders for one location
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders?locationId=1204&limit=25&sort_by=createdAt&order=desc"

# How many match, without fetching them
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders/count_by?locationId=1204"

• 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.
• Les filtres d’actif incluent les sous-actifs. assetId= et assetIds= correspondent aux bons de travail dont l’actif principal ou n’importe quel sous-actif est l’id donné.
• Tri. sort_by prend en charge createdAt, locationName, woPriority (selon le délai de résolution attendu de la priorité) et lastServiceCallServiceScheduledAt. Toute autre valeur, ou l’absence de sort_by, trie par createdAt décroissant.
• Les filtres non indexés sont ignorés. updatedAtStartDate, updatedAtEndDate, buyerFacilityId et walkthroughId ne figurent pas dans l’index de recherche et ne restreignent plus les résultats. Filtrez plutôt sur des fenêtres statusChangedAt ou d’autres colonnes indexées.
• 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 + limit ne 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éaffecter un fournisseur

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/9001" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierFacilityId": 3055, "supplierPrimaryContactEmail": "dispatch@newsupplier.com" }'

• supplierPrimaryContactEmail ne 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 400 non autorisée, alors n’utilisez pas cet endpoint pour sonder l’existence d’un bon de travail.

​

Actions de statut acheteur

curl -X POST "$BASE/v1/buyer/work_order/work_orders/status_update/work_reviewed_and_completed" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Verified on site, closing out.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

​

Verrou d’annulation pendant qu’un technicien est sur place

{
  "message": "You can’t cancel this work order: technician tech@supplier.com is currently checked in."
}

​

Le modèle de statut

​

Notes

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    },
    "taggedUsers": ["tech@supplier.com", "manager@example.com"]
  }'

• 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 400 de type invalidInputDataException. Rien n’est persisté.
• Une liste vide est ignorée. Envoyer taggedUsers sans objet note est rejeté avec 400.

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes/bulk" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "notes": [
      { "text": "", "photo": "https://cdn.example.com/wo-9001/before.jpg" },
      { "text": "", "photo": "https://cdn.example.com/wo-9001/after.jpg" }
    ]
  }'

​

Étiquettes

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_order_labels?no_pagination=true"

curl -X PUT "$BASE/v1/buyer/work_order/work_orders/9001/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 12] }'

• Un ids manquant ou qui n’est pas un tableau, ou un id qui n’est pas un nombre entier, est rejeté avec 400.
• Chaque id doit être une étiquette active de votre propre catalogue. Les ids inconnus ou d’un autre locataire répondent 400 avec 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 400 qu’une écriture refusée, pas un 404.

​

Types de problèmes

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/problem_types"

​

Assembler le tout

1. Mettez en cache me, les types de problèmes et les emplacements au démarrage.
2. Créez le bon de travail avec supplierFacilityId défini (ou créez non assigné, puis classez les fournisseurs et effectuez l’assignation par PATCH).
3. 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 GET /work_orders?statusChangedAt=... comme passe de réconciliation peu fréquente, pas comme signal principal.
4. Lorsque le fournisseur atteint WaitingForReview, vérifiez le travail (voir Appels de service pour les preuves de visite) et postez work_reviewed_and_completed, ou work_unsatisfactory avec une note.
5. Réconciliez le côté monétaire via Soumissions et propositions et Factures.