メインコンテンツまでスキップ

Lotes

Um lote é uma quantidade de um produto com uma data de validade.

RotaEscopoO que faz
GET /v1/batchesreadlista lotes
GET /v1/batches/{id}readmostra um lote
GET /v1/products/{id}/batchesreadlista os lotes de um produto
POST /v1/batcheswritecria um lote (informando o produto no corpo)
POST /v1/products/{id}/batcheswritecria um lote para o produto da URL
PATCH /v1/batches/{id}writealtera um lote
DELETE /v1/batches/{id}deleteexclui um lote

O lote​

CampoTipoDescrição
idUUIDidentificador
product_idUUIDproduto do lote
nametextonome ou número do lote
exp_datedata (AAAA-MM-DD)data de validade
amountnúmero ou nullquantidade
unittexto ou nullunidade (por exemplo un, kg)
pricenúmero ou nullpreço de venda
cost_pricenúmero ou nullpreço de custo
statuschecked ou uncheckedse o lote já foi conferido
locationtexto ou nullonde o lote está (corredor, prateleira…)
additional_datatexto ou nullobservações
created_at, updated_atdata e horacriação e última alteração

Listar: GET /v1/batches​

ParâmetroDescrição
exp_date_fromvalidade a partir desta data, inclusive (AAAA-MM-DD)
exp_date_tovalidade até esta data, inclusive (AAAA-MM-DD)
statuschecked ou unchecked
product_idsó os lotes desse produto
store_idsó os lotes de produtos dessa loja
updated_sincesó os criados ou alterados a partir desse instante
limit, cursorpaginaçã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​

CampoObrigatórioRegras
product_idsim em /v1/batchesproduto da organização. Em /v1/products/{id}/batches vem da URL
exp_datesimdata válida AAAA-MM-DD
namenãoaté 100 caracteres. Se não for enviado, o lote recebe o próximo número ("1", "2"…) entre os lotes do produto
amountnãode 0 a 1.000.000.000
unitnãoaté 20 caracteres
price, cost_pricenãode 0 a 99.999.999,99
statusnãochecked ou unchecked (padrão unchecked)
locationnãoaté 255 caracteres
additional_datanãoaté 1000 caracteres
idnãoUUID 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.