Hoppa till huvudinnehåll
För en leverantörsintegration är arbetsorderkön inkorgen. Den här guiden täcker slutpunkterna under /v1/supplier/work_order/ för att ta emot jobb, svara på dem och hålla köpare informerade medan arbetet pågår. Att schemalägga besök och slutföra arbete sker via servicebesök. Alla exempel förutsätter:

Läsa din kö

Bygg inte din integration på list-slutpunkten. GET /v1/supplier/work_order/work_orders är den dyraste läsningen i Supplier API, och att polla den för att upptäcka nya eller ändrade arbetsordrar är fel mönster. Den är långsam på stora köer, den förbrukar din hastighetsgräns och den missar ändå ändringar mellan pollningarna. Använd webhooks för att få veta att en arbetsorder tilldelades dig, bytte status eller fick en anteckning. Hämta sedan just den arbetsordern via id. Reservera listan för en engångsvis initial laddning och tillfällig avstämning, med ett smalt filter och en liten sida.
Mönstret som skalar är push, sedan hämtning via id:
List- och räkningsslutpunkterna är till för de två tillfällen en webhook inte kan täcka. Använd dem för den första laddningen av arbete som redan fanns innan din slutpunkt registrerades. Använd dem också för en periodisk kontroll av att inget har missats:
Standardpaginering gäller (offset, limit standard 10 max 25, sort_by, order). Varje annan frågeparameter läses som ett filter från filterreferensen nedan. Filter kombineras med AND, och allt är tenant-avgränsat till din anläggning. Listan och räkningen avgör vilka arbetsordrar som matchar i OpenWrenchs sökindex och laddar sedan de fullständiga posterna från databasen. Räkningsslutpunkten kör samma fråga som listan, så de två stämmer alltid överens. Beteende att känna till:
  • Fulltextsökning. search= matchar ord (med prefix- och stamformsmatchning) i titeln, beskrivningen, platsnamnet, anteckningarna, servicebesökens in- och utcheckningsanteckningar och problemtypens namn. Den matchar också referensnummer som arbetsordernumret, PO-numret och tillgångens serienummer. Sätt värdet inom dubbla citattecken för att kräva den exakta frasen.
  • Sortering. sort_by stöder createdAt, locationName, woPriority (efter prioritetens förväntade lösningstid) och lastServiceCallServiceScheduledAt. Varje annat värde, eller inget sort_by, sorterar fallande efter createdAt.
  • Okända filter ignoreras. Endast nycklarna i filterreferensen nedan stöds. Varje annan frågeparameter ignoreras istället för att avvisas, och anropet lyckas ändå. Det gäller felstavade nycklar och updatedAtStartDate, updatedAtEndDate, statusChangedAt, assignedAt, buyerFacilityId och walkthroughId, som inte finns i sökindexet. Innan du förlitar dig på ett nytt filter, jämför count_by med och utan det.
  • Färskhet. Uppdateringar av sökindexet och läs-replikan släpar efter skrivningar ett ögonblick. En ändring du just skrivit, eller en arbetsorder som tilldelades för några sekunder sedan, kan tillfälligt saknas i listresultat och räkningar.
  • Pagineringsdjup. offset + limit kan inte överstiga sökresultatfönstret på 10 000. Smalna av filtret istället för att paginera så djupt.
  • Datamaskering. Om du är en tredjepartsleverantör (inte en köpares interna serviceteam) tas köpar-privata fält bort på arbetsordrar, platser och fakturor innan svaret returneras. Saknade fält är oftast maskering, inte buggar. Se Referensdata för detaljer.

Filterreferens

Nycklarna är skiftlägeskänsliga. En nyckel i singular (status) tar ett värde; nyckeln i plural (statuses) tar en kommaseparerad lista och matchar något av värdena; notStatuses utesluter varje listad status. Datumfilter förklaras under regler för filtervärden. Status Vad och var Vem Datum och tidsfrister

