Listagem e paginação

Os endpoints da API que retornam listas utilizam paginação para dividir os resultados entre diferentes requisições.

Use limit e offset na requisição e hasMore na resposta para percorrer todos os registros.

Parâmetros de paginação

Campo	Onde aparece	Descrição
`limit`	Requisição	Quantidade máxima de itens retornados por página. Aceita valores de `1` a `100`. O padrão é `10`.
`offset`	Requisição	Posição do primeiro item que será retornado. A listagem começa em `0`.
`totalCount`	Resposta	Quantidade total de itens encontrados para os filtros informados.
`hasMore`	Resposta	Indica se ainda existem registros para consultar.

Como percorrer os resultados

Com limit=10, consulte inicialmente com offset=0. Enquanto hasMore for true, incremente o offset pelo mesmo valor utilizado em limit.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Consultar com offset=0"] --> B["Processar os registros"]
    B --> C{"hasMore é true?"}

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

    CSim --> D["Incrementar offset"]
    D --> E["Consultar próxima página"]
    E --> B

    CNao --> F["Finalizar a 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 validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,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

    class A inicio
    class C decisao
    class B,D,E validacao
    class F sucesso

    class CSim respostaSim
    class CNao respostaNao

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

Por exemplo, com limit=10:

Página	`limit`	`offset`
Primeira	`10`	`0`
Segunda	`10`	`10`
Terceira	`10`	`20`

Use hasMore como condição para continuar a paginação. Quando retornar false, não há outra página para os filtros utilizados.

👍
Recomendado
Use listagens paginadas para consultas, cargas iniciais e reconciliação de dados.
Se sua integração precisa acompanhar mudanças de estado, utilize Webhooks em vez de consultar repetidamente os endpoints de listagem.

Próximos passos