Produtos
| Rota | Escopo | O que faz |
|---|---|---|
GET /v1/products | read | lista produtos |
GET /v1/products/{id} | read | mostra um produto (com foto e, se pedir, os lotes) |
POST /v1/products | write | cria um produto |
PATCH /v1/products/{id} | write | altera um produto |
DELETE /v1/products/{id} | delete | exclui um produto e todos os seus lotes |
Os lotes de um produto têm rotas próprias: veja Lotes.
O produto
| Campo | Tipo | Descrição |
|---|---|---|
id | UUID | identificador |
name | texto | nome do produto |
code | texto ou null | código de barras (EAN/GTIN) ou código interno |
days_to_be_next | número ou null | quantos dias antes da validade o lote passa a contar como "vencendo" |
brand_id | UUID ou null | marca |
category_id | UUID ou null | categoria |
store_id | UUID ou null | loja |
has_image | sim/não | se o produto tem foto |
created_at, updated_at | data e hora | criação e última alteração |
Listar: GET /v1/products
| Parâmetro | Descrição |
|---|---|
q | busca no nome ou no código (contém o texto, sem diferenciar maiúsculas) |
code | código exato |
brand_id, category_id, store_id | só os produtos dessa marca, categoria ou loja |
updated_since | só os criados ou alterados a partir desse instante |
limit, cursor | paginação |
curl "https://api.validades.com/v1/products?code=7891000100103" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
Consultar: GET /v1/products/{id}
A resposta traz também:
| Campo | Descrição |
|---|---|
image_url | link temporário da foto do produto (vale alguns minutos), ou null |
batches | só com include=batches: até 500 lotes, ordenados pela validade |
batches_truncated | só com include=batches: true se o produto tem mais de 500 lotes |
curl "https://api.validades.com/v1/products/ID_DO_PRODUTO?include=batches" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
Sem include, a resposta traz o cabeçalho ETag e aceita If-None-Match. Veja Concorrência e idempotência.
Criar: POST /v1/products
| Campo | Obrigatório | Regras |
|---|---|---|
name | sim | 1 a 255 caracteres |
code | não | até 100 caracteres |
days_to_be_next | não | número inteiro de 0 a 3650 |
brand_id, category_id | não | precisa existir na organização |
store_id | não | precisa existir na organização e estar ativa |
id | não | UUID gerado por você; se já existir, a resposta é 409 conflict |
curl -X POST https://api.validades.com/v1/products \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: produto-7891000100103" \
-d '{"name": "Leite integral 1L", "code": "7891000100103", "days_to_be_next": 15, "category_id": "ID_DA_CATEGORIA"}'
Resposta 201 com { "data": { …produto… } } e o cabeçalho ETag.
Alterar: PATCH /v1/products/{id}
Envie só os campos que quer mudar (pelo menos um). null limpa o campo, exceto name, que não pode ficar vazio.
curl -X PATCH https://api.validades.com/v1/products/ID_DO_PRODUTO \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"days_to_be_next": 7, "brand_id": null}'
Resposta 200 com o produto atualizado. Aceita If-Match.
Excluir: DELETE /v1/products/{id}
Exclui também os lotes
Excluir um produto exclui todos os lotes dele e a foto, em todos os aparelhos da organização. A exclusão é definitiva.
{
"data": {
"id": "6b7e1f0a-…",
"deleted": { "product": 1, "batches": 3 }
}
}
Aceita If-Match.