# Introdução

Nesta página, você encontrará todas as informações necessárias sobre como a paginação e filtragem funcionam com a API da Belvo.

Artigo Não Se Aplica ao Débito Direto México
Este artigo não se aplica ao nosso produto de Débito Direto (Pagamentos) no México.

## Paginação

Recomendamos fortemente que você use o parâmetro de consulta `link` em suas requisições de **List** para que você receba apenas os resultados para um determinado `link.id`.

### Aumentar page_size

Ao usar o método **List**, por padrão, você receberá 100 resultados por página. No entanto, você pode aumentar isso para um máximo de 1000 resultados usando o parâmetro de consulta `page_size`:

```shell Exemplo de Aumento de Page Size
curl --request GET \
--url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000'
```

### Propriedades de navegação

Na resposta para qualquer solicitação de **Lista**, você receberá propriedades de navegação na raiz da resposta para auxiliá-lo em suas solicitações subsequentes:

```json Propriedades de Navegação
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados, dependendo do parâmetro page_size.
}
```

| Parâmetro | Descrição |
|  --- | --- |
| `count` | O número total de resultados para sua consulta. |
| `next` | Se disponível, a próxima página de resultados. Se nenhuma página estiver disponível, isso é definido como `null`. |
| `previous` | Se disponível, a página anterior de resultados. Se nenhuma página estiver disponível, isso é definido como `null`. |
| `results` | Um array de resultados para sua consulta. |


No caso de haver mais resultados do que o limite superior definido por `page_size`, você precisará usar o valor do parâmetro `next` para receber a próxima página de resultados (que usa o parâmetro de consulta `page`).

Por exemplo, no caso de você fazer a seguinte chamada de Lista, definindo `page_size` para `1000`:

```shell Exemplo de Solicitação de Lista
curl --request GET \
     --url 'https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000' \
     --header 'accept: application/json'
```

Você receberá a seguinte resposta JSON:

```json Exemplo de Resposta Com Propriedade de Navegação 'next'
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados
}
```

Parâmetros de consulta propagados
Como você pode ver nos exemplos, quaisquer parâmetros de consulta que você fornecer são então propagados para o valor `next`. Por exemplo, na solicitação inicial enviamos `?link=link_id&page_size=1000`, e na resposta, podemos ver que esses parâmetros de consulta são mantidos na nova URL no parâmetro `next`: `?link=link_id&page_size=1000&page=2`.

Você pode então usar a URL no parâmetro `next` para fazer suas chamadas de API seguintes até que `next` seja igual a `null`. No bloco de código abaixo, fornecemos um exemplo de todas as respostas dadas essa situação:

```json Resposta inicial
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "previous": null,
  "results": [] // Até 1000 resultados
}
```

```json Segunda resposta
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=1",
  "results": [] // Até 1000 resultados
}
```

```json Terceira resposta
{
  "count": 3542,
  "next": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=4",
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=2",
  "results": [] // Até 1000 resultados
}
```

```json Resposta final
{
  "count": 3542,
  "next": null,
  "previous": "https://sandbox.belvo.com/api/transactions/?link=link_id&page_size=1000&page=3",
  "results": [] // Até 1000 resultados
}
```

## Filtrando Respostas

Usar filtros na sua solicitação pode reduzir significativamente o tamanho da resposta do servidor, além de garantir que você elimine qualquer dado que não precise para realizar o trabalho.

### Obter apenas certos campos

Você pode usar os filtros `fields` e `omit` na sua consulta de URL para definir quais campos você deseja receber na resposta JSON da API da Belvo. Recomendamos que você use esses campos exclusivamente, ou seja, não combine `fields` e `omit` na mesma consulta. Além disso, você só pode usar os filtros `fields` e `omit` em campos de nível raiz (e não em campos aninhados).

| Parâmetro | Uso | Exemplo |
|  --- | --- | --- |
| `fields` | Quando você quer incluir apenas esses campos na sua resposta | `https://sandbox.belvo.com/api/{endpoint}/?fields=field1,field2` |
| `omit` | Quando você não quer que os campos especificados sejam incluídos na sua resposta | `https://sandbox.belvo.com/api/{endpoint}/?omit=field3,field4` |


Isso é particularmente útil se você deseja minimizar o tamanho do conteúdo das respostas da API. Por exemplo, ao consultar o endpoint de contas, em vez de receber a resposta completa do servidor, você pode adicionar `?fields=id,balance` ao final da sua consulta para obter apenas o ID da conta e o saldo (veja a aba **Filtrado** no exemplo de código abaixo).

Não Filtrado
Quando não se usa `filter`, o tamanho do conteúdo desta resposta é de `341 Bytes`.

```shell Unfiltered Request
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/' \
     --header 'accept: application/json'
```

```json Unfiltered Response
{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "type":"Créditos",
  "name":"CRED PREST BANAMEX",
  "number":null,
  "category":"LN",
  "collected_at":"2019-08-13T08:00:44.251929Z",
  "bank_product_id":"18",
  "currency":"MXN",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  },
  "link":"2259b916-41ec-4dcb-9a01-7865d9c0657e",
  "internal_identification":"1"
}
```

Filtrado
Usando `filter` para recuperar apenas o `id` e o `balance`, o tamanho do conteúdo das respostas diminui para `73 Bytes`

