Arbeta med arbetsordrar via Supplier 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

​

Läsa din kö

# 1. A webhook delivery tells you which work order changed:
#    { "event_type": "workorder.create", "data": { "workOrderId": 9001, ... } }

# 2. Fetch that work order
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/9001"

# Initial load or reconciliation: filter narrowly, page small, walk with offset
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders?status=PendingConfirmationByServiceProvider,ConfirmedByServiceProvider&limit=25&offset=0&sort_by=createdAt&order=asc"

# Count by filter, without fetching rows
curl -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  "$BASE/v1/supplier/work_order/work_orders/count_by?status=ConfirmedByServiceProvider"

• 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.
• 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å ett statusChangedAt-fönster eller andra indexerade kolumner.
• 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.

​

Acceptera eller avvisa

curl -X POST "$BASE/v1/supplier/work_order/work_orders/status_update/confirm" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 9001,
    "note": {
      "text": "Accepted. Tech will be scheduled for tomorrow morning.",
      "noteAddedBy": "dispatch@supplier.com",
      "noteAddedAt": "2026-08-21T08:00:00.000-07:00"
    }
  }'

​

Håll köparen informerad

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/estimated_completion_date" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "estimatedCompletionDate": "2026-08-25T17:00:00.000-07:00" }'

curl -X PATCH "$BASE/v1/supplier/work_order/work_orders/9001/append_supplier_attachments" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "supplierAttachments": [ { "fileName": "before.jpg", "fileId": "a1b2c3d4e5" } ] }'

​

Anteckningar

curl -X PATCH "$BASE/v1/supplier/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": "Replacement compressor is on site, starting the swap tomorrow.",
      "noteAddedBy": "dispatch@supplier.com"
    },
    "taggedUsers": ["ops@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/supplier/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 -X PUT "$BASE/v1/supplier/work_order/work_orders/9001/labels" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [4, 12] }'

• 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

curl -X POST "$BASE/v1/supplier/work_order/work_orders" \
  -H "X-API-KEY: $KEY" -H "OW-KEY: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Damaged freezer door gasket, found during PM visit",
    "locationId": 1204,
    "description": "Gasket torn along bottom edge; recommend replacement."
  }'

​

Problemtyper

​

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 ECD när saker utvecklas.
4. Slutför via utcheckning och fakturera sedan via offerter och fakturering.