Primeiros passos
1. Peça acesso
Só o dono ou um administrador da organização pode fazer isso, e a organização precisa ter assinatura ativa.
- Entre em validades.com e escolha a organização.
- Abra Time → API → Gerenciar API.
- Clique em Solicitar acesso, leia e aceite os Termos de Uso da API e, se quiser, conte para que vai usar a API.
Nossa equipe analisa o pedido e avisa por e-mail. Se o pedido não for aprovado, um novo pedido pode ser feito depois de 30 dias.
2. Crie uma chave
Com a API liberada, no mesmo painel:
- Clique em Criar chave.
- Dê um nome que identifique a integração (por exemplo, "ERP loja centro").
- Escolha o acesso:
- Somente leitura (
read): só consultas; - Leitura e escrita (
readewrite): consultas, criação e alteração; - Permitir exclusões (
delete): marque só se a integração precisar apagar dados.
- Somente leitura (
- Escolha a validade (opcional) e confirme.
A chave aparece uma única vez. Copie e guarde em um local seguro, como o cofre de segredos do seu servidor. Se perder a chave, revogue-a e crie outra. Cada organização pode ter até 5 chaves ativas.
O dono e os administradores recebem um e-mail sempre que uma chave é criada.
3. Teste a chave
A rota /v1/me mostra a quem a chave pertence, os limites e o uso do mês:
curl https://api.validades.com/v1/me \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
{
"data": {
"organization": { "id": "8f1c…", "name": "Mercado Exemplo" },
"workspace": { "id": "2b6f…" },
"api_key": {
"id": "0d3e…",
"name": "ERP loja centro",
"last_four": "a9F2",
"scopes": ["read", "write"],
"expires_at": null,
"created_at": "2026-11-07T12:00:00.000Z"
},
"limits": {
"key_requests_per_minute": 60,
"organization_requests_per_minute": 120,
"monthly_quota": 50000
},
"usage": {
"month": { "period": "2026-11", "used": 1, "remaining": 49999, "resets_at": "2026-12-01T00:00:00.000Z" },
"today": { "date": "2026-11-07", "used": 1 }
}
}
}
4. Faça as primeiras chamadas
Listar os lotes que vencem até o fim do mês:
curl "https://api.validades.com/v1/batches?exp_date_to=2026-11-30&limit=100" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
Cadastrar um produto (precisa do escopo write):
curl -X POST https://api.validades.com/v1/products \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-produto-7891234567890" \
-d '{"name": "Leite integral 1L", "code": "7891234567890", "days_to_be_next": 15}'
Cadastrar um lote para esse produto:
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" \
-d '{"exp_date": "2026-12-31", "amount": 24, "price": 6.49}'
Próximos passos
- Entenda os limites e a cota antes de colocar a integração em produção.
- Para manter outro sistema atualizado, veja Paginação e sincronização.
- Trate os erros pelo campo
code, que não muda. - Acompanhe as chamadas no painel: veja Logs e uso.