> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Paginação
> Paginação baseada em páginas nos endpoints de listagem da Lerian, com parâmetros page e limit e uma estrutura de carga paginada consistente.
Gerenciar grandes conjuntos de dados de forma eficiente é crucial para manter o desempenho e a escalabilidade da API. Nossas APIs empregam um mecanismo robusto de paginação para entregar dados em porções menores e gerenciáveis. Isso melhora os tempos de resposta e o processamento no lado do cliente, particularmente para aplicações que carregam resultados de forma incremental.
## Paginação em nossas APIs
***
Em vez de retornar o conjunto de dados inteiro em uma única resposta, o que pode sobrecarregar recursos, os clientes podem solicitar subconjuntos específicos de dados. Isso melhora os tempos de resposta e permite um tratamento de dados mais suave, particularmente para aplicações que carregam resultados de forma incremental.
Suportamos dois parâmetros de consulta para paginação:
* `page` (inteiro): Especifica o número da página a ser recuperada. O valor padrão é `1`.
* Valores negativos são inválidos e resultarão em erro.
* `limit` (inteiro): Define o número máximo de itens por página. O valor padrão é `10`.
Por exemplo, para recuperar a primeira página de organizações com no máximo 10 itens por página:
```http HTTP theme={null}
GET /v1/organizations?page=1&limit=10
```
### Resposta de paginação
A resposta de paginação inclui a seguinte estrutura:
* `items`: Um array de entidades recuperadas para a página atual. Cada objeto contém informações detalhadas sobre o recurso solicitado, conforme mostrado no exemplo abaixo.
* `page`: O número da página atual, começando em `1` (padrão).
* `limit`: O número máximo de itens incluídos na resposta, conforme definido na requisição ou na configuração padrão.
Abaixo está um exemplo de resposta para uma requisição paginada:
```jsonon JSON expandable theme={null}
{
"items": [
{
"id": "0193696f-8eff-7926-a77a-0b424cf7156b",
"parentOrganizationId": null,
"legalName": "Collins Inc",
"doingBusinessAs": "The ledger.io",
"legalDocument": "78425230000190",
"address": {
"line1": "Avenida Paulista, 1234",
"line2": "CJ 203",
"zipCode": "01310916",
"city": "New Lyla",
"state": "CH",
"country": "FO"
},
"status": {
"code": "ACTIVE",
"description": "Ledger Test"
},
"createdAt": "2024-11-26T17:05:39.071587Z",
"updatedAt": "2024-11-26T17:05:39.071587Z",
"deletedAt": null,
"metadata": {
"bitcoinn": "3QH2XV7JxMRKXDqh87JG7LWuf7AeGfy",
"boolean": true,
"chave": "metadata_chave",
"double": 10.5,
"int": 1
}
}
],
"page": 1,
"limit": 1
}
```
### Tamanho máximo da página
Por padrão, os endpoints da API que suportam paginação aceitam no máximo **100 itens por página** (`limit=100`). Essa restrição ajuda a garantir um desempenho ideal e evita tamanhos excessivos de payload.
Se seu caso de uso requer a recuperação de um número maior de itens por requisição, você pode substituir esse limite definindo a variável de ambiente `MAX_PAGINATION_LIMIT` na configuração da sua implantação (arquivo `.env`).
Aumentar o limite de paginação pode resultar em tempos de resposta mais lentos, dependendo do volume de dados e das condições da infraestrutura. Certifique-se de testar completamente em ambientes de homologação antes de aplicar a mudança em produção.
Para atualizar essa configuração no Kubernetes:
```bash bash theme={null}
kubectl edit configmap midaz-transaction -n midaz
# Set the new value for MAX_PAGINATION_LIMIT
kubectl rollout restart deployments midaz-transaction -n midaz
```
O Midaz e todos os seus serviços de plugins herdam esse comportamento.
## Paginação baseada em cursor
***
Alguns endpoints utilizam paginação baseada em cursor em vez de números de página. Essa abordagem é mais eficiente para grandes conjuntos de dados e garante resultados consistentes mesmo quando os dados são modificados entre as requisições.
Endpoints com paginação por cursor aceitam os seguintes parâmetros de consulta:
* `cursor` (string): Um token codificado de uma resposta anterior (`next_cursor` ou `prev_cursor`) para navegar para frente ou para trás. Omita este parâmetro para começar do início.
* `limit` (inteiro): O número máximo de itens por página. O valor padrão é `10`.
* `sort_order` (string): A direção utilizada para ordenar os resultados. Valores aceitos: `asc` (ascendente, padrão) ou `desc` (descendente).
Ao paginar com um `cursor` de uma resposta anterior, não é possível alterar o `sort_order` durante a paginação. Os parâmetros de ordenação devem ser definidos na requisição inicial e permanecer consistentes ao longo da sequência de paginação.
Por exemplo, para recuperar saldos usando paginação por cursor:
```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10
```
### Resposta da paginação por cursor
A resposta inclui a seguinte estrutura:
* `items`: Um array de entidades para a página atual.
* `next_cursor`: Um token codificado para recuperar a próxima página. Se ausente ou vazio, não há mais resultados.
* `prev_cursor`: Um token codificado para recuperar a página anterior. Se ausente ou vazio, você está na primeira página.
* `limit`: O número máximo de itens incluídos na resposta.
Para navegar para a próxima página, passe o valor de `next_cursor` como o parâmetro de consulta `cursor`:
```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10
```
Abaixo está um exemplo de resposta para uma requisição com paginação por cursor:
```json JSON theme={null}
{
"items": [
{
"id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
"organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
"ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
"alias": "customer-brl-1",
"key": "default",
"assetCode": "BRL",
"available": "1000",
"onHold": "0"
}
],
"next_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0Ijp0cnVlfQ==",
"prev_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0IjpmYWxzZX0=",
"limit": 10
}
```
### Quais endpoints usam paginação por cursor?
Os seguintes endpoints utilizam paginação baseada em cursor:
* **Listar Transações** — `GET /v1/organizations/{id}/ledgers/{id}/transactions`
* **Listar Saldos** — `GET /v1/organizations/{id}/ledgers/{id}/balances`
* **Listar Operações por Conta** — `GET /v1/organizations/{id}/ledgers/{id}/accounts/{id}/operations`
* **Listar Tipos de Conta** — `GET /v1/organizations/{id}/ledgers/{id}/account-types`
* **Listar Rotas de Operação** — `GET /v1/organizations/{id}/ledgers/{id}/operation-routes`
* **Listar Rotas de Transação** — `GET /v1/organizations/{id}/ledgers/{id}/transaction-routes`
Os demais endpoints de listagem utilizam a paginação padrão baseada em página descrita acima.