Listagem incompleta por ausência de paginação

Esse erro ocorre quando a integração consulta um endpoint de listagem, mas processa apenas a primeira parte do resultado.

Quando existem mais registros do que o limite retornado por página, os itens restantes não são carregados. Isso pode gerar relatórios incompletos, falhas de conciliação e a impressão de que determinadas operações não existem.

Como identificar

• a quantidade retornada é sempre igual ao limite por página;
• a resposta indica que existem mais registros;
• o total armazenado no sistema é menor que o total existente no Asaas;
• registros recentes são encontrados, mas os mais antigos não aparecem;
• o problema ocorre somente após o aumento do volume;
• alterar a página, o offset ou o cursor retorna novos registros;
• somente a primeira resposta da consulta aparece nos logs;
• a sincronização termina após uma única requisição.

Como corrigir

1. Verifique qual mecanismo de paginação é utilizado pelo endpoint.
2. Identifique os parâmetros de limite, página, offset ou cursor.
3. Inicie a consulta pela primeira página.
4. Processe e armazene os registros retornados.
5. Verifique se ainda existem registros disponíveis.
6. Avance a paginação conforme o mecanismo do endpoint.
7. Repita a consulta até não existirem novos registros.
8. Evite processar novamente os registros já armazenados.
9. Compare o total processado com o total esperado.
10. Teste a consulta com uma quantidade superior ao limite de uma página.

Fluxo recomendado: consultar → processar a página → verificar se existem mais registros → avançar a paginação → repetir → validar o total.

Fluxo de diagnóstico

1. Confirmação da listagem incompleta

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["A listagem parece<br/>incompleta"] --> B{"A consulta processa<br/>mais de uma página?"}

B --> BSim(("Sim"))
B --> BNao(("Não"))

BSim --> C{"A resposta indica<br/>mais registros?"}

BNao --> D["Identificar o mecanismo<br/>de paginação do endpoint"]
D --> E["Executar a próxima página"]

C --> CSim(("Sim"))
C --> CNao(("Não"))

CSim --> E
CNao --> F["Comparar o total obtido<br/>com o total esperado"]
E --> F

F --> G{"Os totais conferem?"}

G --> GSim(("Sim"))
G --> GNao(("Não"))

GSim --> H["Listagem validada"]
GNao --> I["Revisar filtros e avanço<br/>da paginação"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class B,C,G decisao
class E correcao
class F validacao
class H sucesso
class D,I analise

class BSim,CSim,GSim respostaSim
class BNao,CNao,GNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 1,6,12 stroke:#22C55E,stroke-width:4px
linkStyle 2,7,13 stroke:#EF4444,stroke-width:4px

2. Processamento completo da paginação

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7
}}}%%
flowchart TD
A["Iniciar na primeira página"] --> B["Processar e armazenar<br/>os registros"]

B --> C{"Existem mais<br/>registros?"}

C --> CSim(("Sim"))
C --> CNao(("Não"))

CSim --> D["Avançar offset,<br/>página ou cursor"]
D --> E["Consultar a próxima página"]
E --> B

CNao --> F["Comparar o total processado<br/>com o total esperado"]

F --> G{"Os totais conferem?"}

G --> GSim(("Sim"))
G --> GNao(("Não"))

GSim --> H["Finalizar a sincronização"]

GNao --> I["Revisar paginação, filtros<br/>e duplicidades"]
I --> J["Corrigir e executar<br/>novamente"]

classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

class A inicio
class C,G decisao
class B,D,E correcao
class F validacao
class H sucesso
class I,J analise

class CSim,GSim respostaSim
class CNao,GNao respostaNao

linkStyle default stroke:#94A3B8,stroke-width:2px
linkStyle 2,9 stroke:#22C55E,stroke-width:4px
linkStyle 3,10 stroke:#EF4444,stroke-width:4px

O primeiro fluxo ajuda a confirmar se a ausência dos registros está relacionada à paginação, enquanto o segundo mostra como percorrer todas as páginas e validar o resultado.

Como prevenir

Trate a paginação como uma etapa obrigatória em todos os endpoints de listagem. A consulta deve continuar até que a resposta indique que não existem mais registros.

Teste o fluxo com volumes superiores ao limite de uma página, registre a quantidade processada e evite duplicidades durante novas execuções.

Receber uma página com sucesso não significa que todos os registros foram consultados.