Regler för filtervärden

  • Använd pluralnyckeln för flera värden. statuses=TechScheduled,TechRescheduled matchar någon av statusarna. status=TechScheduled,TechRescheduled letar efter en enda status med just det namnet och returnerar ingenting.
  • Ett värde per nyckel. Om du upprepar en parameter (statuses=TechScheduled&statuses=TechRescheduled) används bara den första. Kommaseparera värdena istället.
  • Datum använder MM/dd/yyyy HH:mm:ss, till exempel 08/01/2026 00:00:00. Värdet är en lokal klocktid som läses i den zon du anger i timezone, eller i UTC om den saknas. Tiden är obligatorisk, och båda ändarna av ett fönster är inkluderande. Slutgränser är exakta: OpenWrench avrundar dem inte till slutet av dagen, så skicka 23:59:59 för att ta med en hel dag. URL-koda värdet (curl -G --data-urlencode gör det åt dig). Lägg inte till en offset som -05:00 i värdet: OpenWrench ignorerar den.
  • Ett datum som inte kan tolkas returnerar 400 med Invalid <key>. Expected format MM/dd/yyyy HH:mm:ss. Det gäller även ISO 8601-värden (2026-10-09T00:00:00), datum utan tid (10/09/2026) och värden som bara består av mellanslag. OpenWrench läser fortfarande ett tomt värde som 1 januari 1970.
  • timezone tar ett IANA-zonnamn, som America/Chicago eller UTC. Fasta offset (-05:00, GMT-5), förkortningar (CST) och okända namn returnerar 400. Se Datumformat för sommartid.
  • Booleska värden är true eller false. unscheduledOrPastSchedule agerar bara på true.
  • Värden måste vara välformade. Ett icke-numeriskt id, eller ett booleskt värde annat än true eller false, kan få anropet att misslyckas med 500 istället för 400.
  • Tenant-avgränsningen kan inte åsidosättas. Anläggningssynligheten som tillämpas från din API-nyckel gäller alltid, oavsett vilka filter du skickar.
Om du vill matcha en lokal dag skickar du 00:00:00 och 23:59:59 på samma datum tillsammans med din zon. Den här förfrågan returnerar arbetsordrar som slutfördes den 9 oktober 2026, Central time:

Acceptera eller avvisa

Acceptera med POST /v1/supplier/work_order/work_orders/status_update/confirm, som sätter statusen till ConfirmedByServiceProvider. En arbetsorder som redan är i en avslutad eller stängd visningsstatus kan inte accepteras (400).
Avvisa med POST .../status_update/decline. Endast kontakter tillhörande arbetsorderns tilldelade leverantörsanläggning får avvisa. Arbetsordern lämnar din kö via leverantörsbytesflödet: dess status återgår till PendingApproval, eller så plockas en privat nätverksleverantör automatiskt, beroende på köparens konfiguration. Anteckningens text registreras som avslagsskäl och återspeglas i vad köparen ser, så var specifik. Båda anropen tar { "id": ..., "note": { ... } } och returnerar den uppdaterade arbetsordern. id är arbetsorderns numeriska id (en int64 som måste finnas), inte visningssträngen woNumber. Skicka det som ett JSON-nummer, inte som en sträng inom citattecken. Hämta värdet med GET /v1/supplier/work_order/work_orders/{id} om du vill kontrollera det innan du skickar. Det finns ingen status_update-slutpunkt för arbetsordrar som slutför ett jobb. Du slutför arbetet via utcheckning av servicebesöket.

Håll köparen informerad

Tre lätta signaler medan jobbet pågår: Reservdelsspårning. Tre statusslutpunkter, med samma { id, note }-kroppsform som ovan:

När interna team inte kan sätta arbetsordrar i vänteläge

En köpare kan hindra sitt interna serviceteam från att sätta arbetsordrar i vänteläge. Inställningen per team är allowToPlaceWorkOrdersOnHold. Den är på som standard, och köparen kan stänga av den för ett internt team. När inställningen är av kan Supplier API-nycklar som tillhör det interna teamet inte flytta en arbetsorder till en On Hold-status. On Hold-statusarna är WaitingForProposal, WaitingForProposalApproval, PartsRequested, PartsOnOrder och DelayedByThirdParty. Blockeringen gäller:
  • POST .../status_update/parts_requested och POST .../status_update/parts_ordered.
  • Utcheckning av servicebesök och fjärrutcheckning med en On Hold-checkOutStatus.
