VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Armazém e separação

Saldos por endereço

Consulta o saldo por endereço, registra contagens físicas, move unidades entre endereços e lê o histórico desses lançamentos.

Listar saldos por endereço

Mostra quantas unidades de cada produto há em cada endereço. Só aparecem endereços não apagados. Não há paginação.

GET/api/v1/vendor/erp/wms/stockSeller

Lista o saldo por endereço

Parâmetros de consulta

warehouse_iduuid
Só endereços deste depósito.
location_iduuid
Só este endereço.
product_iduuid
Só este produto.

Exemplo de requisição: Listar saldos por endereço

bash
curl "$BASE_URL/api/v1/vendor/erp/wms/stock?location_id=252212c1-0771-450f-b2e3-a31edfb30fe3" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar saldos por endereço

200Saldos retornados
json
{
  "stock": [
    {
      "id": "7b3c2a10-5d1e-4f60-8a9b-0c1d2e3f4a5b",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "location_id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
      "location_code": "A-01-03",
      "location_type": "bin",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "warehouse_name": "Depósito Central",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "qty": 12,
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

stockarray

Linhas de saldo.

iduuid
Id da linha de saldo.
vendor_iduuid
Seller dono.
location_iduuid
Endereço.
location_codestring
Código do endereço.
location_typestring
aisleshelfbin
Nível do endereço.
warehouse_iduuid
Depósito do endereço.
warehouse_namestring
Nome do depósito.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Unidades deste produto neste endereço.
updated_atdatetime
Última alteração.
totalinteger
Quantidade devolvida.

Erros: Listar saldos por endereço

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list bin stock","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Registrar contagem

Informa quantas unidades de um produto existem de fato num endereço (inventário). O saldo do endereço passa a ser exatamente qty. Se a contagem difere do esperado, a diferença também é lançada como ajuste no saldo do depósito do ERP de estoque.

POST/api/v1/vendor/erp/wms/stock/countSeller

Registra uma contagem física

Corpo da requisição

location_iduuidobrigatório
Endereço contado.
product_iduuidobrigatório
Produto contado.
qtyintegerobrigatório
Quantidade contada, zero ou mais. É o saldo final, não uma diferença.

Exemplo de requisição: Registrar contagem

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/wms/stock/count" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "qty": 12
}'

Resposta: Registrar contagem

200Saldo do endereço depois da contagem
json
{
  "id": "7b3c2a10-5d1e-4f60-8a9b-0c1d2e3f4a5b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "location_id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
  "location_code": "A-01-03",
  "location_type": "bin",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "warehouse_name": "Depósito Central",
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "product_name": "Camiseta Básica Preta M",
  "qty": 12,
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id da linha de saldo.
vendor_iduuid
Seller dono.
location_iduuid
Endereço.
location_codestring
Código do endereço.
location_typestring
aisleshelfbin
Nível do endereço.
warehouse_iduuid
Depósito do endereço.
warehouse_namestring
Nome do depósito.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Unidades deste produto neste endereço.
updated_atdatetime
Última alteração.

Erros: Registrar contagem

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400location_id ausente.{"error":"vendorerp: location_id required"}
400product_id ausente.{"error":"vendorerp: product_id required"}
400qty negativa.{"error":"vendorerp: qty must be >= 0"}
404O endereço não existe ou é de outro seller.{"error":"location not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}
Contagem mexe no saldo do depósito sem trava

O ajuste de depósito feito pela contagem soma o delta direto no saldo e não passa pela trava de saldo negativo do movimento de estoque. Também não atualiza o estoque do catálogo. Confira os saldos depois de contagens grandes.

Mover entre endereços

Tira unidades de um endereço e põe em outro, na mesma transação. Se os dois endereços estão em depósitos diferentes, a plataforma também transfere o saldo entre os depósitos no ERP de estoque.

POST/api/v1/vendor/erp/wms/stock/moveSeller

Move unidades entre endereços

Corpo da requisição

product_iduuidobrigatório
Produto movido.
from_location_iduuidobrigatório
Endereço de origem.
to_location_iduuidobrigatório
Endereço de destino, diferente da origem.
qtyintegerobrigatório
Unidades, maior que zero.

Exemplo de requisição: Mover entre endereços

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/wms/stock/move" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "from_location_id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
  "to_location_id": "4e7b0a0f-1c11-4c3d-b402-6860b2bd6460",
  "qty": 3
}'

Resposta: Mover entre endereços

200Saldo do endereço de destino
json
{
  "id": "7b3c2a10-5d1e-4f60-8a9b-0c1d2e3f4a5b",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "location_id": "4e7b0a0f-1c11-4c3d-b402-6860b2bd6460",
  "location_code": "A-01-04",
  "location_type": "bin",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "warehouse_name": "Depósito Central",
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "product_name": "Camiseta Básica Preta M",
  "qty": 3,
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id da linha de saldo.
vendor_iduuid
Seller dono.
location_iduuid
Endereço.
location_codestring
Código do endereço.
location_typestring
aisleshelfbin
Nível do endereço.
warehouse_iduuid
Depósito do endereço.
warehouse_namestring
Nome do depósito.
product_iduuid
Produto.
product_namestring
Nome do produto.
qtyinteger
Unidades deste produto neste endereço.
updated_atdatetime
Última alteração.

Erros: Mover entre endereços

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400Falta um dos endereços.{"error":"vendorerp: from_location_id and to_location_id required"}
400Origem igual ao destino.{"error":"vendorerp: from and to must differ"}
400qty menor ou igual a zero.{"error":"vendorerp: qty must be positive"}
400A origem não tem unidades suficientes do produto.{"error":"insufficient stock at source location"}
404O endereço não existe ou é de outro seller.{"error":"location not found"}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Listar histórico

O histórico guarda cada contagem e cada movimentação entre endereços, do mais novo para o mais antigo.

GET/api/v1/vendor/erp/wms/movementsSeller

Lista o histórico de lançamentos de endereço

Parâmetros de consulta

warehouse_iduuid
Só este depósito.
location_iduuid
Só este endereço.
product_iduuid
Só este produto.
kindstring
countmove_inmove_out
Tipo de lançamento. Valor desconhecido devolve lista vazia.
pageintegerpadrão: 1
Página, a partir de 1. Valor inválido ou menor que 1 volta para 1.
per_pageintegerpadrão: 50
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar histórico

bash
curl "$BASE_URL/api/v1/vendor/erp/wms/movements?kind=count" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar histórico

200Histórico retornado
json
{
  "movements": [
    {
      "id": "743a1bc1-8989-4755-b27a-6818c219ab7c",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "location_id": "252212c1-0771-450f-b2e3-a31edfb30fe3",
      "location_code": "A-01-03",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "warehouse_name": "Depósito Central",
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "kind": "count",
      "delta": -2,
      "balance_after": 12,
      "expected_qty": 14,
      "counted_qty": 12,
      "stock_synced": true,
      "reason": "Contagem física",
      "reference": "",
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

movementsarray

Lançamentos da página.

iduuid
Id do movimento de endereço.
vendor_iduuid
Seller dono.
location_iduuid
Endereço afetado.
location_codestring
Código do endereço.
warehouse_iduuid
Depósito do endereço.
warehouse_namestring
Nome do depósito.
product_iduuid
Produto.
product_namestring
Nome do produto.
kindstring
countmove_inmove_out
Origem do lançamento.
deltainteger
Variação aplicada ao endereço (negativa na saída).
balance_afterinteger
Saldo do endereço depois do lançamento.
expected_qtyinteger
Só em count: o saldo que o sistema esperava antes da contagem. Ausente nos demais.
counted_qtyinteger
Só em count: a quantidade contada. Ausente nos demais.
stock_syncedboolean
true quando o lançamento também mexeu no saldo do depósito do ERP de estoque.
reasonstring
Motivo gerado pela plataforma.
referencestring
Em movimentações, BINMOVE-<origem>-<destino>; vazio nos demais.
created_atdatetime
Quando foi lançado.
totalinteger
Total que atende ao filtro.

Erros: Listar histórico

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list bin movements","detail":"o valor \"xyz\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}
401Cabeçalho Authorization ausente, token inválido, expirado ou revogado.{"error":"missing authorization header"}
403O token não é de um usuário seller (por exemplo, é de administrador).{"error":"insufficient permissions"}
403O usuário não está vinculado a um seller, ou o cadastro do seller ainda está em análise (vendor_pending_review).{"error":"no vendor account associated with this user"}

Veja também

  • Endereços
  • Movimentos de estoque
Anterior
Endereços do armazém
Próxima
Listas de separação
Nesta página
  • Listar saldos por endereço
  • Exemplo de requisição: Listar saldos por endereço
  • Resposta: Listar saldos por endereço
  • Erros: Listar saldos por endereço
  • Registrar contagem
  • Exemplo de requisição: Registrar contagem
  • Resposta: Registrar contagem
  • Erros: Registrar contagem
  • Mover entre endereços
  • Exemplo de requisição: Mover entre endereços
  • Resposta: Mover entre endereços
  • Erros: Mover entre endereços
  • Listar histórico
  • Exemplo de requisição: Listar histórico
  • Resposta: Listar histórico
  • Erros: Listar histórico
  • Veja também