PT EN

Armazém: Armazém

URL base: $BUSINESS_API

Listar existências

Registos

GET /inventory/balances

What is where: on hand, reserved, available and in transit

Pages the stock balance rows (one per location and item), ordered by location then item, with limit (default 20, max 100) and the after cursor. Narrow with location_id and item_id. Set non_zero=true to skip empty rows, below_reorder=true for rows at or under the reorder level once holds and planned shortfalls are taken off, and short_for_planned=true for rows where planned work orders need more than is available. Needs the inventory:read scope.

Parâmetros

location_idstring · consulta · opcional

One location

item_idstring · consulta · opcional

One item

below_reorderboolean · consulta · opcional

Only balances at or under their reorder level

non_zeroboolean · consulta · opcional

Leave out empty balances

short_for_plannedboolean · consulta · opcional

Only balances whose available stock does not cover the unreserved need of planned work orders

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Balances ordered by location and item

Mostrar atributos
dataarray of InventoryBalance · obrigatório
Mostrar atributos filhos
tenant_idstring · obrigatório
item_idstring · obrigatório
item_codestring · obrigatório
item_namestring · obrigatório
unitstring · obrigatório
location_idstring · obrigatório
location_namestring · obrigatório
on_handnumber · 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).

availablenumber · obrigatório

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

in_transitnumber · obrigatório

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

reorder_levelnumber · opcional

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

planned_shortnumber · opcional

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

below_reorderboolean · obrigatório

Available less planned_short is at or under the reorder level

value_minorinteger (int64) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/balances" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "item_name": "Ana Matsinhe",
      "unit": "unit",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "location_name": "Ana Matsinhe",
      "on_hand": 1,
      "reserved": 1,
      "available": 1,
      "in_transit": 1,
      "reorder_level": 1,
      "planned_short": 1,
      "below_reorder": true,
      "value_minor": 1342,
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Obter a disponibilidade de um artigo

Registos

GET /inventory/availability

Adds up the balances of one item across locations and returns the totals together with the per-location balances. item_id is required (400 when missing, 404 when the item does not exist in this tenant). Pass location_id to limit the answer to one location; without it, only locations with a non-zero on-hand, reserved or in-transit quantity are listed. Needs the inventory:read scope.

Parâmetros

item_idstring · consulta · obrigatório

The item

location_idstring · consulta · opcional

One location; without it every location holding the item

Devolve

200 Availability

Mostrar atributos
item_idstring · obrigatório
on_handnumber · 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).

availablenumber · obrigatório

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

in_transitnumber · obrigatório

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

locationsarray of InventoryBalance · obrigatório
Mostrar atributos filhos
tenant_idstring · obrigatório
item_idstring · obrigatório
item_codestring · obrigatório
item_namestring · obrigatório
unitstring · obrigatório
location_idstring · obrigatório
location_namestring · obrigatório
on_handnumber · 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).

availablenumber · obrigatório

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

in_transitnumber · obrigatório

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

reorder_levelnumber · opcional

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

planned_shortnumber · opcional

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

below_reorderboolean · obrigatório

Available less planned_short is at or under the reorder level

value_minorinteger (int64) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/availability" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "on_hand": 1,
  "reserved": 1,
  "available": 1,
  "in_transit": 1,
  "locations": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "item_name": "Ana Matsinhe",
      "unit": "unit",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "location_name": "Ana Matsinhe",
      "on_hand": 1,
      "reserved": 1,
      "available": 1,
      "in_transit": 1,
      "reorder_level": 1,
      "planned_short": 1,
      "below_reorder": true,
      "value_minor": 1342,
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Dar entrada de stock

Registos

POST /inventory/receipts

Receive stock, with serials for serialised items

Receiving units of a meter item registers each meter in the meter module (device status in_warehouse) and its serial at the location in one action. Each unit cost feeds the moving weighted average cost.

Parâmetros

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

location_idstring · obrigatório
referencestring · opcional

Delivery note

reasonstring · opcional
occurred_atstring (date-time) · opcional
meter_unitstring · opcional

Dial unit of received meters (default m3)

meter_precisioninteger · opcional
linesarray of InventoryMovementLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · opcional

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

