PT EN

Armazém: Transferências

URL base: $BUSINESS_API

Listar transferências

Registos

GET /inventory/transfers

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

Parâmetros

statusstring · consulta · opcional

in_transit or received

um de in_transit, received

location_idstring · consulta · opcional

Transfers from or to one location

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 Transfers

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

Criar uma transferência

Registos

POST /inventory/transfers

Send stock to another location; it stays in transit until received

Takes stock out of one active location with transfer_out movements and creates a transfer in status in_transit to another location, responding with status 201. The two locations must differ, and serialised lines must list serials in stock at the source. The reason defaults to a standard stock-transfer text. Returns 409 when the source lacks available stock. Callers with only the inventory:van:write scope can send only from 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

from_location_idstring · obrigatório
to_location_idstring · obrigatório
reasonstring · 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 Transfer in transit

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/transfers" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
  "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
  "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"
    }
  ]
}

Obter uma transferência

Registos

GET /inventory/transfers/{id}

Returns one transfer with its source and destination, its lines and serials, its status, and who created and received it. Returns 404 when the transfer does not exist in this tenant. Needs the inventory:read scope.

Parâmetros

idstring · caminho · obrigatório

Transfer ID (xfr_)

Devolve

200 Transfer

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

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

Receber uma transferência

Registos

POST /inventory/transfers/{id}/receive

Books the transfer's lines into the destination location as transfer_in movements, puts its serials back in stock there, and marks the transfer received by the caller. The request takes no body. A transfer that was already received returns 409. Callers with only the inventory:van:write scope can receive only into a van whose members include them. Send an Idempotency-Key header to make retries safe.

Parâmetros

idstring · caminho · obrigatório

Transfer ID (xfr_)

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.

Devolve

200 Transfer received

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 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/transfers/{id}/receive" \
  -H "Authorization: Bearer sk_test_..."
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"
    }
  ]
}