# Paginação Baseada em Cursor

## Melhorias na Paginação

Para melhorar o desempenho e a confiabilidade da nossa API, estamos migrando progressivamente nossos métodos de Lista para paginação baseada em cursor. Esta atualização foi projetada para proporcionar uma experiência mais estável e eficiente, especialmente ao lidar com grandes volumes de dados.

Estrutura Obsoleta
A paginação baseada em cursor irá **substituir** os objetos `_links` e `metadata` anteriores:


```json Estrutura de Paginação Obsoleta
{
  "_links": {
    "first": "/{resource}?limit=20",
    "last": "/{resource}?page=4&limit=20",
    "next": "/{resource}?page=3&limit=20",
    "previous": "/{resource}?page=2&limit=20"
  },
  "metadata": {
    "totalItems": 100,
    "itemCount": 10,
    "itemsPerPage": 10,
    "totalPages": 10,
    "currentPage": 1
  }
}
```

## Como Funciona

### Estrutura

Com a introdução da paginação baseada em cursor, a estrutura das respostas da nossa API para métodos de Lista será atualizada. Aqui está uma visão do novo formato (veja a chave de paginação):


```json Exemplo de Token de Cursor
{
  "items": [
    // Objetos de recurso
  ],
  "pagination": { // [!code highlight]
    "nextCursorToken": "eyJpZCI6IjBkMWEzNzdiLWI0YzUtNGE5NC05ZTJlLTgzZTU5ZDFmNmE5YyIsImNyZWF0ZWREYXRlIjoiMjAyNS0wNy0wMlQxMjozNDo1NloifQ==", // [!code highlight]
    "previousCursorToken": null, // [!code highlight]
  }
}
```

### Navegando pelos Resultados

Para navegar pelos resultados paginados, você usará o `nextCursorToken` (ou `previousCursorToken`) de uma resposta como um parâmetro na sua próxima solicitação. Por exemplo:

1. **Solicitação Inicial**: Sua primeira solicitação para um endpoint de Lista não incluirá um `nextCursorToken`.

```shell Chamada Inicial da API
curl GET baseUrl/account_movements?limit=100
```
2. **Solicitações Subsequentes**: Para recuperar o próximo conjunto de resultados, pegue o valor `nextCursorToken` do objeto de paginação na resposta e use-o como o parâmetro de consulta `nextCursorToken` na sua próxima chamada. No caso de você querer o conjunto anterior de resultados, pegue o valor `previousCursorToken` e passe-o como o parâmetro de consulta `previousCursorToken`.

```shell Chamadas Subsequentes da API
# Avançando
GET baseUrl/account_movements?limit=100&nextCursorToken={pagination.nextCursorToken}

# Retrocedendo
GET baseUrl/account_movements?limit=100&previousCursorToken={pagination.previousCursorToken}
```


Você pode continuar fazendo solicitações com o novo `nextCursorToken` ou `previousCursorToken` de cada resposta até que o valor do campo seja `null` (indicando que não há mais resultados).

## Endpoints Atualmente Suportados

Estamos implementando esta melhoria em nossa API. Os seguintes métodos de Lista atualmente suportam paginação baseada em cursor:

- `GET baseUrl/account_movements` (Em Produção em 5 de agosto de 2025)
- `GET baseUrl/payment_requests` (Em Produção em 5 de agosto de 2025)
- `GET baseUrl/payment_methods` (Em Produção em 8 de agosto de 2025)
- `GET baseUrl/customers` (Em Produção em 22 de agosto de 2025)
- `GET baseUrl/consents` (Em Produção em 22 de agosto de 2025)


## Como Adotar a Nova Paginação

Projetamos a transição para ser o mais suave possível.

- **Para Novos Clientes:** A paginação baseada em cursor é ativada por padrão para todos os novos clientes.
- **Para Clientes Existentes:** Assim que você atualizar sua integração para lidar com o novo formato de resposta e solicitação de paginação, entre em contato com nossa equipe de suporte. Em seguida, ativaremos esse recurso para sua conta.


## Lista de Verificação de Migração

- [ ] Atualizar a análise de resposta para usar o objeto `pagination`
- [ ] Substituir a lógica baseada em páginas pelo manuseio de token de cursor
- [ ] Testar com seus filtros e ordenações existentes
- [ ] Entrar em contato com o suporte para habilitar a paginação por cursor