Ett blockerat anrop returnerar 403 och ändrar ingenting:
Det här är fortfarande tillåtet:
  • Flyttar inom eller ut ur On Hold. En arbetsorder som redan är i vänteläge kan flyttas till en annan On Hold-status, till exempel från PartsRequested till PartsOnOrder. Den kan också lämna On Hold, till exempel med parts_received.
  • Tredjepartsleverantörer. Nycklar för tredjepartsleverantörer begränsas aldrig. Interna team utan inställningen begränsas inte heller.
  • Andra flöden. Skapande av arbetsordrar, underleverantörsstatusar och automatiska flöden som offertförfrågningar och offerter påverkas inte.
Uppskattat slutdatum. PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date läser endast estimatedCompletionDate (ISO 8601) från kroppen:
Bilagor. PATCH /v1/supplier/work_order/work_orders/{id}/append_supplier_attachments lägger till filreferenser till supplierAttachments och bevarar det som redan finns. Ladda upp filen först (se Filer och användare), sedan:

Anteckningar

Lägg till i den delade köpar–leverantör-tråden med PATCH /v1/supplier/work_order/work_orders/append_notes ({ "id": ..., "note": { "text", "noteAddedBy", "noteAddedAt" } }), och läs en arbetsorders tråd med GET /v1/supplier/work_order/work_order_notes/{woId}. Läsning uppdaterar läskvitton för din kontakt, och en nekad läsning returnerar en tom lista istället för ett fel. För att @omnämna personer i anteckningen, lägg till taggedUsers bredvid note: en lista med kontakters e-postadresser. OpenWrench viker in varje e-postadress i note.elements som ett user-element, samma form som apparna skriver för ett @omnämnande, så du behöver inte bygga elements-strukturen själv. Taggade kontakter läggs till i arbetsorderns prenumerantlista om de inte redan prenumererar.
Regler för taggedUsers:
  • E-postadresser trimmas och görs om till gemener innan matchning. En anteckning kan omnämna högst 25 användare.
  • Dubbletter i listan, och användare som redan är taggade i note.elements, hoppas över istället för att omnämnas två gånger.
  • En post som inte är en giltig e-postadress, eller en lista med fler än 25 e-postadresser, avvisas med 400 av typen invalidInputDataException. Ingenting sparas.
  • En tom lista ignoreras. Att skicka taggedUsers utan ett note-objekt avvisas med 400.
För att publicera en uppsättning foton (en teknikers före/efter-bilder, till exempel), använd PATCH /v1/supplier/work_order/work_orders/append_notes/bulk med { "id": ..., "notes": [ ... ] }. Varje anteckning måste bära en photo-URL och inget annat innehåll: text måste vara tomt och video, audio, otherFile och elements måste utelämnas. En förfrågan tar 1–25 anteckningar, dubblerade foto-URL:er avvisas med 400, och batchen behåller sin ordning under ett enda serversatt noteAddedAt. Prenumeranter får en enda grupperad avisering istället för en avisering per foto.

Etiketter

Arbetsorderetiketter är lätta taggar (ett namn plus en valfri färg) som används för att dela upp kön. Via API:et kan du läsa etikettkatalogen och ersätta etiketterna som är applicerade på en arbetsorder. Att skapa eller redigera själva etiketterna sker fortfarande i OpenWrench-appen. Vilken katalog du ser beror på din nyckel: en nyckel som tillhör en köpares interna serviceteam ser det köparföretagets katalog, och en tredjepartsleverantörs nyckel ser sin egen anläggnings katalog. Bläddra i katalogen med GET /v1/supplier/work_order/work_order_labels, eller hämta en med GET /v1/supplier/work_order/work_order_labels/{id}. Listan pagineras med 10 per sida som standard och accepterar search- och label-filter på etikettexten. Skicka no_pagination=true för att hämta hela katalogen i ett anrop. Ersätt en arbetsorders etiketter med PUT /v1/supplier/work_order/work_orders/{woId}/labels. Kroppen är { "ids": [...] } och det är en fullständig ersättning: etiketter som inte listas tas bort, och en tom array rensar dem alla. Svaret listar de etikettmappningar som nu är aktiva på arbetsordern.
Beteende att känna till:
  • Varje id måste vara en levande etikett från din egen katalog; ett saknat ids eller ett ids som inte är en array, ett id som inte är ett heltal, och okända eller tenantöverskridande id:n avvisas alla med 400.
  • Skrivningen kräver skrivbehörighet för arbetsordrar: en nyckel som endast kan se arbetsordern (en budgivare, eller en anläggning med skrivskyddad synlighet) får 400. På en otilldelad arbetsorder får endast en anläggning med läs- och skrivsynlighet sätta etiketter på den.
  • Ett okänt, raderat eller främmande arbetsorder-id svarar med samma 400 som en nekad skrivning, inte en 404.

