Uma integração que funciona com vinte contatos pode falhar quando precisa percorrer milhares de registros. O problema nem sempre é velocidade. Enquanto uma página é lida, pessoas continuam alterando dados; uma execução pode parar no meio; a consulta seguinte pode devolver itens repetidos. O projeto precisa explicar onde terminou o trabalho confirmado e como retomá-lo. Este roteiro ajuda a especificar esse comportamento antes de escolher biblioteca ou ferramenta.
Separe página, lote e checkpoint
Página é a unidade devolvida pela API. Lote é a unidade que sua integração consegue aplicar e conferir. Checkpoint é a posição persistida que permite continuar depois. Esses conceitos podem coincidir, mas não são obrigados a isso. Salvar a posição assim que a resposta chega cria um risco: se a aplicação dos dados falhar depois, o próximo processo pode avançar e deixar registros para trás.
O contrato do fornecedor determina a navegação. No Microsoft Graph, por exemplo, @odata.nextLink indica continuação da rodada e @odata.deltaLink serve para buscar mudanças posteriores. A documentação orienta tratar os tokens como opacos e não presumir uma sequência fixa dos itens. Esses nomes são específicos desse serviço; não devem ser atribuídos automaticamente à API do seu CRM. Consulte o fluxo oficial de consultas delta como exemplo de contrato explícito.
Desenhe uma retomada verificável
- Registre o escopo da execução: entidade, filtro, ambiente e versão do contrato.
- Busque a próxima página usando a continuação documentada, sem inventar parâmetros.
- Valide os registros e aplique as mudanças com proteção contra repetição.
- Guarde as exceções com identificador e motivo, sem descartar silenciosamente entradas.
- Confirme que o lote terminou e só então avance o checkpoint correspondente.
Em um projeto que permite transação conjunta, a gravação do efeito e do progresso pode ocorrer no mesmo compromisso. Quando destino e controle estão em sistemas diferentes, registre estados intermediários e permita reaplicar o lote sem duplicar efeitos. O objetivo do procedimento é conseguir demonstrar o que foi confirmado; a técnica concreta depende das garantias disponíveis em cada ponta.
Exemplo fictício de controle
| Lote | Resultado | Posição persistida | Próxima ação |
|---|---|---|---|
| L01 | Todos os itens confirmados | Cursor B | Buscar a página B |
| L02 | Execução interrompida | Cursor B | Retomar e reaplicar com idempotência |
| L02 repetido | Itens anteriores reconhecidos | Cursor C | Prosseguir após conferência |
As letras representam referências fictícias, não um formato de token. O diário operacional deve mostrar a contagem de itens recebidos, aplicados, reconhecidos e rejeitados. Se uma rejeição impedir a conclusão, o lote permanece pendente. Se a política permitir avançar mantendo a exceção em uma fila durável, essa decisão precisa ser explícita e ter responsável.
Inclua alterações e exclusões
Uma consulta por data de atualização exige perguntas adicionais: qual é o fuso, qual a precisão, como desempatar dois registros no mesmo instante e o que acontece durante a leitura? Uma janela de sobreposição pode ajudar a reencontrar mudanças, desde que exista idempotência. Ela não substitui uma garantia documentada de rastreamento. Também defina como descobrir exclusões: ausência em uma página não prova que um registro foi removido.
Planeje a situação em que o cursor expira ou deixa de ser aceito. O operador deve saber quando iniciar nova leitura integral, como proteger alterações locais e como reconciliar a nova fotografia com o destino. Reiniciar indiscriminadamente uma carga não pode transformar uma falha de navegação em exclusão de dados válidos.
Teste antes de aumentar o volume
Prepare uma amostra controlada com criação, alteração, exclusão e dois itens de mesma data. Interrompa o processo antes e depois da aplicação de um lote; repita a página anterior; altere um registro durante a leitura. O teste passa quando cada efeito esperado aparece uma vez, as exceções continuam visíveis e o progresso permite retomada. Registre a evidência por identificador, não apenas uma mensagem de “sucesso”.
Antes da implementação, alinhe o contrato de dados, a estratégia de idempotência e o tratamento de retentativas. Esse conjunto torna a sincronização recuperável sem pressupor recursos específicos de um produto.
Fontes e referências
Referências consultadas em 21/10/2026. Confira a documentação vigente do seu fornecedor antes de alterar uma integração.
