Hoppa till huvudinnehåll
Ett servicebesök är ett teknikerbesök mot en arbetsorder. Supplier API driver hela besökets livscykel via fem statusuppdateringsslutpunkter plus läsutökningar. Det här är den mest nyansrika delen av API:et; detaljerna nedan är värda att läsa innan du skriver kod. Alla exempel förutsätter:

Hur statusuppdateringsslutpunkterna fungerar

Alla fem delar samma förfrågan-form (en servicebesöksnyttolast) och ett avgörande beteende:
Svaret är den associerade arbetsordern, inte servicebesöket. Varje anrop skapar eller uppdaterar ett servicebesök, flyttar arbetsorderns status och returnerar den uppdaterade arbetsordern i höljet. Läs det nya servicebesökets tillstånd från arbetsorderns associatedServiceCalls / lastServiceCall.
Delade förfrågningsfält: workOrderId och numberOfTechs krävs alltid. id riktar in sig på ett befintligt servicebesök (utelämna det vid första skapandet, återanvänd sedan id:t för varje senare uppdatering av samma besök). leadTechnicianEmail, additionalTechnicianEmails, serviceScheduledAt, checkIn*/checkOut*-grupperna, partsWithQuantity, stockLocationIds och equipmentPerStockLocationIds fylls i allteftersom besöket fortskrider. supplierFacilityId krävs för nycklar tillhörande interna serviceteam; för tredjeparts leverantörsnycklar skrivs det över med ditt eget anläggnings-id oavsett vad du skickar. Alla sökvägar ligger under /v1/supplier/work_order/. Det finns inga motsvarigheter på köparsidan: incheckning och utcheckning kan inte styras från Buyer API.
check_in, check_out och deras remote_-varianter kräver ett befintligt servicebesöks-id. De uppdaterar ett besök; de skapar inte ett. Att skicka dem utan id returnerar 400 InvalidInputException med "required param: id". Starta besöket med tech_scheduled. Det skapar det första servicebesöket och returnerar arbetsordern med det nya servicebesöket i associatedServiceCalls / lastServiceCall. Återanvänd det id:et vid varje senare uppdatering av samma besök.Arbetsordern måste också ha passerat acceptansen innan tech_scheduled är giltigt. Om den fortfarande är PendingConfirmationByServiceProvider (köparstatusen “Open - Pending Contractor Confirmation”), acceptera den först med POST /v1/supplier/work_order/work_orders/status_update/confirm.

1. Schemalägg besöket

serviceScheduledAt måste vara en ISO 8601 datum-tid med en T-separator och en explicit offset (till exempel 2026-08-22T09:00:00.000-07:00, eller ...Z för UTC). Ett mellanslagsseparerat värde som 2026-08-22 09:00:00+00:00 avvisas som ogiltig indata. Se Datumformat. leadTechnicianEmail är huvudteknikerns e-post för besöket och är typad som en vanlig sträng i schemat. Om en tech_scheduled-förfrågan misslyckas med ett generiskt ohanterat undantag, bekräfta först att arbetsordern har passerat acceptans. Bekräfta sedan att serviceScheduledAt följer ISO 8601-formatet ovan. Båda är vanliga orsaker till ett föga beskrivande tech_scheduled-fel. För att flytta bokningen senare, anropa tech_rescheduled med servicebesökets id och det nya serviceScheduledAt.

2. Checka in

checkInTime sätts som standard till serverns aktuella tid när du sätter en checkInStatus utan tid, så du kan utelämna det i liveintegrationer. Skicka det explicit när du fyller i historiska data. checkInImages tar fotoreferenser och geokoordinater ger köparen bevis på plats.

3. Checka ut och sätt utfallet

Utcheckning är där arbetsorderns nästa status bestäms. checkOutStatus krävs och måste vara ett giltigt namn på arbetsorderstatus; det blir arbetsorderns nya status.
Vanliga värden för checkOutStatus:
En köpare kan stänga av allowToPlaceWorkOrdersOnHold för sitt interna serviceteam. Teamets nycklar kan då inte checka ut med en On Hold-checkOutStatus, till exempel PartsRequested eller PartsOnOrder, om inte arbetsordern redan är i vänteläge. Anropet returnerar 403 ForbiddenException med "Placing work orders on hold is not enabled for this internal team", och servicebesöket sparas inte. Nycklar för tredjepartsleverantörer begränsas aldrig. Se när interna team inte kan sätta arbetsordrar i vänteläge.
Slutför en arbetsorder genom att checka ut med WaitingForReview. WorkReviewedAndCompleted är en status som ägs av köparen. Köparen sätter den efter att ha granskat ditt arbete, eller så sätter OpenWrench den automatiskt när automatiskt godkännande gäller (se nedan). Köparen kan också avvisa arbetet med WorkUnsatisfactory. Du får veta köparens beslut via webhooken workorder.status_update. Registrera delar och lager som förbrukas vid besöket via partsWithQuantity, stockLocationIds och equipmentPerStockLocationIds i samma nyttolast. Id:na kommer från din lagerkatalog. Två automationsbeteenden utlöses vid denna punkt:
  • Auto-godkännande. För tredjepartsleverantörer vars köparföretag har autoApproveWorkOrdersCompletedByThirdParty aktiverat uppgraderas ett WaitingForReview-utfall automatiskt till WorkReviewedAndCompleted.
  • Auto-publicering av fakturor. När den resulterande statusen är WorkReviewedAndCompleted kan regler för auto-publicering av fakturor köras och publicera ditt fakturautkast. Se Offerter och fakturering.
remote_check_in och remote_check_out beter sig identiskt för fjärrarbete.

Läsa tillbaka ett servicebesök

Tre utökningar på GET /v1/supplier/work_order/service_calls/{id}:
För tidsrapportering på flottnivå över alla tekniker, använd WrenchMode istället för att iterera besök.

Jobb med flera besök

En arbetsorder kan bära många servicebesök (diagnos, reparation, uppföljning). Skapa varje besök med sitt eget tech_scheduled-anrop (utan id), och håll varje besöks efterföljande uppdateringar nycklade till dess servicebesöks-id. Checka ut mellanliggande besök med en fortsättningsstatus såsom PartsRequested eller TechScheduled, och bara det slutliga besöket med WaitingForReview.