PT EN

Ordens de serviço: Acções

URL base: $BUSINESS_API

Atribuir uma ordem de serviço

Registos

POST /work-orders/{id}/assign

Assigns a crew to a general work order, moves it to assigned and records the status change in its history; when the crew changes, reserved materials move to the new crew. Reassigning an already assigned order only changes the crew. Connection field orders (disconnection, reconnection, new installation, meter exchange) must use dispatch instead and get 409, as does any status that cannot move to assigned. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order to assign; it must not be a connection field order.

Devolve

200 Work order assigned

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/assign" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Work order assigned

Concluir uma ordem de serviço

Registos

POST /work-orders/{id}/complete

Marks a general work order completed, stores the optional notes as its resolution notes, sets completed_at and records the status change in its history. Connection field orders must use execute instead and get 409, and so does an order whose current status cannot move to completed. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order to complete; it must not be a connection field order.

Devolve

200 Work order completed

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/complete" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Work order completed

Obter os metadados de uma ordem de serviço

Registos

GET /work-orders/{id}/metadata

Returns the custom key-value metadata attached to a work order, as resource_type work_order, the resource ID and a metadata map of strings. The work order must exist in the caller's tenant, otherwise 404. Requires business metadata read access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order whose metadata is read.

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

curl -X GET "$BUSINESS_API/work-orders/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Actualizar os metadados de uma ordem de serviço

Registos

PUT /work-orders/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the work order's metadata and returns the full resulting map; keys not mentioned are kept, and a key sent with an empty string value is deleted. Keys are at most 40 characters without square brackets or control characters, values at most 500 characters, and a resource may hold at most 50 keys; violations return 400 with per-key details. The work order must exist in the tenant (404 otherwise). Requires business metadata write access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order whose metadata is merged.

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

curl -X PUT "$BUSINESS_API/work-orders/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Resposta 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Listar o histórico de estados de uma ordem

Registos

GET /work-orders/{id}/status-history

Requires operations:read.

Parâmetros

idstring · caminho · obrigatório

Work order identifier

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Status changes

Mostrar atributos
dataarray of WorkOrderStatusChange · opcional
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
work_order_idstring · opcional
from_statusstring · opcional

Absent on the entry that created the order

to_statusstring · opcional
actor_idstring · opcional
notestring · opcional
note_codestring · opcional

Stable code of a note the server wrote (work_order.generated, work_order.dispatched, work_order.cancel.settled_before_cutoff, work_order.cancel.payment_reversed); clients word it and fall back to note. Absent for notes people typed.

note_paramsobject · opcional

Values the note code fills in: source for work_order.generated, crew for work_order.dispatched.

changed_atstring (date-time) · opcional
has_moreboolean · opcional
next_cursorstring · opcional

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/status-history" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "wor_2I0lP26zrs8XRIe5nuwXV2uhJE0",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "from_status": "from status",
      "to_status": "to status",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "note": "Leitura confirmada no local.",
      "note_code": "NOT-2026-000142",
      "note_params": {
        "key": "value"
      },
      "changed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Enviar uma ordem de serviço a uma brigada

Registos

POST /work-orders/{id}/dispatch

Sends a connection field order to a crew and moves it to dispatched, optionally with a scheduled_for time; give crew_id or set auto_assign to pick the best crew with the required skill. The order must be a field order (400 otherwise), and a crew lacking the required skill, a status that cannot be dispatched, or missing materials for required lines returns 409. A work_order.dispatched event is emitted and the change is recorded in the status history. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

ID of the connection field order to dispatch.

Corpo application/json

crew_idstring · opcional
auto_assignboolean · opcional
scheduled_forstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/dispatch" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "auto_assign": true,
  "scheduled_for": "scheduled for"
}'
Resposta 200

Success

Registar o resultado de uma ordem de serviço

Registos

POST /work-orders/{id}/execute

Record a field order outcome: completed or failed_access_denied

Records the field outcome of a connection field order: result completed or failed_access_denied, with optional executed_at (defaults to now), final reading and notes. Completing a disconnection requires applied_seal_serial and evidence_photo, and a failed_access_denied result requires notes. A work_order.executed event is emitted for downstream processing such as connection status changes; a status that cannot take the result returns 409, and a non-field order returns 400. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

