Sincronização incremental
Como buscar só o que mudou, página a página, sem perder nem repetir registro.
Em resumo
- Toda listagem vem em ordem de atualização, com um cursor para a próxima página.
- Na carga inicial, liste do começo. Depois, retome do último cursor que você guardou.
- O cursor da última página é a sua marca d'água: guarde-o e use na próxima rodada.
- Alterações aparecem na sincronização incremental com até 2 minutos de atraso — é o que garante que nada se perde.
A página
{
"dados": [ { "id": "…", "atualizadoEm": "2026-10-09T15:30:12.654321+00:00", "…": "…" } ],
"paginacao": {
"proximoCursor": "eyJkIjoiMjAyNi0xMC0wOVQxNTozMDoxMi42NTQzMjErMDA6MDAiLCJpIjoi…",
"temMais": true
}
}| Parâmetro | O que faz |
|---|---|
limite | Itens por página, de 1 a 100. Padrão 50. |
cursor | O proximoCursor da página anterior. Opaco: não monte nem altere. |
atualizadoDesde | Só o que mudou a partir deste instante, em ISO 8601 com fuso (2026-10-09T08:00:00-03:00). |
Os itens vêm em ordem crescente de atualizadoEm (e de id, no empate). O cursor guarda a posição exata, com microssegundos: duas linhas atualizadas no mesmo milissegundo não se perdem.
O ciclo de sincronização
cursor = carregar_cursor_guardado() # vazio na primeira vez
repita:
pagina = GET /fornecedores?limite=100&cursor={cursor}
para cada item em pagina.dados:
gravar_por_id(item) # upsert
cursor = pagina.paginacao.proximoCursor
guardar_cursor(cursor)
até pagina.paginacao.temMais == falseNa última página, temMais é false e o proximoCursor continua vindo: é ele que a próxima rodada usa. Uma página vazia devolve o próprio cursor que você mandou.
Por que 2 minutos
Quando um registro muda no Afflux, o instante de atualização é o do início da operação. Uma operação que demora um pouco grava um instante "no passado" — e, se a sua sincronização já tivesse passado por ele, o registro nunca apareceria. Por isso, no modo incremental (com atualizadoDesde ou com um cursor de sincronização), a API só entrega registros atualizados há mais de 2 minutos. O que mudou agora aparece na rodada seguinte.
A listagem simples, sem cursor nem atualizadoDesde, e o detalhe por id (/fornecedores/{id}) mostram o estado atual, sem atraso.
O que não muda a data de atualização
Algumas informações são calculadas no momento da consulta e não mudam atualizadoEm:
- a situação de pagamento da conta a pagar (
pagamento.liberado), que depende de documentos que vencem; - o campo
vencidada conta a pagar.
Para elas, consulte o detalhe da conta imediatamente antes de pagar — veja Contas a pagar.
Exclusões
O Afflux não apaga registros de negócio: encerrar é mudar a situação. Fornecedor inativado, contrato encerrado ou documento cancelado chegam pela sincronização com a nova status. Não há "lista de apagados" a acompanhar.
Reconciliação
Uma vez por semana (ou por mês), vale fazer uma listagem completa, sem cursor, e comparar com o ERP. É a rede de segurança contra qualquer falha do seu lado — um cursor perdido, uma gravação que não completou.