Lotes
Um lote é uma quantidade de um produto com uma data de validade.
| Rota | Escopo | O que faz |
|---|---|---|
GET /v1/batches | read | lista lotes |
GET /v1/batches/{id} | read | mostra um lote |
GET /v1/products/{id}/batches | read | lista os lotes de um produto |
POST /v1/batches | write | cria um lote (informando o produto no corpo) |
POST /v1/products/{id}/batches | write | cria um lote para o produto da URL |
PATCH /v1/batches/{id} | write | altera um lote |
DELETE /v1/batches/{id} | delete | exclui um lote |
O lote
| Campo | Tipo | Descrição |
|---|---|---|
id | UUID | identificador |
product_id | UUID | produto do lote |
name | texto | nome ou número do lote |
exp_date | data (AAAA-MM-DD) | data de validade |
amount | número ou null | quantidade |
unit | texto ou null | unidade (por exemplo un, kg) |
price | número ou null | preço de venda |
cost_price | número ou null | preço de custo |
status | checked ou unchecked | se o lote já foi conferido |
location | texto ou null | onde o lote está (corredor, prateleira…) |
additional_data | texto ou null | observações |
created_at, updated_at | data e hora | criação e última alteração |
Listar: GET /v1/batches
| Parâmetro | Descrição |
|---|---|
exp_date_from | validade a partir desta data, inclusive (AAAA-MM-DD) |
exp_date_to | validade até esta data, inclusive (AAAA-MM-DD) |
status | checked ou unchecked |
product_id | só os lotes desse produto |
store_id | só os lotes de produtos dessa loja |
updated_since | só os criados ou alterados a partir desse instante |
limit, cursor | paginação |
Lotes que vencem nos próximos 7 dias e ainda não foram conferidos:
curl "https://api.validades.com/v1/batches?exp_date_from=2026-11-07&exp_date_to=2026-11-14&status=unchecked&limit=100" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
A lista é ordenada pela última alteração, e não pela validade. Para ordenar por validade, ordene no seu sistema ou use GET /v1/products/{id}?include=batches, que traz os lotes de um produto ordenados pela validade.
GET /v1/products/{id}/batches aceita os mesmos filtros e responde 404 se o produto não existir.
Criar: POST /v1/batches ou POST /v1/products/{id}/batches
| Campo | Obrigatório | Regras |
|---|---|---|
product_id | sim em /v1/batches | produto da organização. Em /v1/products/{id}/batches vem da URL |
exp_date | sim | data válida AAAA-MM-DD |
name | não | até 100 caracteres. Se não for enviado, o lote recebe o próximo número ("1", "2"…) entre os lotes do produto |
amount | não | de 0 a 1.000.000.000 |
unit | não | até 20 caracteres |
price, cost_price | não | de 0 a 99.999.999,99 |
status | não | checked ou unchecked (padrão unchecked) |
location | não | até 255 caracteres |
additional_data | não | até 1000 caracteres |
id | não | UUID gerado por você; se já existir, a resposta é 409 conflict |
curl -X POST https://api.validades.com/v1/products/ID_DO_PRODUTO/batches \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: nf-4521-item-3" \
-d '{"exp_date": "2026-12-31", "amount": 24, "unit": "un", "price": 6.49, "location": "Corredor 3"}'
Resposta 201 com { "data": { …lote… } } e o cabeçalho ETag.
Alterar: PATCH /v1/batches/{id}
Envie só os campos que quer mudar (pelo menos um). null limpa o campo. O produto do lote (product_id) não pode ser trocado: crie um lote novo no outro produto.
curl -X PATCH https://api.validades.com/v1/batches/ID_DO_LOTE \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"amount": 10, "status": "checked"}'
Aceita If-Match.
Excluir: DELETE /v1/batches/{id}
{ "data": { "id": "…", "deleted": { "batch": 1 } } }
Aceita If-Match.