Paginação

Paginação por cursor na API de Leads

A paginação por cursor permite percorrer páginas da listagem com estabilidade, usando o cursor retornado pela própria API.

next_cursorhas_morecursor API

Por que usamos cursor

Cursor é mais adequado para sincronização do que paginação por número de página quando a base pode mudar entre uma chamada e outra. O cliente continua a partir do ponto retornado pela API.

Como funciona page_info

{
  "page_info": {
    "next_cursor": "eyJ2Ijox...",
    "has_more": true
  }
}

Como usar next_cursor

Se has_more for true, envie cursor=VALOR_DE_next_cursor na próxima chamada. Se next_cursor for null ou has_more for false, a janela de paginação terminou.

Como evitar duplicidade

Não altere parâmetros da consulta no meio da paginação. Mantenha limit e filtros coerentes até concluir a janela e use uma chave estável no destino para upsert quando necessário.

Exemplo de fluxo completo

Primeira chamada

GET /public/v1/leads?limit=100&updated_since=...

Ler page_info

Verificar has_more e next_cursor.

Continuar

Chamar GET /public/v1/leads?limit=100&cursor=NEXT_CURSOR_AQUI.

Encerrar

Parar quando has_more=false e salvar o marco da sincronização.

Erros de cursor

Status	Código	Quando acontece	Ação recomendada
400	invalid_cursor	O cursor informado não pode ser lido ou não pertence à consulta atual.	Use apenas o valor retornado em page_info.next_cursor.
400	invalid_limit	O limit está fora do intervalo aceito ou não é numérico.	Ajuste o tamanho da página antes de repetir a chamada.