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

Movimentos e transferências

Lê o extrato de estoque, lança entradas, saídas e ajustes, e transfere unidades entre depósitos.

Listar movimentos

O extrato é o registro imutável de tudo que mexeu no estoque: entradas, saídas e ajustes, do mais novo para o mais antigo. Use para auditar um saldo ou reconciliar com o seu sistema.

GET/api/v1/vendor/erp/inventory/movementsSeller

Lista o extrato de movimentos

Parâmetros de consulta

product_iduuid
Só movimentos deste produto.
warehouse_iduuid
Só movimentos deste depósito.
typestring
inoutadjust
Tipo do movimento. Um valor desconhecido não dá erro, apenas devolve lista vazia.
fromstring
Início, inclusivo, sobre a data do movimento. Data (2026-10-01) ou data e hora RFC 3339.
tostring
Fim, inclusivo. Atenção: uma data sem hora (2026-10-31) vale meia-noite do início do dia, então exclui os movimentos desse dia.
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 movimentos

bash
curl "$BASE_URL/api/v1/vendor/erp/inventory/movements?warehouse_id=8204b8b8-e7e2-4b96-bba8-5a937fe001c8&type=in&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar movimentos

200Movimentos retornados
json
{
  "movements": [
    {
      "id": "593aca14-635f-4bd2-acc2-c10f99ddae51",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "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",
      "type": "in",
      "quantity": 20,
      "reason": "Compra de reposição",
      "reference": "NF 4521",
      "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
      "created_at": "2026-10-11T14:30:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

movementsarray

Movimentos da página.

iduuid
Id do movimento.
vendor_iduuid
Seller dono do movimento.
product_iduuid
Produto movimentado.
product_namestring
Nome do produto no catálogo. Vazio se o produto não foi encontrado.
warehouse_iduuid
Depósito afetado.
warehouse_namestring
Nome do depósito.
typestring
inoutadjust
Tipo do movimento.
quantityinteger
Quantidade como foi enviada: positiva em in/out; em adjust é o delta com sinal.
reasonstring
Motivo informado. Vazio se não informado.
referencestring
Referência livre (nota, pedido de compra, transferência). Vazio se não informada.
created_byuuid
Usuário que lançou. Ausente quando o lançamento veio de um processo automático.
created_atdatetime
Quando foi lançado, RFC 3339 UTC.
totalinteger
Total de movimentos que atendem ao filtro, em todas as páginas.

Erros: Listar movimentos

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

Registrar movimento

Lança uma entrada, saída ou ajuste num depósito. O movimento e o novo saldo são gravados juntos, numa só transação. Quando o produto é do próprio seller, o mesmo delta também é refletido no estoque do catálogo, que é o que a vitrine e o checkout leem.

POST/api/v1/vendor/erp/inventory/movementsSeller

Registra um movimento de estoque

Corpo da requisição

product_iduuidobrigatório
Produto movimentado.
warehouse_iduuidobrigatório
Depósito do seller.
typestringobrigatório
inoutadjust
in soma, out subtrai, adjust aplica quantity como delta com sinal. Aceita maiúsculas.
quantityintegerobrigatório
Em in e out, positivo. Em adjust, um delta (positivo ou negativo), nunca o saldo final. Zero é recusado.
reasonstring
Motivo, texto livre.
referencestring
Referência livre (nota, pedido).

Exemplo de requisição: Registrar movimento

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/inventory/movements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "type": "in",
  "quantity": 20,
  "reason": "Compra de reposição",
  "reference": "NF 4521"
}'

Resposta: Registrar movimento

201Movimento lançado
json
{
  "id": "593aca14-635f-4bd2-acc2-c10f99ddae51",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "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",
  "type": "in",
  "quantity": 20,
  "reason": "Compra de reposição",
  "reference": "NF 4521",
  "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
  "created_at": "2026-10-11T14:30:00Z"
}

Campos da resposta

iduuid
Id do movimento.
vendor_iduuid
Seller dono do movimento.
product_iduuid
Produto movimentado.
product_namestring
Nome do produto no catálogo. Vazio se o produto não foi encontrado.
warehouse_iduuid
Depósito afetado.
warehouse_namestring
Nome do depósito.
typestring
inoutadjust
Tipo do movimento.
quantityinteger
Quantidade como foi enviada: positiva em in/out; em adjust é o delta com sinal.
reasonstring
Motivo informado. Vazio se não informado.
referencestring
Referência livre (nota, pedido de compra, transferência). Vazio se não informada.
created_byuuid
Usuário que lançou. Ausente quando o lançamento veio de um processo automático.
created_atdatetime
Quando foi lançado, RFC 3339 UTC.

Erros: Registrar movimento

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"}
400type fora dos três valores.{"error":"vendorerp: type must be in|out|adjust"}
400quantity igual a zero.{"error":"vendorerp: quantity must be non-zero"}
400quantity negativa em in ou out.{"error":"vendorerp: quantity must be positive for in/out"}
400Saída ou ajuste negativo maior que o saldo atual.{"error":"estoque insuficiente: saldo atual 4, a movimentação deixaria o saldo negativo"}
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"}
O produto não é validado

A rota confere o depósito, mas não confere se product_id existe nem se é seu. Um id qualquer cria saldo no ERP; só o produto do próprio seller reflete no catálogo. Confira o id antes.

Alerta de estoque baixo

Se o saldo cruzar o estoque mínimo (veja Saldos) a plataforma avisa o seller uma vez, no sino de notificações (e por e-mail, se o seller não desligou esse aviso), e só volta a avisar depois que o saldo se recuperar.

Transferir estoque

Move unidades de um depósito para outro do mesmo seller de forma atômica: a saída na origem e a entrada no destino são gravadas na mesma transação, ligadas por uma referência comum. Se qualquer parte falhar, nada muda.

POST/api/v1/vendor/erp/inventory/transferSeller

Transfere estoque entre depósitos

Corpo da requisição

product_iduuidobrigatório
Produto transferido.
from_warehouse_iduuidobrigatório
Depósito de origem.
to_warehouse_iduuidobrigatório
Depósito de destino. Deve ser diferente da origem.
quantityintegerobrigatório
Unidades, maior que zero.
reasonstring
Motivo. Padrão Transferência entre depósitos.
referencestring
Referência comum às duas pernas. Padrão TRF-<origem>-<destino>.

Exemplo de requisição: Transferir estoque

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/inventory/transfer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
  "from_warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "to_warehouse_id": "5d0f2a77-0c3e-4b0f-8d9a-1e6b7c2a4f90",
  "quantity": 5,
  "reason": "Reabastecer loja"
}'

Resposta: Transferir estoque

201Transferência feita
json
{
  "out": {
    "id": "593aca14-635f-4bd2-acc2-c10f99ddae51",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "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",
    "type": "out",
    "quantity": 5,
    "reason": "Compra de reposição",
    "reference": "TRF-origem-destino",
    "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
    "created_at": "2026-10-11T14:30:00Z"
  },
  "in": {
    "id": "f6921987-1a3a-40ac-a800-2038b3991981",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "product_id": "94e6917e-8733-4ddc-b446-ed85977117e8",
    "product_name": "Camiseta Básica Preta M",
    "warehouse_id": "5d0f2a77-0c3e-4b0f-8d9a-1e6b7c2a4f90",
    "warehouse_name": "Loja Pinheiros",
    "type": "in",
    "quantity": 5,
    "reason": "Compra de reposição",
    "reference": "TRF-origem-destino",
    "created_by": "b00d3e7c-d5b4-4942-827a-06e2c43645af",
    "created_at": "2026-10-11T14:30:00Z"
  }
}

Campos da resposta

outobject
Perna de saída, no depósito de origem. Mesmos campos de um movimento.
inobject
Perna de entrada, no depósito de destino. Mesmos campos de um movimento.

Erros: Transferir estoque

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"}
400Falta um dos dois depósitos.{"error":"vendorerp: from_warehouse_id and to_warehouse_id required"}
400Origem igual ao destino.{"error":"vendorerp: from and to warehouses must differ"}
400quantity menor ou igual a zero.{"error":"vendorerp: quantity must be positive"}
400A origem não tem saldo suficiente.{"error":"insufficient stock at source warehouse"}
404Um dos depósitos 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"}
Reservas não entram na conta

A transferência confere o saldo físico da origem, não o disponível. Unidades reservadas por pedidos também podem ser transferidas.

Veja também

  • Saldos por depósito
  • Depósitos
  • Reservas
Anterior
Depósitos
Próxima
Saldos de estoque
Nesta página
  • Listar movimentos
  • Exemplo de requisição: Listar movimentos
  • Resposta: Listar movimentos
  • Erros: Listar movimentos
  • Registrar movimento
  • Exemplo de requisição: Registrar movimento
  • Resposta: Registrar movimento
  • Erros: Registrar movimento
  • Transferir estoque
  • Exemplo de requisição: Transferir estoque
  • Resposta: Transferir estoque
  • Erros: Transferir estoque
  • Veja também