Comment fonctionnent les endpoints de mise à jour de statut
Les cinq partagent une même forme de requête (une charge utile d’appel de service) et un comportement crucial : Champs de requête partagés :workOrderId et numberOfTechs sont toujours requis. id cible un appel de service existant (omettez-le à la première création, puis réutilisez l’id pour chaque mise à jour ultérieure de la même visite). leadTechnicianEmail, additionalTechnicianEmails, serviceScheduledAt, les groupes checkIn*/checkOut*, partsWithQuantity, stockLocationIds et equipmentPerStockLocationIds se remplissent à mesure que la visite progresse.
supplierFacilityId est requis pour les clés d’équipes de service internes; pour les clés de fournisseur tiers, il est écrasé par votre propre id d’établissement peu importe ce que vous envoyez.
Tous les chemins sont sous
/v1/supplier/work_order/. Il n’existe pas d’équivalents côté acheteur : l’arrivée et le départ ne peuvent pas être pilotés depuis l’API Acheteur.
1. Planifier la visite
serviceScheduledAt doit être une date-heure ISO 8601 avec un séparateur T et un décalage explicite (par exemple, 2026-08-22T09:00:00.000-07:00, ou ...Z pour UTC). Une valeur séparée par une espace comme 2026-08-22 09:00:00+00:00 est rejetée comme entrée invalide. Voir Formats de date.
leadTechnicianEmail est le courriel du technicien principal affecté à la visite et est typé comme une simple chaîne dans le schéma. Si une requête tech_scheduled échoue avec une exception non gérée générique, confirmez d’abord que le bon de travail a dépassé l’acceptation. Confirmez ensuite que serviceScheduledAt respecte le format ISO 8601 ci-dessus. Ces deux causes sont les plus fréquentes d’un échec peu descriptif de tech_scheduled.
Pour déplacer le rendez-vous plus tard, appelez tech_rescheduled avec l’id de l’appel de service et le nouveau serviceScheduledAt.
2. S’enregistrer
checkInTime prend par défaut l’heure actuelle du serveur lorsque vous définissez un checkInStatus sans heure, alors vous pouvez l’omettre dans les intégrations en direct. Passez-le explicitement lors d’un remplissage rétroactif. checkInImages prend des références de photo, et les coordonnées géographiques donnent à l’acheteur une preuve de présence sur place.
3. Quitter et définir le résultat
C’est au départ que se décide le prochain statut du bon de travail.checkOutStatus est requis et doit être un nom de statut de bon de travail valide; il devient le nouveau statut du bon de travail.
checkOutStatus :
Un acheteur peut désactiver
allowToPlaceWorkOrdersOnHold pour son équipe de service interne. Les clés de cette équipe ne peuvent alors pas quitter avec un checkOutStatus En attente, comme PartsRequested ou PartsOnOrder, sauf si le bon de travail est déjà en attente. L’appel retourne 403 ForbiddenException avec "Placing work orders on hold is not enabled for this internal team", et l’appel de service n’est pas enregistré. Les clés des fournisseurs tiers ne sont jamais restreintes. Consultez lorsque les équipes internes ne peuvent pas mettre les bons de travail en attente.WaitingForReview. WorkReviewedAndCompleted est un statut qui appartient à l’acheteur. L’acheteur le définit après avoir révisé votre travail, ou OpenWrench le définit automatiquement lorsque l’approbation automatique s’applique (voir ci-dessous). L’acheteur peut aussi rejeter le travail avec WorkUnsatisfactory. Vous apprenez la décision de l’acheteur par le webhook workorder.status_update.
Enregistrez les pièces et le stock consommés durant la visite via partsWithQuantity, stockLocationIds et equipmentPerStockLocationIds dans la même charge utile. Les ids proviennent de votre catalogue d’inventaire.
Deux comportements d’automatisation se déclenchent à ce moment :
- Approbation automatique. Pour les fournisseurs tiers dont l’entreprise acheteuse a
autoApproveWorkOrdersCompletedByThirdPartyactivé, un résultatWaitingForReviewest automatiquement promu àWorkReviewedAndCompleted. - Publication automatique de facture. Chaque fois que le statut résultant est
WorkReviewedAndCompleted, les règles de publication automatique de facture peuvent s’exécuter et publier votre brouillon de facture. Voir Soumissions et facturation.
remote_check_in et remote_check_out se comportent de façon identique pour le travail effectué hors site.
Relire un appel de service
Trois expansions surGET /v1/supplier/work_order/service_calls/{id} :
Travaux à plusieurs visites
Un même bon de travail peut porter plusieurs appels de service (diagnostic, réparation, suivi). Créez chaque visite avec son propre appeltech_scheduled (sans id), et gardez les mises à jour subséquentes de chaque visite indexées sur l’id de son appel de service. Quittez les visites intermédiaires avec un statut de continuation tel que PartsRequested ou TechScheduled, et seulement la visite finale avec WaitingForReview.