# Paginar os resultados

Vários endpoints da API do Payments Direct retornam resultados paginados quando uma lista pode conter muitos registros. A API usa dois estilos de paginação, conforme o endpoint:

- **Paginação baseada em token** para identidades, instrumentos financeiros e busca de pagamentos. A resposta inclui um valor opaco de `nextToken` que você informa para recuperar a próxima página.
- **Paginação por offset** para transações de ledger. Você especifica o índice do registro inicial (`offset`) e o número de registros a retornar (`page-size`).


A tabela abaixo resume qual estilo se aplica a cada endpoint paginado.

| Endpoint | Estilo | Parâmetro de tamanho da página | Padrão | Máximo |
|  --- | --- | --- | --- | --- |
| `GET /v3/identities` | Baseada em token | `limit` | 10 | 100 |
| `GET /v3/identities/{identity-id}/financial-instruments` | Baseada em token | `limit` | 10 | 100 |
| `POST /v3/payments/filter` | Baseada em token (corpo da requisição) | `page.size` | 20 | 100 |
| `GET /v2/ledger-transactions` | Por offset | `page-size` | 25 | 50 |


## Paginação baseada em token

A paginação baseada em token usa um token de string opaco para marcar a sua posição em um conjunto de resultados. Quando a API retorna um `nextToken` na resposta, há mais resultados disponíveis. Quando o `nextToken` está ausente, você chegou à última página.

Os tokens são opacos e podem mudar entre releases. Não tente decodificar, interpretar nem construir valores de token.

### Identidades e instrumentos financeiros

Em `GET /v3/identities` e `GET /v3/identities/{identity-id}/financial-instruments`, informe os parâmetros de paginação como parâmetros de consulta.

**Parâmetros da requisição:**

| Parâmetro | Tipo | Obrigatório | Descrição |
|  --- | --- | --- | --- |
| `limit` | integer | Não | Número máximo de registros a retornar. O padrão é 10 e o máximo é 100. |
| `next-token` | string | Não | Token opaco retornado pela resposta anterior. Omita este parâmetro para começar do início. |


**Exemplo: primeira página**

```bash
curl -X GET "https://{base-url}/v3/identities?limit=25" \
  -H "Authorization: Bearer <access_token>"
```

**Exemplo de resposta (há mais páginas disponíveis):**

```json
{
  "data": [
    { "identityId": "abc123", "identityType": "INDIVIDUAL", "..." },
    { "..." }
  ],
  "nextToken": "eyJrZXkxIjoidmFsdWUifQ=="
}
```

**Exemplo: página seguinte**

```bash
curl -X GET "https://{base-url}/v3/identities?limit=25&next-token=eyJrZXkxIjoidmFsdWUifQ==" \
  -H "Authorization: Bearer <access_token>"
```

Quando a resposta não inclui o campo `nextToken`, você já recuperou todos os registros disponíveis.

### Busca de pagamentos

O endpoint `POST /v3/payments/filter` usa paginação baseada em token, mas os parâmetros de paginação são informados no **corpo da requisição**, e não como parâmetros de consulta.

**Campos de paginação do corpo da requisição:**

| Campo | Tipo | Obrigatório | Descrição |
|  --- | --- | --- | --- |
| `page.size` | integer | Não | Número de pagamentos a retornar por página. O padrão é 20 e o máximo é 100. |
| `page.lastPageToken` | string | Não | Token retornado na resposta anterior. Omita para recuperar a primeira página. |


**Exemplo: primeira página**

```bash
curl -X POST "https://{base-url}/v3/payments/filter" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "paymentStates": ["COMPLETED"]
    },
    "sort": {
      "sortField": "CREATED_AT",
      "sortDirection": "DESC"
    },
    "page": {
      "size": 20
    }
  }'
```

**Exemplo de resposta (há mais páginas disponíveis):**

```json
{
  "data": [ { "..." } ],
  "filter": { "..." },
  "sort": { "..." },
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}
```

**Exemplo: página seguinte**

Inclua o valor de `lastPageToken` da resposta anterior no corpo da próxima requisição:

```json
{
  "page": {
    "size": 20,
    "lastPageToken": "eyJsYXN0SWQiOiJhYmMxMjMifQ=="
  }
}
```

Quando a resposta não inclui o campo `page.lastPageToken`, você já recuperou todos os pagamentos correspondentes.

## Paginação por offset

O endpoint `GET /v2/ledger-transactions` usa paginação por offset. Você controla a janela de resultados com dois parâmetros: `page-size` (quantos registros retornar) e `offset` (quantos registros pular).

**Parâmetros da requisição:**

| Parâmetro | Tipo | Obrigatório | Descrição |
|  --- | --- | --- | --- |
| `page-size` | integer | Sim | Número de registros a retornar. O padrão é 25 e o máximo é 50. |
| `offset` | integer | Não | Número de registros a pular antes de retornar resultados. O padrão é 0 (começa do início). |


A resposta inclui um campo `total` com a contagem geral de registros correspondentes. Use `total`, `pageSize` e `pageElements` para determinar se existem páginas adicionais.

**Campos da resposta:**

| Campo | Tipo | Descrição |
|  --- | --- | --- |
| `total` | integer | Número total de registros que correspondem aos filtros da requisição. |
| `pageSize` | integer | Número de registros solicitados por página (reflete o parâmetro `page-size`). |
| `pageElements` | integer | Número de registros efetivamente retornados nesta resposta. |
| `offset` | integer | Número de registros pulados (reflete o parâmetro `offset`). |


**Exemplo: primeira página**

```bash
curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25" \
  -H "Authorization: Bearer <access_token>"
```

**Exemplo de resposta:**

```json
{
  "offset": 0,
  "pageSize": 25,
  "pageElements": 25,
  "total": 83,
  "statementTransactions": [ { "..." } ]
}
```

**Exemplo: segunda página**

Com `total=83` e `pageSize=25`, a segunda página começa em `offset=25`:

```bash
curl -X GET "https://{base-url}/v2/ledger-transactions?currency=USD&start-dttm=2026-01-01T00:00:00Z&end-dttm=2026-01-31T23:59:59Z&page-size=25&offset=25" \
  -H "Authorization: Bearer <access_token>"
```

Você recuperou todos os registros quando `offset + pageElements >= total`.

## Boas práticas

**Use o tamanho máximo de página em recuperações em massa.** Quando o seu objetivo é recuperar todos os registros (por exemplo, para conciliação), defina `limit` ou `page-size` no valor máximo permitido para reduzir o número de requisições.

**Verifique a ausência do `nextToken`, não o valor dele.** Nos endpoints baseados em token, o sinal correto de que você chegou à última página é a ausência de `nextToken` (ou de `page.lastPageToken`) na resposta, e não um valor de token específico.

**Não modifique nem construa tokens.** Os tokens são opacos. Uma lógica que interprete ou concatene valores de token vai quebrar quando o formato do token mudar.

**Considere os registros adicionados durante a recuperação.** A paginação por offset sobre um conjunto de resultados que muda ativamente pode gerar lacunas ou duplicatas. Em transações de ledger, use um intervalo de tempo fixo (`start-dttm` e `end-dttm`) para garantir que o conjunto de resultados não mude enquanto você pagina por ele.

**Não armazene tokens em cache entre sessões.** Os tokens são válidos apenas na sessão em que foram emitidos. Sempre inicie uma nova sequência de paginação para cada novo trabalho de recuperação.