Paginação e sincronização
Paginação por cursor
Todas as listas são paginadas por cursor e ordenadas pela data da última alteração (updated_at), da mais antiga para a mais recente.
{
"data": [ … ],
"pagination": {
"limit": 50,
"has_more": true,
"next_cursor": "eyJ1IjoiMjAyNi0xMS0wNlQx…"
}
}
| Parâmetro | Descrição |
|---|---|
limit | itens por página: padrão 50, máximo 100 |
cursor | o next_cursor da página anterior |
Para percorrer a lista inteira, repita a chamada passando cursor=next_cursor enquanto has_more for true.
curl "https://api.validades.com/v1/products?limit=100&cursor=eyJ1IjoiMjAyNi0xMS0wNlQx…" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
Regras do cursor:
- é um texto opaco: não tente montar nem alterar;
- vale só para a mesma lista e os mesmos filtros (um cursor de produtos não funciona em lotes);
- itens alterados no mesmo instante não são pulados nem repetidos entre páginas.
Os dados mudam o tempo todo, pelos aparelhos da equipe e pela própria API. Com número de página, um item alterado durante a leitura muda de posição e pode ser pulado ou repetido. O cursor evita isso.
Buscando só o que mudou: updated_since
As listas aceitam updated_since, um instante ISO 8601 com fuso horário. A resposta traz só os itens criados ou alterados a partir desse instante.
curl "https://api.validades.com/v1/batches?updated_since=2026-11-06T13:00:00Z&limit=100" \
-H "Authorization: Bearer vld_live_SUA_CHAVE"
Exclusões: GET /v1/deletions
Itens excluídos não aparecem mais nas listas, então updated_since não mostra exclusões. Para isso existe a rota /v1/deletions, que lista o que foi excluído nos últimos 90 dias, inclusive:
- exclusões feitas no aplicativo, no site ou pela API;
- exclusões em cascata (lotes de um produto excluído, produtos e lotes de uma loja excluída com
cascade=true).
Receita de sincronização incremental
Primeira vez:
- Guarde o instante atual em UTC como
inicio. - Baixe cada lista inteira (categorias, marcas, lojas, produtos, lotes), seguindo os cursores.
- Salve
iniciocomoultima_sincronizacao.
Nas vezes seguintes:
- Guarde o instante atual como
inicio. - Para cada lista, busque com
updated_since=ultima_sincronizacaoe siga os cursores. Crie ou atualize os itens recebidos no seu sistema. - Busque
/v1/deletions?since=ultima_sincronizacao, siga os cursores e apague os itens listados. - Salve
iniciocomoultima_sincronizacao.
Dicas:
- Use uma pequena margem de segurança, por exemplo
updated_since2 minutos antes da última sincronização. Itens repetidos são inofensivos: basta atualizar peloid. - Sincronize primeiro categorias, marcas e lojas, depois produtos e por último lotes, para que as referências já existam no seu sistema.
- Se o seu sistema ficar mais de 90 dias sem sincronizar, faça uma sincronização completa de novo, porque as exclusões mais antigas já não estarão disponíveis.
Filtros das listas
Os filtros de cada lista estão nas páginas de referência. Parâmetros desconhecidos ou inválidos são recusados com 422 (validation_error), com o detalhe do problema em details.