PT EN

Armazém: Artigos

URL base: $BUSINESS_API

Listar artigos

Registos

GET /inventory/items

Pages the tenant's catalogue with limit (default 20, max 100) and the after cursor. Filter by kind (bulk or serialised), is_meter and active (true or 1 for true, any other value for false), and search with q. Needs the inventory:read scope.

Parâmetros

kindstring · consulta · opcional

bulk or serialised

um de bulk, serialised

is_meterboolean · consulta · opcional

Only meter items

activeboolean · consulta · opcional

Only active or inactive items

qstring · consulta · opcional

Resource-specific text search.

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Catalogue items

Mostrar atributos
dataarray of InventoryItem · 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
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/items" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Criar um artigo

Registos

POST /inventory/items

Adds a stock item to the catalogue and returns it with status 201. code (stored upper case, unique per tenant) and name are required; unit defaults to un and must be one of un, m, kg, l, cx or rolo, and kind defaults to bulk. Serialised items, including every item with is_meter set, are counted in un. Reorder levels need distinct, existing locations and values of zero or more. Needs the inventory:supervise scope; a duplicate code returns 409. 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

codestring · obrigatório
namestring · obrigatório
descriptionstring · opcional
unitstring · opcional · predefinição un

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

kindstring · opcional · predefinição bulk

um de bulk, serialised

is_meterboolean · opcional
meter_manufacturerstring · opcional
meter_modelstring · opcional
meter_diameter_mminteger · opcional
reorder_levelnumber · opcional

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

reorder_levelsarray of InventoryReorderLevel · opcional
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) · opcional

Devolve

201 Item created

Mostrar atributos
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

Erros 400 · 401 · 403 · 409

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

curl -X POST "$BUSINESS_API/inventory/items" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "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": 0
}'
Resposta 201
{
  "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"
}

Obter um artigo

Registos

GET /inventory/items/{id}

Returns one catalogue item of the caller's tenant, including its per-location reorder levels, standard and average cost, and meter details. Returns 404 when the item does not exist in this tenant. Needs the inventory:read scope.

Parâmetros

idstring · caminho · obrigatório

Item ID (itm_)

Devolve

200 Item

Mostrar atributos
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

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/items/{id}" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "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"
}

Actualizar um artigo

Registos

PATCH /inventory/items/{id}

Changes only the fields you send: name, description, reorder_level, reorder_levels (replaces the whole list), standard_cost_minor, the meter manufacturer, model and diameter, and active. Code, unit and kind cannot be changed. Negative levels or costs and a blank name return 400, and an unknown item returns 404. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parâmetros

idstring · caminho · obrigatório

Item ID (itm_)

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

namestring · opcional
descriptionstring · opcional
reorder_levelnumber · opcional

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

reorder_levelsarray of InventoryReorderLevel · opcional

Replaces every per-location override.

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) · opcional
meter_manufacturerstring · opcional
meter_modelstring · opcional
meter_diameter_mminteger · opcional
activeboolean · opcional

Devolve

200 Item updated

Mostrar atributos
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

Erros 400 · 401 · 403 · 404

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

curl -X PATCH "$BUSINESS_API/inventory/items/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 0,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "active": true
}'
Resposta 200
{
  "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"
}

Importar artigos

Registos

POST /inventory/items/import

Create and update catalogue items from CSV, matched by code, with a dry run

Columns code, name, unit, kind, description, reorder_level, standard_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, as the catalogue export writes them. A unit or kind never changes on an existing item.

Parâmetros

dry_runboolean · consulta · opcional

Check every row and report errors without writing anything

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 · 409 · 413 · 422

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

curl -X POST "$BUSINESS_API/inventory/items/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 artigos

Registos

GET /inventory/items/export

Downloads the whole catalogue as a text/csv attachment, built in full before it is sent so a failure comes back as a problem response instead of a cut-off file. The columns are code, name, unit, kind, description, reorder_level, standard_cost_minor, average_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, the same header the item import reads. Needs the inventory:read scope.

Devolve

200 text/csv with the catalogue import's columns and average_cost_minor

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/items/export" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200

text/csv with the catalogue import's columns and average_cost_minor