Paginação

Todos os endpoints da API que retornam uma lista de itens são paginados. Para navegar entre as páginas há parâmetros específicos.

Estrutura de Resposta Paginada

Todos os métodos de listagem possuem uma estrutura em comum, que é a de paginação.

JSON

{
  "data": [],
  "page": 1,
  "limit": 20,
  "total": 150
}

Campos da Resposta

Campo	Tipo	Descrição
data	Array	Lista de itens retornados na página atual
page	Number	Número da página atual
limit	Number	Quantidade de itens por página (máximo 100)
total	Number	Quantidade total de itens disponíveis

---

Parâmetros de Paginação

Para navegar entre as páginas, utilize os seguintes parâmetros na query string:

page

Número da página que você deseja acessar.

• Tipo: Integer
• Padrão: 1
• Mínimo: 1

Exemplo:

Bash

GET /api/v1/clients?page=2

limit

Quantidade de itens por página.

• Tipo: Integer
• Padrão: 20
• Mínimo: 1
• Máximo: 100

Exemplo:

Bash

GET /api/v1/clients?limit=50

📘

Limite máximo

Cada página possui limite máximo de 100 registros. Caso a propriedade limit possua um valor superior, esse valor será substituído pelo limite de registros.

---

Combinando Paginação com Filtros

Você pode combinar os parâmetros de paginação com outros filtros disponíveis:

Exemplo: Buscar clientes ativos na página 2

Requisição:

Bash

curl -X GET "https://api.belasis.com.br/api/v1/clients?page=2&limit=20&active=true" \\
  -H "Content-Type: application/json" \\
  -H "ACCESS-TOKEN: bpk_sua_chave_aqui"

Exemplo: Buscar clientes por nome na página 1

Requisição:

Bash

curl -X GET "https://api.belasis.com.br/api/v1/clients?page=1&limit=30&search=Maria" \\
  -H "Content-Type: application/json" \\
  -H "ACCESS-TOKEN: bpk_sua_chave_aqui"

Resposta:

JSON

{
  "data": [
    {
      "id": 2,
      "name": "Maria Santos",
      "phone": "(11) 99999-8888"
    },
    {
      "id": 15,
      "name": "Maria da Silva",
      "phone": "(11) 88888-7777"
    }
    // ... outros registros que contêm "Maria" no nome
  ],
  "page": 1,
  "limit": 30,
  "total": 45
}

📘 Nota importante

O campo total na resposta reflete a quantidade total de registros após aplicar os filtros. No exemplo acima, existem 45 clientes com "Maria" no nome, não o total geral de clientes.

---

Navegando Entre Páginas

Verificar se existe próxima página

Use a seguinte lógica:

JavaScript

const hasNextPage = (page * limit) < total;

Exemplo:

JavaScript

// Resposta da API
const response = {
  page: 2,
  limit: 20,
  total: 150
};

// Verificar se há próxima página
const hasNextPage = (response.page * response.limit) < response.total;
// (2 * 20) < 150 = 40 < 150 = true

Verificar se existe página anterior

JavaScript

const hasPreviousPage = page > 1;

---

Boas Práticas

✅ Recomendações

• Use um limit adequado para sua aplicação (evite solicitar muitos registros de uma vez)
• Implemente navegação de páginas em sua interface (botões "Anterior" e "Próximo")
• Armazene o total para calcular o número de páginas disponíveis
• Combine paginação com filtros para melhorar o desempenho

❌ Evite

• Não use valores muito altos para limit (máximo é 100)
• Não ignore o campo total - ele é importante para navegação
• Não assuma que todas as páginas terão o mesmo número de registros (a última página pode ter menos itens)