# Introdução

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

## Paginação

Use o parâmetro de consulta `link` ao listar
Recomendamos fortemente que você use o parâmetro de consulta `link` em suas solicitações de **List** para que você receba apenas 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`:


```curl
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
{
  "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`:


```curl
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
{
  "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 nesta situação:


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


```json
{
  "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
{
  "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
{
  "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 o filtro `fields` na sua consulta de URL para definir quais campos:

- Você deseja que sejam retornados na sua resposta.
`fields=field1,field2`
- Você deseja que sejam excluídos na sua resposta.
`omit=field1,field2`


Você só pode direcionar campos de primeiro nível, o que retornará quaisquer campos aninhados

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 **Filtered** no exemplo de código abaixo).


```shell
GET https://sandbox.belvo.com/api/accounts/5a772f98-befc-4217-8ae7-a087e73a7c28/

HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 341 Bytes # Tamanho não filtrado

{
  "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"
}
```


```shell
GET https://sandbox.belvo.com/api/accounts/
5a772f98-befc-4217-8ae7-a087e73a7c28/?fields=id,balance # Consulta filtrada

HTTP/1.1 200 OK
Content-Type: application/json
Content-Size: 73 Bytes # Resposta filtrada retornada

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

### Filtrar dados de resposta

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, confira nossa documentação de referência da API.
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

| 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 do campo de consulta (lembre-se de usar duplo sublinhado, `__`, entre o campo e o operador). O exemplo abaixo retornará apenas contas onde a `currency` é `COP` e o `balance_available` está entre `3000` e `5000`:

### Campos aninhados de destino

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


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

Abaixo você verá alguns exemplos de como aplicar filtros às suas chamadas 🤓.

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

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


```curl
https://api.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`:


```curl
https://api.belvo.com/api/transactions/?account__balance__current__gt=1000
```

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

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


```curl
https://api.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}`:


```curl
https://api.belvo.com/api/links/?external_id={id}
```