/v1/buyer/work_order/: att skapa arbetsordrar, söka i dem, köparsidans statusåtgärder, anteckningstråden, etiketterna och problemtyperna.
Alla exempel förutsätter dessa skalvariabler:
Arbetsorderobjektet
En arbetsorder som returneras av API:et bär bland annat följande fält:Skapa en arbetsorder
POST /v1/buyer/work_order/work_orders kräver mer än de uppenbara fälten. Till skillnad från de flesta köparslutpunkter måste buyerFacilityId, buyerCompanyId och createdBy anges i kroppen; de härleds inte från din API-nyckel på den här slutpunkten. Använd GET /v1/buyer/me för att slå upp ditt företags- och anläggnings-id en gång och cacha dem.
Obligatoriska fält: title, locationId, problemTypeId, buyerFacilityId, buyerCompanyId och createdBy (e-postadressen till kontakten som skapar).
- Initial status. Om
statusutelämnas beräknas den initiala statusen från ditt företags konfiguration. Serviceförfrågningar börjar oftast iPendingApproval; arbetsordrar utgår frånUnassigned. Om du skickar enstatuslöses den fortfarande mot företagets konfiguration, så den effektiva statusen kan skilja sig från vad du skickade. - Utskick vid skapande. Att skicka
supplierFacilityIdtilldelar leverantören omedelbart. Ett okäntsupplierFacilityId,assetIdellerproblemTypeIdavvisas med400. - Underliggande tillgångar.
subAssetIdsär en valfri array med ids för underliggande tillgångar som bifogas utöver huvud-assetId. Underliggande tillgångar är tillgångar skapade med ettparentId; se Tillgångar. - Godkännandeflagga. Fältet heter
needApproval, inteneedsApproval. Svarsobjektet använderneedsApproval; själva skapa-förfrågan gör det inte. - Koppling till genomgång.
walkThroughIdochsiteSurveyTaskTitleIdmåste anges tillsammans eller inte alls. Se Platsbesiktningar. - Upserts. Att skicka ett
iduppdaterar den befintliga arbetsordern istället för att skapa en ny.
Lista, filtrera och räkna
offset, limit (standard 10, max 25), sort_by och order. Varje annan frågeparameter läses som ett filter från filterreferensen nedan. Filter kombineras med AND och kombineras alltid med tenant-avgränsningen som härleds från din nyckel, så du ser bara ditt företags arbetsordrar.
Listan och räkningen avgör vilka arbetsordrar som matchar i OpenWrenchs sökindex och laddar sedan de fullständiga posterna från databasen. Det ändrar några beteenden:
- 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 citattecken (search="walk-in cooler") 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,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, så en arbetsorder som skapades för millisekunder 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.
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=Unassigned,PendingApprovalmatchar någon av statusarna.status=Unassigned,PendingApprovalletar efter en enda status med just det namnet och returnerar ingenting. - Ett värde per nyckel. Om du upprepar en parameter (
statuses=Unassigned&statuses=PendingApproval) 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.isStaleochunscheduledOrPastScheduleagerar 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.
buyerCompanyIdsätts alltid från din API-nyckel, så att skicka det har ingen effekt.
00:00:00 och 23:59:59 på samma datum tillsammans med din zon. Den här förfrågan returnerar arbetsordrar som skapades den 9 oktober 2026, Central time:
GET /v1/buyer/work_order/work_orders/{id}.
Tilldela om en leverantör
PATCH /v1/buyer/work_order/work_orders/{id} är avsiktligt smal: endast supplierFacilityId och supplierPrimaryContactEmail läses från kroppen. Alla andra fält du skickar ignoreras tyst istället för att avvisas.
supplierPrimaryContactEmailgäller endast som en del av en omtilldelning. Att skicka den utan en leverantörsanläggningsändring gör att hela patchen blir en no-op: inget sparas och den aktuella arbetsordern returneras.- Ett icke-existerande id och ett behörighetsavslag returnerar båda samma
400-svar (unauthorized), så använd inte den här slutpunkten för att avgöra om en arbetsorder finns.
Köparens statusåtgärder
Fyra dedikerade slutpunkter flyttar en arbetsorder genom de köparägda delarna av livscykeln. Var och en tar samma kropp: arbetsordernsid och en valfri note som läggs till i tråden tillsammans med statusändringen.
Avbokningslås medan en tekniker är incheckad
Företag kan aktivera ett avbokningslås som håller arbetsordrar öppna medan en tekniker är på plats. Med låset aktiverat avvisar OpenWrench varje avbokning med409 Conflict om en tekniker är aktivt incheckad på något av arbetsorderns servicebesök. Detta täcker besök på själva arbetsordern och besök på dess underentreprenad-arbetsordrar. OpenWrench blockerar på samma sätt avbokning av ett underkontrakt vars status propageras till rotarbetsordern, och sparar ingenting på någon av arbetsordrarna.
Låset konfigureras per köparföretag med två inställningar:
Felmeddelandet i
409 identifierar den incheckade teknikern via e-post när besöket registrerade den:
409, vänta tills teknikern checkar ut (eller tills incheckningen blir inaktuell) och försök igen, eller be leverantören avsluta besöket först. Låset är en del av ditt köparföretags arbetsorderkonfiguration i OpenWrench.
Statusmodellen
status-värden du kommer att se och sätta via API:et:
De leverantörsägda övergångarna kommer in via leverantörens egen integration eller OpenWrench-apparna; din sida observerar dem via webhooks eller genom att hämta arbetsordern (
statusChanges innehåller hela historiken) och agerar på de köparägda.
Anteckningar
Arbetsordrar har en delad köpar–leverantör-anteckningstråd. Lägg till medPATCH /v1/buyer/work_order/work_orders/append_notes. Kroppen är { "id": <woId>, "note": { ... } } där anteckningen behöver text och noteAddedBy. Servern skriver över noteAddedAt med sin egen klocka, och författarens e-post läggs till i arbetsorderns lista över köparprenumeranter så att de får efterföljande aviseringar.
taggedUsers bredvid note: en lista med kontakters e-postadresser att @omnämna. 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/buyer/work_order/work_orders/append_notes/bulk. Använd den när du har en uppsättning foton att publicera (en teknikers före/efter-bilder, till exempel): prenumeranter får en enda grupperad avisering istället för en avisering per foto. Kroppen är { "id": <woId>, "notes": [ ... ] } med 1–25 anteckningar, och 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. Att upprepa samma foto-URL i en förfrågan avvisas med 400. Servern stämplar varje anteckning i batchen med samma noteAddedAt och bevarar ordningen du skickade dem i.
GET /v1/buyer/work_order/work_order_notes/{woId}. Detta returnerar bara den grundläggande köpar–leverantör-tråden (entreprenörs- och interna trådar är separata), och läsningen markerar anteckningarna som lästa för din kontakt. En nekad läsning returnerar en tom lista istället för ett fel.
Etiketter
Etiketter är lätta taggar som ditt team definierar i OpenWrench-appen (ett namn plus en valfri färg). Via API:et kan du läsa katalogen och ersätta etiketterna som är applicerade på en arbetsorder. Att skapa eller redigera själva etiketterna sker fortfarande i appen. Bläddra i katalogen medGET /v1/buyer/work_order/work_order_labels, eller hämta en med GET /v1/buyer/work_order/work_order_labels/{id}. Listan är avgränsad till ditt företags etiketter och pagineras med 10 per sida som standard. Den accepterar search- och label-filter på etikettexten. Skicka no_pagination=true för att hämta hela katalogen i ett anrop (sorteringen gäller fortfarande).
PUT /v1/buyer/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.
- Ett saknat
idseller ettidssom inte är en array, eller ett id som inte är ett heltal, avvisas med400. - Varje id måste vara en levande etikett från din egen katalog. Okända eller tenantöverskridande id:n svarar
400med de felande id:na listade. - Skrivningen kräver skrivbehörighet för arbetsordrar. Ett okänt, raderat eller främmande arbetsorder-id svarar med samma
400som en nekad skrivning, inte en404.
Problemtyper
GET /v1/buyer/work_order/problem_types listar de problemtyper som är konfigurerade för ditt företag. Cacha detta: du behöver ett giltigt problemTypeId för varje arbetsorder du skapar, och den rangordnade leverantörsslutpunkten tar också ett.
Sätta ihop det hela
En typisk utskicksintegration:- Cacha
me, problemtyper och platser vid start. - Skapa arbetsordern med
supplierFacilityIdsatt (eller skapa otilldelad, rangordna sedan leverantörer ochPATCHtilldelningen). - Följ leverantörens framsteg via webhooks (
workorder.status_update), och hämta varje arbetsorder via id när en händelse kommer in. Behåll ett snävt filtrerat listanrop (GET /work_orders?isActive=true&locationId=...) som en gles avstämningskörning, inte som den primära signalen. - När leverantören når
WaitingForReview, verifiera arbetet (se Servicebesök för besöksbevis) och postawork_reviewed_and_completed, ellerwork_unsatisfactorymed en anteckning. - Stäm av pengasidan genom Offerter och förslag och Fakturor.