PT EN

Ordens de serviço: Ordens de serviço

URL base: $BUSINESS_API

Listar ordens de serviço

Registos

GET /work-orders

Lists the tenant's work orders with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). Filters for order type, priority, status, service area, crew, account and connection combine with AND, and q searches the order text and also matches orders of accounts whose holder matches the search. Requires operations read access.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

account_idstring · consulta · opcional

Only orders raised for this account

connection_idstring · consulta · opcional

Only orders raised for this connection

Devolve

200 Work orders

Mostrar atributos
dataarray of WorkOrder · obrigatório
Mostrar atributos filhos
idstring · opcional
tenant_idstring · opcional
order_numberstring · opcional
order_typestring · opcional
prioritystring · opcional
statusstring · opcional
account_idstring · opcional
account_numberstring · opcional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · opcional

Display name of the customer who holds the referenced account. Omitted when unknown.

connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · opcional
has_moreboolean · obrigatório
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" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "order_number": "ORD-2026-000142",
      "order_type": "order type",
      "priority": "priority",
      "status": "active",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
      "connection_holder_name": "Ana Matsinhe",
      "description": "Leitura confirmada no local."
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Criar uma ordem de serviço

Registos

POST /work-orders

Create a field work order, with its material lines from a kit or one by one

Materials are planned when the order is created (RFC 0071 section 5.3). kit_id fills the lines from a kit (default picks the kit set for the order type); materials add catalogue items or free-text parts, or adjust a kit line (quantity 0 removes it). Meters are required lines by default on installation and replacement orders. Lines are reserved at the natural source (the crew's van, the service area's warehouse, the main warehouse); a shortage is a warning in the response, never a refusal. Without materials, proposed_kit_id offers the order type's default kit.

Corpo application/json

order_typestring · obrigatório
prioritystring · opcional
asset_idstring · opcional
service_area_idstring · opcional
account_idstring · opcional
crew_idstring · opcional
descriptionstring · obrigatório
scheduled_atstring (date-time) · opcional
connection_idstring · opcional
required_skillstring · opcional
kit_idstring · opcional

A kit (kit_), or default for the order type's default kit

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 Work order created, with each material line's availability and reservation

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
order_numberstring · obrigatório
order_typestring · obrigatório
prioritystring · obrigatório
statusstring · obrigatório
crew_idstring · opcional
service_area_idstring · opcional
connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
material_linesarray of WorkOrderMaterialLine · opcional
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
material_cost_minorinteger (int64) · opcional

Cost of the materials used, at average cost; per new connection on its installation order

proposed_kit_idstring · opcional

Default kit for the order type, offered when created without materials

Erros 400 · 403

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

curl -X POST "$BUSINESS_API/work-orders" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "order_type": "order type",
  "priority": "priority",
  "asset_id": "ass_2IIXBYi79uuRV0QXd685rmSLhO0",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "description": "Leitura confirmada no local.",
  "scheduled_at": "2026-11-19T09:30:00Z",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "required_skill": "required skill",
  "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
{
  "id": "wor_2oUz9aQ9Pk2Rnyu1nAG9ZoClFso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "order_number": "ORD-2026-000142",
  "order_type": "order type",
  "priority": "priority",
  "status": "active",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "material_lines": [
    {
      "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"
    }
  ],
  "material_cost_minor": 1,
  "proposed_kit_id": "pro_2xh4kVlEItn0iXlimBdSi5r4MzJ"
}

Obter uma ordem de serviço

Registos

GET /work-orders/{id}

Get work order details, with material lines and material cost

Returns one work order with its status, crew, schedule, execution details and its material lines. Responds 404 when the order is not in the caller's tenant. Requires operations read access.

Parâmetros

idstring · caminho · obrigatório

ID of the work order in the caller's tenant.

Devolve

200 Work order details; material_lines and material_cost_minor appear when the order has materials

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
order_numberstring · obrigatório
order_typestring · obrigatório
prioritystring · obrigatório
statusstring · obrigatório
crew_idstring · opcional
service_area_idstring · opcional
connection_idstring · opcional
connection_holder_namestring · opcional

Display name of the customer who holds the referenced connection. Omitted when unknown.

descriptionstring · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
material_linesarray of WorkOrderMaterialLine · opcional
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
material_cost_minorinteger (int64) · opcional

Cost of the materials used, at average cost; per new connection on its installation order

proposed_kit_idstring · opcional

Default kit for the order type, offered when created without materials

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

curl -X GET "$BUSINESS_API/work-orders/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "id": "wor_2oUz9aQ9Pk2Rnyu1nAG9ZoClFso",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "order_number": "ORD-2026-000142",
  "order_type": "order type",
  "priority": "priority",
  "status": "active",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "connection_holder_name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "material_lines": [
    {
      "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"
    }
  ],
  "material_cost_minor": 1,
  "proposed_kit_id": "pro_2xh4kVlEItn0iXlimBdSi5r4MzJ"
}