PT EN

Armazém: Contagens de stock

URL base: $BUSINESS_API

Listar contagens de stock

Registos

GET /inventory/stocktakes

Pages the stocktakes with limit (default 20, max 100) and the after cursor. Filter by location_id and by status (counting or approved). Needs the inventory:read scope.

Parâmetros

location_idstring · consulta · opcional

One location

statusstring · consulta · opcional

counting or approved

um de counting, approved

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Stocktakes

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

Abrir uma contagem de stock

Registos

POST /inventory/stocktakes

Opens a stocktake in status counting at an active location, returned with status 201. It records a line for every item with a non-zero balance there, holding the expected quantity, the expected serials for serialised items, and the item's average cost. A reason is optional. Callers with only the inventory:van:write scope can open one only in 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
reasonstring · opcional

Devolve

201 Stocktake opened

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

Erros 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/stocktakes" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local."
}'
Resposta 201
{
  "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"
}

Obter uma contagem de stock

Registos

GET /inventory/stocktakes/{id}

Returns one stocktake with its status, its lines with the expected and counted quantities and serials, who counted each line, and the approval details once approved. Returns 404 when the stocktake does not exist in this tenant. Needs the inventory:read scope.

Parâmetros

idstring · caminho · obrigatório

Stocktake ID (stk_)

Devolve

200 Stocktake

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

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

Registar quantidades contadas

Registos

POST /inventory/stocktakes/{id}/lines

Records 1 to 500 counted lines on a stocktake still in status counting (409 once approved) and returns the updated stocktake. Count bulk items with a quantity of zero or more. Count serialised items by scanning their serials, where the quantity is the number of distinct serials. An item may appear only once per request, and counting it again later replaces the earlier count. The caller is recorded as the counter of each line. Send an Idempotency-Key header to make retries safe.

Parâmetros

idstring · caminho · obrigatório

Stocktake ID (stk_)

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

linesarray of object · obrigatório
Mostrar atributos filhos
item_idstring · obrigatório
countednumber · opcional

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

serialsarray of string · opcional

Scanned serials; for a serialised item they are the count.

Devolve

200 Stocktake with the counts

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

Erros 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/stocktakes/{id}/lines" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "counted": 1,
      "serials": [
        "serial"
      ]
    }
  ]
}'
Resposta 200
{
  "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"
}

Aprovar uma contagem de stock

Registos

POST /inventory/stocktakes/{id}/approve

Turns each counted line's difference from the expected quantity into adjustment movements and marks the stocktake approved. Needs the inventory:supervise scope and a reason. The approver must be someone other than whoever opened the stocktake or counted any line (403). Returns 409 when the stocktake is already approved, when nothing was counted, when expected meters are missing (scrap or locate them first), or when a found serial is registered elsewhere. Send an Idempotency-Key header to make retries safe.

Parâmetros

idstring · caminho · obrigatório

Stocktake ID (stk_)

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 Stocktake approved

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/stocktakes/{id}/approve" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Resposta 200
{
  "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"
    }
  ]
}