Saltar al contenido principal

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âmetroDescrição
limititens por página: padrão 50, máximo 100
cursoro 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.
Por que cursor, e não número da página

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:

  1. Guarde o instante atual em UTC como inicio.
  2. Baixe cada lista inteira (categorias, marcas, lojas, produtos, lotes), seguindo os cursores.
  3. Salve inicio como ultima_sincronizacao.

Nas vezes seguintes:

  1. Guarde o instante atual como inicio.
  2. Para cada lista, busque com updated_since=ultima_sincronizacao e siga os cursores. Crie ou atualize os itens recebidos no seu sistema.
  3. Busque /v1/deletions?since=ultima_sincronizacao, siga os cursores e apague os itens listados.
  4. Salve inicio como ultima_sincronizacao.

Dicas:

  • Use uma pequena margem de segurança, por exemplo updated_since 2 minutos antes da última sincronização. Itens repetidos são inofensivos: basta atualizar pelo id.
  • 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.