> ## Documentation Index
> Fetch the complete documentation index at: https://docs.procfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paginação

## **Introdução**

O Procfy utiliza o padrão de paginação para retornar os resultados das requisições. A paginação é utilizada para dividir os resultados em páginas, facilitando a visualização e a navegação entre os resultados.

A paginação é utilizada em todas as rotas que retornam uma lista de resultados. Por exemplo, a rota de [visualizar várias transações](/transacoes#visualizar-várias-transações) retorna uma lista de transações, e utiliza a paginação para dividir os resultados em páginas.

A paginação é controlada através dos parâmetros `page` e `itens`. O parâmetro `page` indica o número da página, e o parâmetro `itens` indica a quantidade de itens por página.

| Parâmetro | Tipo    | Descrição                      |
| :-------- | :------ | :----------------------------- |
| page      | integer | Número da página               |
| items     | integer | Quantidade de itens por página |

#### **Valores aceitos para os parâmetros**

### **página**

O parâmetro `page` deve ser um número inteiro maior que zero. O valor padrão é `1`.

### **itens**

O parâmetro `items` deve ser um número inteiro maior que zero. O valor padrão é `25`.

<Info>
  O valor máximo para o parâmetro `items` é `50`. Caso o valor informado seja maior que `50`, será utilizado 50 como valor padrão.
</Info>

***

#### Exemplo

Vamos fazer uma requisição para a API para listar todas as transações. Para isso, vamos utilizar o endpoint `GET api/v1/transactions`.

A primeira requisição pode ser feita sem a inclusão de parâmetros, o que a API interpretará como a solicitação da primeira página. Caso deseje acessar uma página específica, basta fornecer o número da página no parâmetro `page`.

Observe que os objetos que estão dentro da paginação são retornados no atributo `data`. Se os objetos forem de outro tipo, como contas bancárias, os nomes dos objetos presentes na página também serão incluídos no atributo `data`. Veja mais sobre isso na seção [Acessando objetos de uma página](/paginacao#acessando-objetos-de-uma-página).

Exemplo de requisição para listar todas as transações (1ª página)

```text theme={null}
GET /api/v1/transactions
```

Exemplo de resposta para listar todas as transações (1ª página)

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 25,
    "pages": 2,
    "last": 2,
    "next": 2,
    "prev": null,
    "count": 39,
    "from": 1,
    "to": 25
  },
  "data": [...]
}
```

Exemplo de requisição para listar todas as transações (2ª página)

```text theme={null}
GET /api/v1/transactions?page=2
```

```json theme={null}
{
  "page": {
    "page": 2,
    "items": 25,
    "pages": 2,
    "last": 2,
    "next": null,
    "prev": 1,
    "count": 39,
    "from": 26,
    "to": 39
  },
  "data": [...]
}
```

***

## **Acessando objetos de uma página**

Ao realizar requisições para listar objetos paginados, como transações ou contatos, a API retorna uma estrutura consistente para facilitar a manipulação e a navegação pelos dados. Vamos explorar dois exemplos: transações e contatos.

#### **Exemplo**

Ao requisitar a listagem de todas as transações, a resposta é um objeto contendo o atributo `data`, o qual encapsula uma lista de transações disponíveis. A estrutura adotada facilita a identificação e manipulação desses dados específicos.

De maneira análoga, ao requisitar a listagem de contatos, a resposta apresenta o atributo `data` contendo a lista correspondente. A estrutura é a mesma, independentemente do tipo de objeto solicitado.

#### **Exemplo Prático**

Considerando a requisição para listar transações, ao acessar response.data, você terá acesso direto à lista de transações retornadas. Essa abordagem proporciona clareza e praticidade ao trabalhar com objetos paginados em ambientes de programação.

> Exemplo de resposta de uma requisição para listar todas as transações (1ª página)

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 25,
    "pages": 2,
    "last": 2,
    "next": 2,
    "prev": null,
    "count": 39,
    "from": 1,
    "to": 25
  },
  "data": [...]
}
```

> Exemplo de resposta de uma requisição para listar todos os contatos (1ª página)

```json theme={null}
{
  "page": {
    "page": 1,
    "items": 25,
    "pages": 2,
    "last": 2,
    "next": 2,
    "prev": null,
    "count": 39,
    "from": 1,
    "to": 25
  },
  "data": [...]
}
```

> Exemplo de como acessar objetos de uma página

<CodeGroup>
  ```shellscript shell theme={null}
  #!/bin/bash

  API_URL="https://api.procfy.io/api/v1/transacoes?page=1"

  # Fazendo a requisição e armazenando a resposta em um arquivo temporário
  response_file=$(mktemp)
  curl -s "$API_URL" > "$response_file"

  # Acessando objetos de uma página
  transactions=$(jq -r '.transactions' "$response_file")

  # Agora, você pode manipular a lista de transações conforme necessário
  echo "$transactions"

  # Limpando o arquivo temporário
  rm "$response_file"
  ```

  ```ruby ruby theme={null}
  require 'httparty'

  response = HTTParty.get('https://api.procfy.io/api/v1/transacoes?page=1')

  # Acessando objetos de uma página
  transactions = response.parsed_response['transactions']

  # Agora, você pode manipular a lista de transações conforme necessário
  puts transactions
  ```

  ```python python theme={null}
  import requests

  api_url = 'https://api.procfy.io/api/v1/transacoes?page=1'

  response = requests.get(api_url)

  # Acessando objetos de uma página
  transactions = response.json()['transactions']

  # Agora, você pode manipular a lista de transações conforme necessário
  print(transactions)
  ```

  ```javascript javascript theme={null}
  const axios = require('axios');

  axios.get('https://api.procfy.io/api/v1/transacoes?page=1')
    .then(response => {
      // Acessando objetos de uma página
      const transactions = response.data.transactions;

      // Agora, você pode manipular a lista de transações conforme necessário
      console.log(transactions);
    })
    .catch(error => console.error(error));
  ```
</CodeGroup>

***

## **Erros**

#### **Parâmetros menores ou iguais a zero**

Se a requisição enviar o parâmetro `page` com um valor menor ou igual a zero, ou enviar o parametro `items` com um valor menor ou igual a zero, a API retornará os erros ao lado.

#### **Parâmetros maiores que o número de páginas**

Caso o parâmetro `page` seja maior que o número de páginas, a API retornará o erro ao lado.

> Enviando itens com valor menor ou igual a zero

```json theme={null}
{
  "error": "Pagination error",
  "description": "expected :items >= 1; got 0"
}
```

> Enviando page com valor menor ou igual a zero

```json theme={null}
{
  "error": "Pagination error",
  "description": "expected :page >= 1; got 0"
}
```

> Enviando page com valor `99`, sendo que o número de páginas é `2`

```json theme={null}
{
  "error": "Pagination error",
  "description": "expected :page in 1..2; got 99"
}
```