Skapa en leverantörsinitierad arbetsorder

Leverantörer kan öppna arbetsordrar själva (en tekniker upptäcker en trasig dörr medan han är på plats för något annat). POST /v1/supplier/work_order/work_orders kräver title och locationId; platsen avgör köparanläggningen och företaget.
Standardvärden vid utelämning: problemTypeId faller tillbaka till den första löv-problemtypen för platsens köparföretag, och woPriorityId till en standardprioritet för det företaget. Ett assetId, om det anges, måste existera, och dess område ärvs när areaId inte är satt. Fältet heter needApproval (utan “s”) i den här skapa-kroppen. Ett id i kroppen ignoreras: det här anropet skapar alltid en ny arbetsorder. Servern sätter den initiala statusen. För en tredjepartsleverantörs nyckel ignoreras status och isSupplierInitiated i kroppen. Servern skapar arbetsordern som SupplierInitiatedPendingApproval med isSupplierInitiated: true. Köparens godkännandekonfiguration avgör sedan var den hamnar. När köparen automatiskt godkänner leverantörsinitierade arbetsordrar bekräftar OpenWrench den direkt till din anläggning som ConfirmedByServiceProvider. Annars stannar den i SupplierInitiatedPendingApproval tills en köpare godkänner den. Två typer av nycklar kan sätta status: nycklar som tillhör en köpares interna serviceteam, och betalande leverantörer som skapar en arbetsorder på en plats hos en kund de förvaltar. Om dessa nycklar utelämnar status härleder OpenWrench den initiala statusen från köparföretagets konfiguration. Ett internt team hamnar i AssignedToInternalTech. Överlämningar från internt team. En nyckel för ett internt serviceteam kan skapa en arbetsorder för en annan leverantörsanläggning genom att skicka den anläggningens supplierFacilityId. Det fungerar bara när din anläggnings konfiguration tillåter överföring av arbete. OpenWrench behandlar då skapandet som en överlämning, precis som en överföring. Om begäran inte skickar någon status, eller skickar SupplierInitiatedPendingApproval (som entreprenörernas mobilapp alltid gör), sätter OpenWrench PendingConfirmationByServiceProvider. Arbetsordern går till mottagande leverantör för bekräftelse i stället för till köparens godkännandekö för leverantörsinitierade arbetsordrar. En privat mottagaranläggning mappas fortfarande till AssignedToInternalTech. OpenWrench behåller status som den skickades i dessa fall:
  • Begäran skickar någon annan uttrycklig status.
  • supplierFacilityId är din egen anläggning.
  • Din anläggnings konfiguration tillåter inte överföring av arbete.

Problemtyper

GET /v1/supplier/work_order/problem_types listar problemtyper över dina relaterade köparföretag (inte hastighetsbegränsad). Använd den för att klassificera leverantörsinitierade arbetsordrar korrekt per köpare.

Typisk integrationsloop

  1. Registrera en webhook-slutpunkt för workorder.create och workorder.status_update. Vid varje leverans, hämta arbetsordern via id. Gör den engångsvisa initiala laddningen från list-slutpunkten, och håll den utanför den löpande loopen förutom som en gles, snävt filtrerad säkerhetspollning.
  2. confirm eller decline inom din SLA.
  3. Schemalägg besöket via servicebesök; posta reservdelsstatusar och ett uppskattat slutdatum när saker utvecklas.
  4. Slutför via utcheckning och fakturera sedan via offerter och fakturering.