/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ö
Mönstret som skalar är push, sedan hämtning via id: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_bystödercreatedAt,locationName,woPriority(efter prioritetens förväntade lösningstid) ochlastServiceCallServiceScheduledAt. Varje annat värde, eller ingetsort_by, sorterar fallande eftercreatedAt. - 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,buyerFacilityIdochwalkthroughId, som inte finns i sökindexet. Innan du förlitar dig på ett nytt filter, jämförcount_bymed 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 + limitkan 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,TechRescheduledmatchar någon av statusarna.status=TechScheduled,TechRescheduledletar 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 exempel08/01/2026 00:00:00. Värdet är en lokal klocktid som läses i den zon du anger itimezone, 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å skicka23:59:59för att ta med en hel dag. URL-koda värdet (curl -G --data-urlencodegör det åt dig). Lägg inte till en offset som-05:00i värdet: OpenWrench ignorerar den. - Ett datum som inte kan tolkas returnerar
400medInvalid <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. timezonetar ett IANA-zonnamn, somAmerica/ChicagoellerUTC. Fasta offset (-05:00,GMT-5), förkortningar (CST) och okända namn returnerar400. Se Datumformat för sommartid.- Booleska värden är
trueellerfalse.unscheduledOrPastScheduleagerar bara påtrue. - Värden måste vara välformade. Ett icke-numeriskt id, eller ett booleskt värde annat än
trueellerfalse, kan få anropet att misslyckas med500istället för400. - 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.
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 medPOST /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).
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 ärallowToPlaceWorkOrdersOnHold. 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_requestedochPOST .../status_update/parts_ordered.- Utcheckning av servicebesök och fjärrutcheckning med en On Hold-
checkOutStatus.
403 och ändrar ingenting:
- 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
PartsRequestedtillPartsOnOrder. Den kan också lämna On Hold, till exempel medparts_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.
PATCH /v1/supplier/work_order/work_orders/{id}/estimated_completion_date läser endast estimatedCompletionDate (ISO 8601) från kroppen:
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 medPATCH /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.
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
400av typeninvalidInputDataException. Ingenting sparas. - En tom lista ignoreras. Att skicka
taggedUsersutan ettnote-objekt avvisas med400.
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 medGET /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.
- Varje id måste vara en levande etikett från din egen katalog; ett saknat
idseller ettidssom inte är en array, ett id som inte är ett heltal, och okända eller tenantöverskridande id:n avvisas alla med400. - 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
400som en nekad skrivning, inte en404.
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.
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
- Registrera en webhook-slutpunkt för
workorder.createochworkorder.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. confirmellerdeclineinom din SLA.- Schemalägg besöket via servicebesök; posta reservdelsstatusar och ett uppskattat slutdatum när saker utvecklas.
- Slutför via utcheckning och fakturera sedan via offerter och fakturering.