ID of the connection field order whose outcome is recorded.

Corpo application/json

resultstring · opcional
executed_atstring · opcional
applied_seal_serialstring · opcional
evidence_photostring · opcional
final_readingstring · opcional
notesstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/execute" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "result": "result",
  "executed_at": "2026-11-19T09:30:00Z",
  "applied_seal_serial": "applied seal serial",
  "evidence_photo": "evidence photo",
  "final_reading": "final reading",
  "notes": "Leitura confirmada no local."
}'
Resposta 200

Success

Cancelar uma ordem de serviço

Registos

POST /work-orders/{id}/cancel

Cancelling publishes the status change; inventory releases the order's reservations and takes back anything issued to it. Cancelling a cancelled order changes nothing.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

Corpo application/json

reasonstring · obrigatório

Devolve

200 Work order cancelled

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/cancel" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Resposta 200

Work order cancelled

Listar linhas de material de uma ordem

Registos

GET /work-orders/{id}/material-lines

A work order's material lines with availability, reservations, issues, returns and cost

Catalogue lines carry the inventory picture; free-text lines are flagged needs_mapping and touch no stock. Free-text materials recorded before material lines are listed read-only with legacy true.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

Devolve

200 Material lines

Mostrar atributos
dataarray of WorkOrderMaterialLine · obrigatório
Mostrar atributos filhos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/material-lines" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "unit": "unit",
      "planned": 1,
      "reserved": 1,
      "issued": 1,
      "used": 1,
      "returned": 1,
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
      "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
      "needs_mapping": true,
      "legacy": true,
      "stock_status": "reserved",
      "serialised": true,
      "is_meter": true,
      "cost_minor": 1,
      "availability": {
        "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
        "source_location_name": "Ana Matsinhe",
        "available": 1,
        "short": 1,
        "other_locations": [
          {
            "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
            "location_name": "Ana Matsinhe",
            "kind": "active",
            "available": 1
          }
        ]
      },
      "reservations": [
        {
          "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
          "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
          "quantity": 1,
          "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
          "status": "active",
          "expires_at": "2026-11-19T09:30:00Z",
          "created_at": "2026-11-19T09:30:00Z"
        }
      ],
      "suggested_transfer": {
        "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
        "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
        "quantity": 1
      },
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Adicionar linhas de material a uma ordem

Registos

POST /work-orders/{id}/material-lines

Add material lines from a kit or one by one, until the order ends

