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

Reservas de estoque

Lista, cria e libera reservas que separam unidades do saldo para pedidos e compromissos manuais.

Listar reservas

Uma reserva separa unidades do saldo para que não sejam prometidas duas vezes. Quando um pedido do seller é criado a plataforma reserva os itens sozinha; você também pode reservar na mão. A lista traz as duas origens.

GET/api/v1/vendor/erp/inventory/reservationsSeller

Lista as reservas de estoque

Parâmetros de consulta

statusstring
reservedreleasedcommitted
Filtra pelo estado da reserva. Um 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: 20
Itens por página, de 1 a 200. Fora dessa faixa vale o padrão.

Exemplo de requisição: Listar reservas

bash
curl "$BASE_URL/api/v1/vendor/erp/inventory/reservations?status=reserved" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Listar reservas

200Reservas retornadas
json
{
  "reservations": [
    {
      "id": "61f7b821-50a5-41a0-a30e-274532a26d1c",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "product_name": "Notebook Slim Rosa",
      "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
      "order_id": null,
      "quantity": 2,
      "status": "reserved",
      "reference": "Evento da loja",
      "created_at": "2026-10-11T14:30:00Z",
      "released_at": null
    }
  ],
  "total": 1
}

Campos da resposta

reservationsarray

Reservas da página.

iduuid
Id da reserva.
vendor_iduuid
Seller dono da reserva.
product_iduuid
Produto reservado.
product_namestring
Nome do produto.
warehouse_iduuid
Depósito onde a reserva está.
order_iduuid
Pedido que originou a reserva. null em reserva manual.
quantityinteger
Unidades reservadas.
statusstring
reservedreleasedcommitted
Estado da reserva.
referencestring
Texto livre. Reservas de pedido trazem order.
created_atdatetime
Criação.
released_atdatetime
Quando saiu de reserved. null enquanto reservada.
totalinteger
Total que atende ao filtro.

Erros: Listar reservas

StatusQuandoCorpo
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"}

Reservar estoque

Reserva unidades de um produto num depósito, por exemplo para um evento ou uma venda combinada fora da plataforma. Diferente da reserva automática de pedido, esta recusa a operação se o disponível for menor que o pedido.

POST/api/v1/vendor/erp/inventory/reservationsSeller

Reserva estoque manualmente

Corpo da requisição

product_iduuidobrigatório
Produto.
warehouse_iduuidobrigatório
Depósito do seller.
quantityintegerobrigatório
Unidades, maior que zero.
referencestring
Texto livre para lembrar o motivo.

Exemplo de requisição: Reservar estoque

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/inventory/reservations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "quantity": 2,
  "reference": "Evento da loja"
}'

Resposta: Reservar estoque

201Reserva criada
json
{
  "id": "61f7b821-50a5-41a0-a30e-274532a26d1c",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
  "product_name": "Notebook Slim Rosa",
  "warehouse_id": "8204b8b8-e7e2-4b96-bba8-5a937fe001c8",
  "order_id": null,
  "quantity": 2,
  "status": "reserved",
  "reference": "Evento da loja",
  "created_at": "2026-10-11T14:30:00Z",
  "released_at": null
}

Campos da resposta

iduuid
Id da reserva.
vendor_iduuid
Seller dono da reserva.
product_iduuid
Produto reservado.
product_namestring
Nome do produto.
warehouse_iduuid
Depósito onde a reserva está.
order_iduuid
Pedido que originou a reserva. null em reserva manual.
quantityinteger
Unidades reservadas.
statusstring
reservedreleasedcommitted
Estado da reserva.
referencestring
Texto livre. Reservas de pedido trazem order.
created_atdatetime
Criação.
released_atdatetime
Quando saiu de reserved. null enquanto reservada.

Erros: Reservar estoque

StatusQuandoCorpo
400Corpo não é um JSON válido.{"error":"invalid request body","detail":"invalid character 'b' looking for beginning of object key string"}
400Falta product_id ou warehouse_id.{"error":"vendorerp: product_id and warehouse_id required"}
400quantity menor ou igual a zero.{"error":"vendorerp: quantity must be positive"}
400O disponível (saldo menos reservado) é menor que quantity.{"error":"vendorerp: insufficient available stock"}
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"}

Liberar reserva

Devolve ao disponível as unidades de uma reserva em estado reserved. Só reservas ainda abertas podem ser liberadas; uma já liberada ou já consumida responde 404.

POST/api/v1/vendor/erp/inventory/reservations/{id}/releaseSeller

Libera uma reserva

Parâmetros de caminho

iduuidobrigatório
Id (UUID) da reserva.

Exemplo de requisição: Liberar reserva

bash
curl -X POST "$BASE_URL/api/v1/vendor/erp/inventory/reservations/3f6c1c1e-8d0b-4a55-9a52-1d6f6a4a7b10/release" \
  -H "Authorization: Bearer $TOKEN"

Resposta: Liberar reserva

200Reserva liberada
json
{
  "message": "reservation released"
}

Campos da resposta

messagestring
Sempre reservation released.

Erros: Liberar reserva

StatusQuandoCorpo
404Não existe, é de outro seller, ou já saiu do estado reserved.{"error":"reservation 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 de pedido se resolvem sozinhas

Quando o pedido é cancelado a reserva é liberada; quando ele passa a enviado ou concluído a reserva vira committed. Libere na mão só reservas manuais.

Disponível é o que você pode prometer

Mostre ao cliente o campo available de Saldos, não quantity: o primeiro já desconta as reservas.

Veja também

  • Saldos de estoque
  • Movimentos e transferências
Anterior
Saldos de estoque
Próxima
ERP de armazém e separação
Nesta página
  • Listar reservas
  • Exemplo de requisição: Listar reservas
  • Resposta: Listar reservas
  • Erros: Listar reservas
  • Reservar estoque
  • Exemplo de requisição: Reservar estoque
  • Resposta: Reservar estoque
  • Erros: Reservar estoque
  • Liberar reserva
  • Exemplo de requisição: Liberar reserva
  • Resposta: Liberar reserva
  • Erros: Liberar reserva
  • Veja também