```shell Filtered Request
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance' \
     --header 'accept: application/json'
```

```json Filtered Response
{
  "id":"5a772f98-befc-4217-8ae7-a087e73a7c28",
  "balance": {
      "current": 63054.93,
      "available": 62985.22
  }
}
```

### Filtrar dados de resposta com operadores

Você pode usar filtros adicionais na sua consulta de URL para restringir as respostas que recebe. A Belvo suporta os seguintes operadores para suas consultas:

Campos Filtráveis por Endpoint
Para saber quais campos você pode filtrar na string de consulta (incluindo campos aninhados), confira a seção **Query** do método LIST para qualquer recurso em nossa documentação de referência da API. Por exemplo, aqui estão os parâmetros de consulta para nosso recurso de Contas.

Se você perceber que não consegue filtrar um determinado campo e gostaria de fazê-lo, entre em contato com o Suporte da Belvo em support@belvo.com

| Operador | Use quando você quiser | Exemplo |
|  --- | --- | --- |
| `=` | Obter resultados que correspondem exatamente a um valor. | `fieldA=OpenFinance` |
| `gt` | Obter resultados que são maiores que um determinado valor. | `fieldA__gt=5000` |
| `lt` | Obter resultados que são menores que um determinado valor. | `fieldA__lt=6000` |
| `gte` | Obter resultados que são maiores ou iguais a um determinado valor. | `fieldA__gte=5000` |
| `lte` | Obter resultados que são menores ou iguais a um determinado valor. | `fieldA__lte=6000` |
| `in` | Obter resultados para qualquer um dos elementos listados. Funciona com strings. | `fieldA__in=monday,wednesday,friday` |
| `range` | Obter resultados que estão entre dois valores. Funciona com datas e números. Separe os dois valores com uma vírgula. | `fieldA__range=1,5` |
| `&` | Combinar consultas. | `query1&query2` |


Para usar os operadores, basta adicioná-los ao final da URL da sua solicitação como campos de consulta. Lembre-se de usar duplo sublinhado, `__`, entre o campo e o operador e o e comercial, `&`, para encadear campos de consulta juntos. O exemplo abaixo retornará apenas contas onde a `currency` é `BRL` e o `balance_available` está entre `3000` e `5000`:

```shell Exemplo de Solicitação de Consulta Encadeada
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?currency=BRL&balance_available__range=3000,5000' \
     --header 'accept: application/json'
```

### Campos aninhados de destino

Você pode querer direcionar campos aninhados dentro da resposta. No exemplo abaixo, se você quiser direcionar o campo `current`, o caminho da consulta seria: `account__balance__current`. Observe que os duplos sublinhados (`__`) são usados para indicar que um campo está aninhado dentro de outro campo.

```json Exemplo de JSON para Campos Aninhados de Destino
{
  "accounts": {
    "link": "57f212dc-1ba4-407f-b7f0-15a5e5ff17ae",
    "category": "CHECKING_ACCOUNT",
    "type": "Cuentas de efectivo",
    "number": "002180700688677950",
    "balance": {
      "available": 4523.48,
      "current": 4523.48
    }
  }
}
```

No exemplo de requisição abaixo, estamos combinando o direcionamento de um campo aninhado (`account__balance__current`) com o operador `range`. Note que tanto para o campo aninhado quanto para o operador, adicionamos duplos sublinhados (`__`).

```shell Exemplo de Requisição para Campos Aninhados de Destino
curl --request GET \
     --url 'https://sandbox.belvo.com/api/accounts/?account__balance__current__range=3000,5000' \
     --header 'accept: application/json'
```

Campos Filtráveis por Endpoint
Para saber quais campos você pode filtrar na string de consulta (incluindo campos aninhados), confira a seção **Query** do método LIST para qualquer recurso em nossa documentação de referência da API. Por exemplo, aqui estão os parâmetros de consulta para nosso recurso de Contas.

Se você descobrir que não consegue filtrar um determinado campo e gostaria de fazê-lo, entre em contato com o Suporte da Belvo em support@belvo.com

### Exemplos

### Transação igual a um determinado ID

Use `id={o-id-que-você-deseja}`:

```shell Exemplo de Transação Igual a um Determinado ID
https://sandbox.belvo.com/api/transactions/?id=2259b916-41ec-4dcb-9a01-7865d9c0657e
```

#### Transações de uma conta com determinado saldo

Use `account__balance__current__gt={value}`. Você precisará usar duplo sublinhado para obter o saldo atual, pois o campo `current` está aninhado com `balance` e `account`:

```shell Exemplo de Transação de uma Conta com Determinado Saldo
https://sandbox.belvo.com/api/transactions/?account__balance__current__gt=1000
```

#### Detalhes da conta para um de muitos IDs de conta

Use `id__in={id1},{id2},{id3}`:

```shell Exemplo de Detalhes da Conta para muitos IDs de Conta
https://sandbox.belvo.com/api/accounts/?id__in=
2259b916-41ec-4dcb-9a01-7865d9c0657e,
5a772f98-befc-4217-8ae7-a087e73a7c28,
574d4a4f-1101-4bb0-bb7c-e27a440af507
```

#### Links com um determinado external_id

Use `external_id={id}`:

```shell Exemplo de External ID
https://sandbox.belvo.com/api/links/?external_id={id}
```