Arbetsordrar i Buyer API

export BASE="https://api.useopenwrench.com/api/external"
export KEY="<your-api-key>"        # X-API-KEY header
export SECRET="<shared-secret>"    # OW-KEY header

​

Arbetsorderobjektet

​

Skapa en arbetsorder

curl -X POST "$BASE/v1/buyer/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Walk-in cooler not holding temperature",
    "description": "Temp reading 48F, product at risk.",
    "locationId": 1204,
    "assetId": 5511,
    "problemTypeId": 17,
    "woPriorityId": 3,
    "nte": 500,
    "buyerFacilityId": 88,
    "buyerCompanyId": 12,
    "createdBy": "ops@example.com",
    "supplierFacilityId": 3021
  }'

• Initial status. Om status utelämnas beräknas den initiala statusen från ditt företags konfiguration. Serviceförfrågningar börjar oftast i PendingApproval; arbetsordrar utgår från Unassigned. Om du skickar en status löses den fortfarande mot företagets konfiguration, så den effektiva statusen kan skilja sig från vad du skickade.
• Utskick vid skapande. Att skicka supplierFacilityId tilldelar leverantören omedelbart. Ett okänt supplierFacilityId, assetId eller problemTypeId avvisas med 400.
• 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 ett parentId; se Tillgångar.
• Godkännandeflagga. Fältet heter needApproval, inte needsApproval. Svarsobjektet använder needsApproval; själva skapa-förfrågan gör det inte.
• Koppling till genomgång. walkThroughId och siteSurveyTaskTitleId måste anges tillsammans eller inte alls. Se Platsbesiktningar.
• Upserts. Att skicka ett id uppdaterar den befintliga arbetsordern istället för att skapa en ny.

​

Lista, filtrera och räkna

# Most recent work orders for one location
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders?locationId=1204&limit=25&sort_by=createdAt&order=desc"

# How many match, without fetching them
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_orders/count_by?locationId=1204"

• 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.
• Tillgångsfilter inkluderar underliggande tillgångar. assetId= och assetIds= matchar arbetsordrar vars huvudtillgång eller någon underliggande tillgång är det angivna id:t.
• 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.
• Oindexerade filter ignoreras. updatedAtStartDate, updatedAtEndDate, buyerFacilityId och walkthroughId finns inte i sökindexet och smalnar inte längre av resultaten. Filtrera istället på statusChangedAt-fönster eller andra indexerade kolumner.
• 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 + limit kan inte överstiga sökresultatfönstret på 10 000. Smalna av filtret istället för att paginera så djupt.

​

Tilldela om en leverantör

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/9001" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierFacilityId": 3055, "supplierPrimaryContactEmail": "dispatch@newsupplier.com" }'

• supplierPrimaryContactEmail gä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

curl -X POST "$BASE/v1/buyer/work_order/work_orders/status_update/work_reviewed_and_completed" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Verified on site, closing out.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

​

Avbokningslås medan en tekniker är incheckad

{
  "message": "You can’t cancel this work order: technician tech@supplier.com is currently checked in."
}

​

Statusmodellen

​

Anteckningar

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    }
  }'

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Access code for the back door is 4417.",
      "noteAddedBy": "ops@example.com",
      "noteAddedAt": "2026-08-21T09:00:00.000-07:00"
    },
    "taggedUsers": ["tech@supplier.com", "manager@example.com"]
  }'

• 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.

curl -X PATCH "$BASE/v1/buyer/work_order/work_orders/append_notes/bulk" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "notes": [
      { "text": "", "photo": "https://cdn.example.com/wo-9001/before.jpg" },
      { "text": "", "photo": "https://cdn.example.com/wo-9001/after.jpg" }
    ]
  }'

​

Etiketter

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/work_order_labels?no_pagination=true"

curl -X PUT "$BASE/v1/buyer/work_order/work_orders/9001/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 12] }'

• Ett saknat ids eller ett ids som inte är en array, eller ett id som inte är ett heltal, avvisas med 400.
• Varje id måste vara en levande etikett från din egen katalog. Okända eller tenantöverskridande id:n svarar 400 med 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 400 som en nekad skrivning, inte en 404.

​

Problemtyper

curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/buyer/work_order/problem_types"

​

Sätta ihop det hela

1. Cacha me, problemtyper och platser vid start.
2. Skapa arbetsordern med supplierFacilityId satt (eller skapa otilldelad, rangordna sedan leverantörer och PATCH tilldelningen).
3. 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 GET /work_orders?statusChangedAt=... som en gles avstämningskörning, inte som den primära signalen.
4. När leverantören når WaitingForReview, verifiera arbetet (se Servicebesök för besöksbevis) och posta work_reviewed_and_completed, eller work_unsatisfactory med en anteckning.
5. Stäm av pengasidan genom Offerter och förslag och Fakturor.