Estrutura de Resposta Paginada

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

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

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:

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:

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:

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:

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

const hasNextPage = (page * limit) < total;

Exemplo:

// 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

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)