Adds planned material lines to a work order from a kit (kit_id, or default for the order type's default kit) or from an explicit materials list, and returns 201 with the new lines in a data array. Items already on the order are skipped, and if nothing new remains the request fails with 409; a completed or cancelled order also returns 409. Catalogue items are reserved in inventory when inventory is available. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

Corpo application/json

kit_idstring · opcional
materialsarray of WorkOrderMaterialInput · opcional
Mostrar atributos filhos
item_idstring · opcional

Catalogue item; omit for a free-text part

part_codestring · opcional
descriptionstring · opcional
quantitynumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

unitstring · opcional
requiredboolean · opcional

Blocks dispatch until reserved; defaults to true for meters on installation and replacement orders

source_location_idstring · opcional

Devolve

201 Lines added and reserved where the stock is

Mostrar atributos
dataarray of WorkOrderMaterialLine · obrigatório
Mostrar atributos filhos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "materials": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "quantity": 1,
      "unit": "unit",
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd"
    }
  ]
}'
Resposta 201
{
  "data": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "part_code": "PAR-2026-000142",
      "description": "Leitura confirmada no local.",
      "unit": "unit",
      "planned": 1,
      "reserved": 1,
      "issued": 1,
      "used": 1,
      "returned": 1,
      "required": true,
      "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
      "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
      "needs_mapping": true,
      "legacy": true,
      "stock_status": "reserved",
      "serialised": true,
      "is_meter": true,
      "cost_minor": 1,
      "availability": {
        "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
        "source_location_name": "Ana Matsinhe",
        "available": 1,
        "short": 1,
        "other_locations": [
          {
            "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
            "location_name": "Ana Matsinhe",
            "kind": "active",
            "available": 1
          }
        ]
      },
      "reservations": [
        {
          "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
          "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
          "quantity": 1,
          "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
          "status": "active",
          "expires_at": "2026-11-19T09:30:00Z",
          "created_at": "2026-11-19T09:30:00Z"
        }
      ],
      "suggested_transfer": {
        "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
        "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
        "quantity": 1
      },
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Alterar uma linha de material

Registos

PATCH /work-orders/{id}/material-lines/{line}

Change a line until its material is issued; an item_id maps a free-text line to the catalogue

Changes a material line that has not been issued yet: planned quantity (must be positive), required flag, source location, description (up to 255 characters), or item_id to map a free-text line to a catalogue item. Returns the updated line with its stock picture and syncs inventory reservations. A completed or cancelled order, a line with issued material, remapping a line that already has an item, or an item already on the order returns 409. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

linestring · caminho · obrigatório

Material line ID (wml_)

Corpo application/json

item_idstring · opcional

Maps a free-text line to a catalogue item

quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · opcional
source_location_idstring · opcional
descriptionstring · opcional

Devolve

200 Line changed and its reservation adjusted

Mostrar atributos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X PATCH "$BUSINESS_API/work-orders/{id}/material-lines/{line}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "quantity": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "description": "Leitura confirmada no local."
}'
Resposta 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Remover uma linha de material

Registos

DELETE /work-orders/{id}/material-lines/{line}

Remove a line until its material is issued; its reservations are released

Removes a planned material line from a work order and returns 204; inventory reservations are resynced for catalogue items. A line with material already issued, or an order that is completed or cancelled, returns 409. Requires operations write access.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

linestring · caminho · obrigatório

Material line ID (wml_)

Devolve

204 Line removed

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X DELETE "$BUSINESS_API/work-orders/{id}/material-lines/{line}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 204

Line removed

Dar saída de uma linha de material

Registos

POST /work-orders/{id}/material-lines/{line}/issue

Record material issued to a line, for crews working out of order or offline

A held reservation at the location is consumed, so reserved and issued never count the same units. The location defaults to the line's reservation, then its source. Meters are issued when installed through the meter actions. Replaying the Idempotency-Key records once.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

linestring · caminho · obrigatório

Material line ID (wml_)

Idempotency-Keystring · cabeçalho · opcional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Corpo application/json

quantitynumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

location_idstring · opcional
serialsarray of string · opcional
reasonstring · opcional
occurred_atstring (date-time) · opcional

Devolve

200 Replayed Idempotency-Key; nothing recorded twice

Mostrar atributos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/issue" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "serials": [
    "serial"
  ],
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Resposta 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Registar o material usado

Registos

POST /work-orders/{id}/material-lines/{line}/use

Record the quantity a line actually used, which may differ from planned

Setting the same quantity again changes nothing, so an offline phone can replay it. On a completed order inventory settles the difference: unused issued stock returns to the van or warehouse, and extra use is issued from the van.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

linestring · caminho · obrigatório

Material line ID (wml_)

Corpo application/json

usednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

occurred_atstring (date-time) · opcional

Devolve

200 Use recorded

Mostrar atributos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/use" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "used": 1,
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Resposta 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Registar o material devolvido

Registos

POST /work-orders/{id}/material-lines/{line}/return

Returns issued material from a work order line to stock (quantity, optional location_id, serials, reason and occurred_at) and responds 201 with the updated line. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe: a replay returns 200 with Idempotent-Replayed: true. Free-text lines, unavailable inventory, or returning below a quantity already recorded as used on a completed order return 409.

Parâmetros

idstring · caminho · obrigatório

Work order ID (wko_)

linestring · caminho · obrigatório

Material line ID (wml_)

Idempotency-Keystring · cabeçalho · opcional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Corpo application/json

quantitynumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

location_idstring · opcional
serialsarray of string · opcional
reasonstring · opcional
occurred_atstring (date-time) · opcional

