VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/ERP Estoque

Saldos de estoque

Consulta o saldo físico, reservado e disponível por produto e depósito, e define o estoque mínimo que dispara o alerta.

Listar saldos

A grade de saldos mostra, para cada par produto e depósito, o saldo físico, o reservado e o disponível, além do estoque mínimo. A resposta traz também low_stock_count, o número de itens em alerta em todo o seller, que serve para o indicador no topo de uma tela.

GET/api/v1/vendor/erp/inventory/stockSeller

Lista o saldo por produto e depósito

Parâmetros de consulta

product_iduuid
Só este produto.
warehouse_iduuid
Só este depósito.
lowstring
1true
1 ou true devolve só itens em alerta de estoque baixo.
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 saldos

bash
curl "$BASE_URL/api/v1/vendor/erp/inventory/stock?low=1" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar saldos

200Saldos retornados
json
{
  "stock": [
    {
      "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
      "product_name": "Camiseta Básica Preta M",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "warehouse_name": "Depósito Central",
      "quantity": 18,
      "reorder_point": 10,
      "low_stock": false,
      "reserved": 3,
      "available": 15,
      "updated_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1,
  "low_stock_count": 0
}

Campos da resposta

stockarray

Saldos da página.

product_iduuid
Produto.
product_namestring
Nome do produto. Vazio se o produto não existe mais no catálogo.
warehouse_iduuid
Depósito.
warehouse_namestring
Nome do depósito.
quantityinteger
Saldo físico atual neste depósito.
reorder_pointinteger
Estoque mínimo. 0 desliga o alerta.
low_stockboolean
true quando reorder_point > 0 e quantity <= reorder_point. Calculado, não gravado.
reservedinteger
Unidades reservadas (por pedidos em aberto ou reserva manual).
availableinteger
Disponível para prometer: quantity menos reserved. É o ATP (available to promise).
updated_atdatetime
Última mudança do saldo.
totalinteger
Total de linhas que atendem ao filtro.
low_stock_countinteger
Itens em alerta em todo o seller, ignorando os filtros da chamada.

Erros: Listar saldos

StatusQuandoCorpo
500Um filtro de id não é um UUID válido (a plataforma devolve 500, não 400).{"error":"failed to list 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"}
Depósito apagado ainda aparece

A grade não esconde linhas de depósitos apagados. Como só é possível apagar um depósito vazio, na prática elas têm saldo zero.

Definir estoque mínimo

Grava o estoque mínimo (ponto de reposição) de um produto num depósito. Enquanto o saldo for maior que o mínimo está tudo certo; quando ele chega no mínimo ou abaixo, a linha passa a low_stock: true e o seller recebe o alerta. Use 0 para desligar o alerta daquela linha.

PUT/api/v1/vendor/erp/inventory/stock/reorder-pointSeller

Define o estoque mínimo de uma linha

Corpo da requisição

product_iduuidobrigatório
Produto.
warehouse_iduuidobrigatório
Depósito do seller.
reorder_pointintegerobrigatório
Estoque mínimo, zero ou mais.

Exemplo de requisição: Definir estoque mínimo

bash
curl -X PUT "$BASE_URL/api/v1/vendor/erp/inventory/stock/reorder-point" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "reorder_point": 10
}'

Resposta: Definir estoque mínimo

200Estoque mínimo gravado
json
{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "product_name": "Camiseta Básica Preta M",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "warehouse_name": "Depósito Central",
  "quantity": 18,
  "reorder_point": 10,
  "low_stock": false,
  "reserved": 3,
  "available": 15,
  "updated_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

product_iduuid
Produto.
product_namestring
Nome do produto. Vazio se o produto não existe mais no catálogo.
warehouse_iduuid
Depósito.
warehouse_namestring
Nome do depósito.
quantityinteger
Saldo físico atual neste depósito.
reorder_pointinteger
Estoque mínimo. 0 desliga o alerta.
low_stockboolean
true quando reorder_point > 0 e quantity <= reorder_point. Calculado, não gravado.
reservedinteger
Unidades reservadas (por pedidos em aberto ou reserva manual).
availableinteger
Disponível para prometer: quantity menos reserved. É o ATP (available to promise).
updated_atdatetime
Última mudança do saldo.

Erros: Definir estoque mínimo

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400product_id ausente.{"error":"vendorerp: product_id required"}
400warehouse_id ausente.{"error":"vendorerp: warehouse_id required"}
400reorder_point negativo.{"error":"vendorerp: reorder_point must be >= 0"}
404O depósito não existe ou é de outro seller.{"error":"warehouse 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"}

Veja também

  • Movimentos e transferências
  • Reservas
Anterior
Movimentos e transferências
Próxima
Reservas de estoque
Nesta página
  • Listar saldos
  • Exemplo de requisição: Listar saldos
  • Resposta: Listar saldos
  • Erros: Listar saldos
  • Definir estoque mínimo
  • Exemplo de requisição: Definir estoque mínimo
  • Resposta: Definir estoque mínimo
  • Erros: Definir estoque mínimo
  • Veja também