Passer au contenu principal
Un appel de service est une visite de technicien sur un bon de travail. L’API Fournisseur pilote l’ensemble du cycle de vie de la visite à travers cinq endpoints de mise à jour de statut ainsi que des expansions de lecture. C’est la partie la plus nuancée de l’API; les détails ci-dessous méritent d’être lus avant d’écrire du code. Tous les exemples supposent :

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 :
La réponse est le bon de travail associé, pas l’appel de service. Chaque appel crée ou met à jour un appel de service, fait avancer le statut du bon de travail, et retourne le bon de travail mis à jour dans l’enveloppe. Lisez le nouvel état de l’appel de service sur les associatedServiceCalls / lastServiceCall du bon de travail.
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.
check_in, check_out et leurs variantes remote_ exigent un id d’appel de service existant. Ils mettent à jour une visite; ils n’en créent pas. Les envoyer sans id retourne 400 InvalidInputException avec "required param: id". Commencez la visite par tech_scheduled. Il crée le premier appel de service et retourne le bon de travail avec le nouvel appel dans associatedServiceCalls / lastServiceCall. Réutilisez cet id à chaque mise à jour ultérieure de la même visite.Le bon de travail doit aussi avoir dépassé l’acceptation avant que tech_scheduled soit valide. S’il est encore à PendingConfirmationByServiceProvider (le statut acheteur « Open - Pending Contractor Confirmation »), acceptez-le d’abord avec POST /v1/supplier/work_order/work_orders/status_update/confirm.

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.
Valeurs courantes de 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.
Pour compléter un bon de travail, quittez avec 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 autoApproveWorkOrdersCompletedByThirdParty activé, un résultat WaitingForReview est 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 sur GET /v1/supplier/work_order/service_calls/{id} :
Pour un rapport de temps à l’échelle de la flotte à travers tous les techniciens, utilisez WrenchMode plutôt que d’itérer sur les appels.

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 appel tech_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.