Devolve

200 Replayed Idempotency-Key; nothing recorded twice

Mostrar atributos
idstring · obrigatório

wml_ identifier (wmt_ for a legacy free-text material)

tenant_idstring · obrigatório
work_order_idstring · obrigatório
item_idstring · opcional
item_codestring · opcional
part_codestring · opcional
descriptionstring · opcional
unitstring · opcional
plannednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

issuednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

usednumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

returnednumber · obrigatório

Quantity in the item's unit, with at most three decimals (12.5 metres).

requiredboolean · obrigatório
source_location_idstring · opcional
kit_idstring · opcional
needs_mappingboolean · obrigatório

Free text for a stores person to map; touches no stock

legacyboolean · opcional
stock_statusstring · obrigatório

um de reserved, partially_reserved, short, issued, settled, released, unmapped, untracked

serialisedboolean · opcional
is_meterboolean · opcional
cost_minorinteger (int64) · obrigatório

Issues less returns at average cost

availabilityobject · opcional
Mostrar atributos filhos
source_location_idstring · opcional
source_location_namestring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

shortnumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

other_locationsarray of object · opcional
Mostrar atributos filhos
location_idstring · opcional
location_namestring · opcional
kindstring · opcional
availablenumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reservationsarray of object · opcional
Mostrar atributos filhos
idstring · opcional
location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

serial_idstring · opcional
statusstring · opcional
expires_atstring (date-time) · opcional
created_atstring (date-time) · opcional
suggested_transferobject · opcional
Mostrar atributos filhos
from_location_idstring · opcional
to_location_idstring · opcional
quantitynumber · opcional

Quantity in the item's unit, with at most three decimals (12.5 metres).

created_bystring · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404 · 409

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X POST "$BUSINESS_API/work-orders/{id}/material-lines/{line}/return" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 1,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "serials": [
    "serial"
  ],
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z"
}'
Resposta 200
{
  "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "item_code": "ITE-2026-000142",
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "unit": "unit",
  "planned": 1,
  "reserved": 1,
  "issued": 1,
  "used": 1,
  "returned": 1,
  "required": true,
  "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
  "kit_id": "kit_2uWTnksrliq19iiHpycNpyqZtmS",
  "needs_mapping": true,
  "legacy": true,
  "stock_status": "reserved",
  "serialised": true,
  "is_meter": true,
  "cost_minor": 1,
  "availability": {
    "source_location_id": "sou_2nDQqZJueRPA8hXIWbBOkTVyEfd",
    "source_location_name": "Ana Matsinhe",
    "available": 1,
    "short": 1,
    "other_locations": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "location_name": "Ana Matsinhe",
        "kind": "active",
        "available": 1
      }
    ]
  },
  "reservations": [
    {
      "id": "wor_25hW2XB8sL1GY7V6Y1JgQVD2eLL",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "status": "active",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "suggested_transfer": {
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "quantity": 1
  },
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar materiais de uma ordem

Registos

GET /work-orders/{id}/materials

Lists the simple material records (part code, description, quantity, unit) logged against a work order, oldest first, with cursor pagination (limit defaults to 20, maximum 100) and a total_count. These are separate from inventory-backed material lines. Responds 404 when the work order does not exist and requires operations read access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order whose material records are listed.

limitinteger · consulta · opcional

Maximum resources to return (default 20, maximum 100).

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões operations:read · Funções: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/work-orders/{id}/materials" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

Success

Adicionar material a uma ordem

Registos

POST /work-orders/{id}/materials

Logs a material used on a work order as a simple record and returns 201; part_code and a positive quantity are required, description and unit are optional. The record does not touch inventory stock, unlike material lines. Responds 404 when the work order does not exist and requires operations write access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order the material is logged against.

Corpo application/json

part_codestring · opcional
descriptionstring · opcional
quantityinteger · opcional
unitstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões operations:write · Funções: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/work-orders/{id}/materials" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "part_code": "PAR-2026-000142",
  "description": "Leitura confirmada no local.",
  "quantity": 1,
  "unit": "unit"
}'
Resposta 200

Success