Traiter des bons de travail avec l'API Fournisseur

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

​

Lire votre file

# 1. A webhook delivery tells you which work order changed:
#    { "event_type": "workorder.create", "data": { "workOrderId": 9001, ... } }

# 2. Fetch that work order
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/9001"

# Initial load or reconciliation: filter narrowly, page small, walk with offset
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders?status=PendingConfirmationByServiceProvider,ConfirmedByServiceProvider&limit=25&offset=0&sort_by=createdAt&order=asc"

# Count by filter, without fetching rows
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/count_by?status=ConfirmedByServiceProvider"

• 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.
• 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 une fenêtre 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. Votre propre changement fraîchement écrit, ou un bon de travail assigné il y a quelques secondes, 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.
• 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.

​

Accepter ou refuser

curl -X POST "$BASE/v1/supplier/work_order/work_orders/status_update/confirm" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Accepted. Tech will be scheduled for tomorrow morning.",
      "noteAddedBy": "dispatch@supplier.com",
      "noteAddedAt": "2026-08-21T08:00:00.000-07:00"
    }
  }'

​

Tenir l’acheteur informé

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/estimated_completion_date" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "estimatedCompletionDate": "2026-08-25T17:00:00.000-07:00" }'

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/append_supplier_attachments" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierAttachments": [ { "fileName": "before.jpg", "fileId": "a1b2c3d4e5" } ] }'

​

Notes

curl -X PATCH "$BASE/v1/supplier/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": "Replacement compressor is on site, starting the swap tomorrow.",
      "noteAddedBy": "dispatch@supplier.com"
    },
    "taggedUsers": ["ops@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/supplier/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 -X PUT "$BASE/v1/supplier/work_order/work_orders/9001/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 12] }'

• Chaque id doit être une étiquette active de votre propre catalogue; un ids manquant ou qui n’est pas un tableau, un id non entier, et les ids inconnus ou d’un autre locataire sont tous rejetés avec 400.
• 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 assigné, 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 400 qu’une écriture refusée, pas un 404.

​

Créer un bon de travail à l’initiative du fournisseur

curl -X POST "$BASE/v1/supplier/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Damaged freezer door gasket, found during PM visit",
    "locationId": 1204,
    "description": "Gasket torn along bottom edge; recommend replacement."
  }'

​

Types de problèmes

​

Boucle d’intégration typique

1. Enregistrez un endpoint webhook pour workorder.create et workorder.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é.
2. confirm ou decline dans votre entente de service.
3. Planifiez la visite via les appels de service; publiez des statuts de pièces et une ECD au fil des développements.
4. Complétez via le départ, puis facturez via soumissions et facturation.