serialsarray of string · opcional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · opcional

Receipts only: cost per unit

Devolve

201 Receipt recorded

Mostrar atributos
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
transferobject · opcional
Mostrar atributos filhos
idstring · obrigatório

xfr_ identifier

tenant_idstring · obrigatório
from_location_idstring · obrigatório
to_location_idstring · obrigatório
statusstring · obrigatório

um de in_transit, received

reasonstring · opcional
linesarray of InventoryTransferLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · obrigatório

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

serialsarray of string · opcional
created_bystring · obrigatório
received_bystring · opcional
created_atstring (date-time) · obrigatório
received_atstring (date-time) · opcional
stocktakeobject · opcional
Mostrar atributos filhos
idstring · obrigatório

stk_ identifier

tenant_idstring · obrigatório
location_idstring · obrigatório
statusstring · obrigatório

um de counting, approved

reasonstring · opcional
created_bystring · obrigatório
frozen_atstring (date-time) · obrigatório
approved_bystring · opcional
approval_reasonstring · opcional
approved_atstring (date-time) · opcional
linesarray of InventoryStocktakeLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
expectednumber · obrigatório

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

expected_serialsarray of string · opcional
countednumber · opcional

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

counted_serialsarray of string · opcional
differencenumber · opcional

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

unit_cost_minorinteger (int64) · obrigatório
difference_value_minorinteger (int64) · obrigatório
counted_bystring · opcional
counted_atstring (date-time) · opcional
difference_value_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · opcional
Mostrar atributos filhos
idstring · obrigatório

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/receipts" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reference": "REF-2026-000142",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "meter_unit": "meter unit",
  "meter_precision": 1,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Resposta 201
{
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Dar saída de stock

Registos

POST /inventory/issues

Refused with insufficient_stock when available stock would go below zero, unless the location allows negative stock; a negative balance then raises an alert. Meter serials are issued by installing the meter.

Parâmetros

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

location_idstring · obrigatório
source_typestring · opcional

um de work_order, connection, other

source_idstring · opcional
reasonstring · obrigatório
occurred_atstring (date-time) · opcional
linesarray of InventoryMovementLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · opcional

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

serialsarray of string · opcional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · opcional

Receipts only: cost per unit

Devolve

201 Issue recorded at the average cost

Mostrar atributos
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
transferobject · opcional
Mostrar atributos filhos
idstring · obrigatório

xfr_ identifier

tenant_idstring · obrigatório
from_location_idstring · obrigatório
to_location_idstring · obrigatório
statusstring · obrigatório

um de in_transit, received

reasonstring · opcional
linesarray of InventoryTransferLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · obrigatório

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

serialsarray of string · opcional
created_bystring · obrigatório
received_bystring · opcional
created_atstring (date-time) · obrigatório
received_atstring (date-time) · opcional
stocktakeobject · opcional
Mostrar atributos filhos
idstring · obrigatório

stk_ identifier

tenant_idstring · obrigatório
location_idstring · obrigatório
statusstring · obrigatório

um de counting, approved

reasonstring · opcional
created_bystring · obrigatório
frozen_atstring (date-time) · obrigatório
approved_bystring · opcional
approval_reasonstring · opcional
approved_atstring (date-time) · opcional
linesarray of InventoryStocktakeLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
expectednumber · obrigatório

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

expected_serialsarray of string · opcional
countednumber · opcional

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

counted_serialsarray of string · opcional
differencenumber · opcional

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

unit_cost_minorinteger (int64) · obrigatório
difference_value_minorinteger (int64) · obrigatório
counted_bystring · opcional
counted_atstring (date-time) · opcional
difference_value_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · opcional
Mostrar atributos filhos
idstring · obrigatório

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

Permissões inventory:van:write · Funções: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/issues" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "source_type": "work_order",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Resposta 201
{
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Devolver stock

Registos

POST /inventory/returns

Puts issued stock back into an active location as return movements and responds with status 201. A reason is required; source_type and source_id can point at the work order or record the stock came back from, and occurred_at can backdate the movement. Serialised lines must list serials that are currently issued (409 serial_mismatch otherwise), and they move back in stock at the location. Callers with only the inventory:van:write scope can return only into a van whose members include them. Send an Idempotency-Key header to make retries safe.

Parâmetros

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

location_idstring · obrigatório
source_typestring · opcional

um de work_order, connection, other

source_idstring · opcional
reasonstring · obrigatório
occurred_atstring (date-time) · opcional
linesarray of InventoryMovementLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · opcional

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

serialsarray of string · opcional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · opcional

Receipts only: cost per unit

Devolve

201 Return recorded

Mostrar atributos
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
transferobject · opcional
Mostrar atributos filhos
idstring · obrigatório

xfr_ identifier

tenant_idstring · obrigatório
from_location_idstring · obrigatório
to_location_idstring · obrigatório
statusstring · obrigatório

um de in_transit, received

reasonstring · opcional
linesarray of InventoryTransferLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · obrigatório

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

serialsarray of string · opcional
created_bystring · obrigatório
received_bystring · opcional
created_atstring (date-time) · obrigatório
received_atstring (date-time) · opcional
stocktakeobject · opcional
Mostrar atributos filhos
idstring · obrigatório

stk_ identifier

tenant_idstring · obrigatório
location_idstring · obrigatório
statusstring · obrigatório

um de counting, approved

reasonstring · opcional
created_bystring · obrigatório
frozen_atstring (date-time) · obrigatório
approved_bystring · opcional
approval_reasonstring · opcional
approved_atstring (date-time) · opcional
linesarray of InventoryStocktakeLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
expectednumber · obrigatório

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

expected_serialsarray of string · opcional
countednumber · opcional

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

counted_serialsarray of string · opcional
differencenumber · opcional

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

unit_cost_minorinteger (int64) · obrigatório
difference_value_minorinteger (int64) · obrigatório
counted_bystring · opcional
counted_atstring (date-time) · opcional
difference_value_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · opcional
Mostrar atributos filhos
idstring · obrigatório

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

Permissões inventory:van:write · Funções: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/returns" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "source_type": "work_order",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Resposta 201
{
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Ajustar stock

Registos

POST /inventory/adjustments

Adjust stock found (positive) or missing (negative)

Corrects the on-hand stock at one active location: a positive line quantity records stock found, a negative one removes stock missing, and each line becomes an append-only adjustment movement. Needs the inventory:supervise scope and a reason. For serialised items, the serials you list are created in stock (found) or marked lost (missing). Meters found must come in through a receipt and return 409, as do removals that would take the location below its reserved stock (insufficient_stock) unless it allows negative stock. Movements that carry value raise an inventory.movement.recorded event for the ledger. Send an Idempotency-Key header to make retries safe: a replay returns the stored response with Idempotent-Replayed: true.

Parâmetros

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

location_idstring · obrigatório
reasonstring · obrigatório
linesarray of InventoryMovementLine · obrigatório

A positive quantity adds stock found; a negative one removes stock missing.

Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · opcional

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

serialsarray of string · opcional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · opcional

Receipts only: cost per unit

Devolve

201 Adjustment recorded

Mostrar atributos
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
transferobject · opcional
Mostrar atributos filhos
idstring · obrigatório

xfr_ identifier

tenant_idstring · obrigatório
from_location_idstring · obrigatório
to_location_idstring · obrigatório
statusstring · obrigatório

um de in_transit, received

reasonstring · opcional
linesarray of InventoryTransferLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · obrigatório

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

serialsarray of string · opcional
created_bystring · obrigatório
received_bystring · opcional
created_atstring (date-time) · obrigatório
received_atstring (date-time) · opcional
stocktakeobject · opcional
Mostrar atributos filhos
idstring · obrigatório

stk_ identifier

tenant_idstring · obrigatório
location_idstring · obrigatório
statusstring · obrigatório

um de counting, approved

reasonstring · opcional
created_bystring · obrigatório
frozen_atstring (date-time) · obrigatório
approved_bystring · opcional
approval_reasonstring · opcional
approved_atstring (date-time) · opcional
linesarray of InventoryStocktakeLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
expectednumber · obrigatório

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

expected_serialsarray of string · opcional
countednumber · opcional

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

counted_serialsarray of string · opcional
differencenumber · opcional

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

unit_cost_minorinteger (int64) · obrigatório
difference_value_minorinteger (int64) · obrigatório
counted_bystring · opcional
counted_atstring (date-time) · opcional
difference_value_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · opcional
Mostrar atributos filhos
idstring · obrigatório

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

Permissões inventory:supervise · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/inventory/adjustments" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local.",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Resposta 201
{
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Abater stock danificado

Registos

POST /inventory/scraps

Meter serials are scrapped through POST $BUSINESS_API/meters/{id}/device-status.

Parâmetros

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

location_idstring · obrigatório
reasonstring · obrigatório
linesarray of InventoryMovementLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · opcional

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

serialsarray of string · opcional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · opcional

Receipts only: cost per unit

Devolve

201 Scrap recorded

Mostrar atributos
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
transferobject · opcional
Mostrar atributos filhos
idstring · obrigatório

xfr_ identifier

tenant_idstring · obrigatório
from_location_idstring · obrigatório
to_location_idstring · obrigatório
statusstring · obrigatório

um de in_transit, received

reasonstring · opcional
linesarray of InventoryTransferLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
quantitynumber · obrigatório

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

serialsarray of string · opcional
created_bystring · obrigatório
received_bystring · opcional
created_atstring (date-time) · obrigatório
received_atstring (date-time) · opcional
stocktakeobject · opcional
Mostrar atributos filhos
idstring · obrigatório

stk_ identifier

tenant_idstring · obrigatório
location_idstring · obrigatório
statusstring · obrigatório

um de counting, approved

reasonstring · opcional
created_bystring · obrigatório
frozen_atstring (date-time) · obrigatório
approved_bystring · opcional
approval_reasonstring · opcional
approved_atstring (date-time) · opcional
linesarray of InventoryStocktakeLine · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
expectednumber · obrigatório

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

expected_serialsarray of string · opcional
countednumber · opcional

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

counted_serialsarray of string · opcional
differencenumber · opcional

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

unit_cost_minorinteger (int64) · obrigatório
difference_value_minorinteger (int64) · obrigatório
counted_bystring · opcional
counted_atstring (date-time) · opcional
difference_value_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · opcional
Mostrar atributos filhos
idstring · obrigatório

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 404 · 409

Permissões inventory:supervise · Funções: admin, operations, owner

curl -X POST "$BUSINESS_API/inventory/scraps" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local.",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Resposta 201
{
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Listar movimentos de stock

Registos

GET /inventory/movements

Pages the movements, each one a positive quantity moving into or out of a location (receipt, issue, return, transfer_out, transfer_in, adjustment or scrap). Use limit (default 20, max 100) and the after cursor. Filter by item_id, location_id (matches either side), kind, source_type, source_id, work_order_id, actor_id, and from/to (RFC 3339 or YYYY-MM-DD; from is inclusive, to is exclusive). Needs the inventory:read scope.

Parâmetros

item_idstring · consulta · opcional

One item

location_idstring · consulta · opcional

Movements from or to one location

kindstring · consulta · opcional

Movement kind

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

source_typestring · consulta · opcional

work_order, connection, meter, stocktake, transfer, receipt or other

source_idstring · consulta · opcional

The source record

work_order_idstring · consulta · opcional

Movements serving a work order's material lines

actor_idstring · consulta · opcional

Who recorded it

fromstring · consulta · opcional

Occurred at or after (RFC 3339 or YYYY-MM-DD)

tostring · consulta · opcional

Occurred before (RFC 3339 or YYYY-MM-DD)

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Movements, newest first

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

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/movements" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Localizar um número de série

Registos

GET /inventory/serials/{serial}

Where a meter or device is, and its history

Looks up a serial number (trimmed and matched in upper case) and returns its current status and location, its catalogue item, and every movement it took part in. Status is one of in_stock, in_transit, issued, installed, in_testing, scrapped or lost. Returns 404 when the serial is not registered in this tenant. Needs the inventory:read scope.

Parâmetros

serialstring · caminho · obrigatório

Serial number

Devolve

200 Serial and its movements

Mostrar atributos
serialobject · obrigatório
Mostrar atributos filhos
idstring · obrigatório

ser_ identifier

tenant_idstring · obrigatório
item_idstring · obrigatório
serial_numberstring · obrigatório
statusstring · obrigatório

um de in_stock, in_transit, issued, installed, in_testing, scrapped, lost

location_idstring · opcional
meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

source_typestring · opcional
source_idstring · opcional
unit_cost_minorinteger (int64) · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
itemobject · obrigatório
Mostrar atributos filhos
idstring · obrigatório

itm_ identifier

tenant_idstring · obrigatório
codestring · obrigatório
namestring · obrigatório
descriptionstring · opcional
unitstring · obrigatório

um de un, m, kg, l, cx, rolo

kindstring · obrigatório

um de bulk, serialised

is_meterboolean · obrigatório

Units are meters owned by the meter module

meter_manufacturerstring · opcional
meter_modelstring · opcional
meter_diameter_mminteger · opcional
reorder_levelnumber · obrigatório

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

reorder_levelsarray of InventoryReorderLevel · obrigatório
Mostrar atributos filhos
location_idstring · obrigatório
levelnumber · obrigatório

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

standard_cost_minorinteger (int64) · obrigatório
average_cost_minorinteger (int64) · obrigatório

Moving weighted average cost per unit, in minor units of the tenant currency

activeboolean · obrigatório
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
movementsarray of InventoryMovement · obrigatório
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório

Erros 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/serials/{serial}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "serial": {
    "id": "inv_2PHY0Z5QMxBeY3tSAjLSArbqe1Z",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
    "serial_number": "SER-2026-000142",
    "status": "in_stock",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
    "meter_serial": "meter serial",
    "meter_holder_name": "Ana Matsinhe",
    "source_type": "source type",
    "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
    "unit_cost_minor": 1,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "item": {
    "id": "inv_2gCDJwAl34EFzaahb8GfVEQrV6w",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "code": "COD-2026-000142",
    "name": "Ana Matsinhe",
    "description": "Leitura confirmada no local.",
    "unit": "un",
    "kind": "bulk",
    "is_meter": true,
    "meter_manufacturer": "meter manufacturer",
    "meter_model": "meter model",
    "meter_diameter_mm": 1,
    "reorder_level": 1,
    "reorder_levels": [
      {
        "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
        "level": 1
      }
    ],
    "standard_cost_minor": 1,
    "average_cost_minor": 1,
    "active": true,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Listar reservas de stock

Registos

GET /inventory/reservations

Pages the stock reservations, mostly ones work orders hold for their materials, with limit (default 20, max 100) and the after cursor. Filter by status (held, issued or released), location_id, item_id and work_order_id. Needs the inventory:read scope.

Parâmetros

statusstring · consulta · opcional

held, issued or released

um de held, issued, released

location_idstring · consulta · opcional

One location

item_idstring · consulta · opcional

One item

work_order_idstring · consulta · opcional

One work order

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Reservations

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

rsv_ identifier

tenant_idstring · obrigatório
item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

serial_idstring · opcional
work_order_idstring · opcional
material_line_idstring · opcional

wml_ work-order material line

statusstring · obrigatório

um de held, issued, released

expires_atstring (date-time) · opcional
created_bystring · obrigatório
release_reasonstring · opcional
released_atstring (date-time) · opcional
created_atstring (date-time) · obrigatório
updated_atstring (date-time) · obrigatório
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/reservations" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "inv_25h0mvVwm3z0UVLyavt0YBZ6URl",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "status": "held",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_by": "created by",
      "release_reason": "release reason",
      "released_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Libertar uma reserva de stock

Registos

POST /inventory/reservations/{id}/release

Frees a held reservation so its quantity counts as available again, and records the reason (required) and the release time. Only a reservation in status held can be released: an issued or already released one returns 409. Callers with only the inventory:van:write scope can release holds only in a van whose members include them. Send an Idempotency-Key header to make retries safe.

Parâmetros

idstring · caminho · obrigatório

Reservation ID (rsv_)

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

reasonstring · obrigatório

Devolve

200 Reservation released

Mostrar atributos
idstring · obrigatório

rsv_ identifier

tenant_idstring · obrigatório
item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

serial_idstring · opcional
work_order_idstring · opcional
material_line_idstring · opcional

wml_ work-order material line

statusstring · obrigatório

um de held, issued, released

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

Erros 400 · 401 · 403 · 404 · 409

Permissões inventory:van:write · Funções: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/reservations/{id}/release" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Resposta 200
{
  "id": "inv_25h0mvVwm3z0UVLyavt0YBZ6URl",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "quantity": 1,
  "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
  "status": "held",
  "expires_at": "2026-11-19T09:30:00Z",
  "created_by": "created by",
  "release_reason": "release reason",
  "released_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Listar alertas de stock

Registos

GET /inventory/alerts

The stores work queue: negative balances and items below their reorder level

Returns the open and resolved stock alerts for the tenant, newest work first, paged with limit (default 20, max 100) and the after cursor. An alert has kind negative_balance (raised when a movement takes a location that allows negative stock below zero), below_reorder (raised by the daily reorder scan) or short_for_planned (planned work orders need more than is available). Filter with kind and status (open or resolved). Needs the inventory:read scope.

Parâmetros

kindstring · consulta · opcional

negative_balance, below_reorder or short_for_planned

um de negative_balance, below_reorder, short_for_planned

statusstring · consulta · opcional

open or resolved

um de open, resolved

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Alerts

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

sal_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de negative_balance, below_reorder, short_for_planned

item_idstring · obrigatório
location_idstring · obrigatório
quantitynumber · obrigatório

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

levelnumber · opcional

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

statusstring · obrigatório

um de open, resolved

movement_idstring · opcional
created_atstring (date-time) · obrigatório
resolved_atstring (date-time) · opcional
has_moreboolean · obrigatório
next_cursorstring · opcional

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/alerts" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Importar entradas de stock

Registos

POST /inventory/receipts/import

Import an opening stock or a delivery note from CSV, with a dry run

Columns item_code (or item_id), quantity, unit_cost_minor, serials (serialised items, separated by | or spaces), location_code (or the location_id parameter) and reference; commas or semicolons, with a header row. Every row is checked first: a dry run, or a file with any row in error, writes nothing and answers with each row's errors. A commit receives one receipt per location; the same file imported again records once (the key is the Idempotency-Key, or the file's digest). Meter rows also register each meter.

Parâmetros

dry_runboolean · consulta · opcional

Check every row and report errors without writing anything

location_idstring · consulta · opcional

Receiving location for rows that name none

referencestring · consulta · opcional

Delivery note reference for rows that name none

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

csvstring · obrigatório

The CSV text with a header row

dry_runboolean · opcional
location_idstring · opcional
referencestring · opcional

Devolve

200 Dry run report

Mostrar atributos
dry_runboolean · obrigatório
rowsinteger · obrigatório
validinteger · obrigatório
committedboolean · obrigatório
createdinteger · opcional
updatedinteger · opcional
errorsarray of object · obrigatório
Mostrar atributos filhos
rowinteger · obrigatório

Line number in the file, the header being 1

columnstring · opcional
codestring · obrigatório

um de item_code_missing, item_unknown, item_inactive, location_unknown, location_missing, location_inactive, quantity_invalid, unit_cost_invalid, serials_missing, serials_count_mismatch, serial_repeated, serial_exists, …

parametersobject · opcional

Stable values for client-localized error text, keyed by parameter name.

messagestring · opcional

English compatibility text; use code and parameters for display.

movementsarray of InventoryMovement · opcional
Mostrar atributos filhos
idstring · obrigatório

mvt_ identifier

tenant_idstring · obrigatório
kindstring · obrigatório

um de receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · obrigatório
quantitynumber · obrigatório

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

from_location_idstring · opcional
to_location_idstring · opcional
serial_idstring · opcional
serial_numberstring · opcional
unit_cost_minorinteger (int64) · obrigatório
total_cost_minorinteger (int64) · obrigatório
value_change_minorinteger (int64) · opcional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · opcional
reason_codestring · opcional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · opcional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · opcional
source_idstring · opcional
referencestring · opcional
actor_idstring · obrigatório
work_order_idstring · opcional

Work order whose material line the movement served

material_line_idstring · opcional

wml_ work-order material line

occurred_atstring (date-time) · obrigatório
created_atstring (date-time) · obrigatório
meter_idsarray of string · opcional

Erros 400 · 401 · 403 · 404 · 409 · 413 · 422

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

curl -X POST "$BUSINESS_API/inventory/receipts/import" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "csv": "csv",
  "dry_run": true,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reference": "REF-2026-000142"
}'
Resposta 200
{
  "dry_run": true,
  "rows": 1,
  "valid": 1,
  "committed": true,
  "created": 1,
  "updated": 1,
  "errors": [
    {
      "row": 1,
      "column": "column",
      "code": "item_code_missing",
      "parameters": {
        "key": "value"
      },
      "message": "Leitura confirmada no local."
    }
  ],
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ]
}

Exportar movimentos de stock

Registos

GET /inventory/movements/export

Oldest first within the filters; at most 100000 movements per export, so narrow the dates for more. The last two columns tie each row to the ledger: stock_value_change_minor is what the movement posted to the stock on hand account, and ledger_source_reference is the source reference of its journal entry (empty for a transfer, which posts nothing).

Parâmetros

item_idstring · consulta · opcional

Only movements of this catalogue item ID.

location_idstring · consulta · opcional

Only movements into or out of this location ID; it matches either the source or the destination location.

kindstring · consulta · opcional

Only movements of this kind: receipt, issue, return, transfer_out, transfer_in, adjustment or scrap.

source_typestring · consulta · opcional

Only movements pointing at this kind of source, such as work_order, connection, meter, stocktake, transfer, receipt or other.

source_idstring · consulta · opcional

Only movements pointing at this source record ID, usually combined with source_type.

work_order_idstring · consulta · opcional

Only movements tied to this work order ID.

actor_idstring · consulta · opcional

Only movements recorded by this user ID.

fromstring (date-time) · consulta · opcional

Inclusive lower bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC); any other format returns 400.

tostring (date-time) · consulta · opcional

Exclusive upper bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC, so that day is left out); any other format returns 400.

Devolve

200 text/csv: occurred_at, movement_id, kind, item_code, item_name, unit, quantity, from_location_code, to_location_code, serial_number, unit_cost_minor, total_cost_minor, reason, source_type, source_id, work_order_id, material_line_id, reference, actor_id

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/movements/export" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

text/csv: occurred_at, movement_id, kind, item_code, item_name, unit, quantity, from_location_code, to_location_code, serial_number, unit_cost_minor, total_cost_minor, reason, source_type, source_id, work_order_id, material_line_id, reference, actor_id

Obter as definições do armazém

Registos

GET /inventory/settings

The utility's inventory settings, such as the re-dispatch hold period

Returns the tenant's inventory settings, currently redispatch_hold_days: how long reservations stay held after a work order fails because access was denied, waiting for it to be dispatched again. It also shows who last changed the settings and when. Needs the inventory:read scope.

Devolve

200 Settings

Mostrar atributos
tenant_idstring · obrigatório
redispatch_hold_daysinteger · obrigatório

Days a failed_access_denied order keeps its reservations before they are released

updated_bystring · opcional
updated_atstring (date-time) · opcional

Erros 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/settings" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "redispatch_hold_days": 1,
  "updated_by": "updated by",
  "updated_at": "2026-11-19T09:30:00Z"
}

Actualizar as definições do armazém

Registos

PATCH /inventory/settings

Change how long a failed visit keeps its reservations (14 days by default)

Sets redispatch_hold_days, which must be between 1 and 365 (400 otherwise), and records the caller as the last editor. Leaving the field out keeps the current value. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parâmetros

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

redispatch_hold_daysinteger · opcional

Devolve

200 Settings

Mostrar atributos
tenant_idstring · obrigatório
redispatch_hold_daysinteger · obrigatório

Days a failed_access_denied order keeps its reservations before they are released

updated_bystring · opcional
updated_atstring (date-time) · opcional

Erros 400 · 401 · 403 · 409

Permissões inventory:supervise · Funções: admin, operations, owner

curl -X PATCH "$BUSINESS_API/inventory/settings" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "redispatch_hold_days": 1
}'
Resposta 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "redispatch_hold_days": 1,
  "updated_by": "updated by",
  "updated_at": "2026-11-19T09:30:00Z"
}