Paginação

A Leads2b oferece paginação para a maioria dos endpoints de listagem de itens da nossa API.

Paginação com page + limit (limit-offset)

Alguns endpoints oferecem paginação tradicional baseada em página e limite (limit-offset). Nesse modo, os parâmetros de consulta são page (número da página, 1-based) e limit (quantidade de itens por página). As respostas incluem um objeto pagination com informações sobre a página atual, total de itens, número total de páginas, e links para navegação.

Exemplo de requisição inicial:

GET /v2/orders/search?page=1&limit=1

Exemplo de resposta (limit-offset):

{
  "data": [
    {
      "id": 19,
      "date": null,
      "fk_id": null,
      ...,
      "items": []
    }
  ],
  "pagination": {
    "page": 1,
    "total": 34,
    "total_pages": 34,
    "limit": 1,
    "has_next": true,
    "has_prev": false,
    "links": {
      "self": "/v2/orders/search?page=1&limit=1",
      "first": "/v2/orders/search?page=1&limit=1",
      "last": "/v2/orders/search?page=34&limit=1",
      "next": "/v2/orders/search?page=2&limit=1",
      "prev": null
    }
  },
  "meta": {
    "timestamp": "2026-04-02T18:02:35.534Z",
    "version": "1.0.0"
  }
}

Os campos principais do objeto pagination são:

• page: número da página atual (1-based).
• total: total de itens disponíveis.
• total_pages: número total de páginas.
• limit: limite de itens por página.
• has_next / has_prev: flags booleanas indicando se há próxima/anterior.
• links: URLs self, first, last, next e prev para navegação.

Use page e limit nas requisições para navegar quando o endpoint suportar esse modo de paginação.

Ordenação (sort)

Você pode controlar a ordenação dos resultados usando o parâmetro sort nas requisições que suportam paginação por page + limit. O formato é uma string com campos separados por vírgula. Para ordenar de forma decrescente, prefixe o campo com -. Exemplos:

• sort=name — ordena por name em ordem ascendente.
• sort=-created_at — ordena por created_at em ordem decrescente.
• sort=name,-created_at — ordena por name ascendente e, em caso de empate, por created_at descendente.

Se sort não for informado, o comportamento padrão utiliza as configurações do servidor. Combine sort com page/limit para paginar os resultados já ordenados.

Paginação com cursor

Nossa paginação é feita através de cursor, que nada mais é que um identificador utilizado para percorrer as páginas de resultados. O cursor é retornado na resposta da API e deve ser utilizado na próxima requisição para obter a próxima página.

Os endpoints que utilizam paginação com cursor retornam um objeto com os campos size e next_cursor, além do data. O campo size indica a quantidade de itens retornados na página atual, e next_cursor é o cursor que deve ser utilizado na próxima requisição. Portanto, para obter a próxima página de resultados, deve-se informar no parâmetro cursor o valor de next_cursor retornado na resposta da requisição anterior, em conjunto com o parâmetro limit, que indica a quantidade de itens por página. Desta forma, é estabilecida a navegação sequencial.

Exemplo de Paginação

Requisição Inicial

Para obter os primeiros resultados, faça uma requisição ao endpoint desejado sem o parâmetro cursor:

GET /items?limit=3

Resposta

A API retornará um JSON contendo os dados da página atual e o next_cursor para a próxima requisição:

{
  "size": 3,
  "next_cursor": "dyz",
  "data": [
    { "id": "ayz", "name": "Item A" },
    { "id": "byz", "name": "Item B" },
    { "id": "cyz", "name": "Item C" }
  ]
}

Próxima Página

Para obter a próxima página de resultados, utilize o valor de next_cursor retornado na resposta anterior:

GET /items?limit=3&cursor=dyz

Reposta da próxima página

{
  "data": [
    { "id": "dyz", "name": "Item D" },
    { "id": "eyz", "name": "Item E" },
    { "id": "fyz", "name": "Item F" }
  ],
  "size": 3,
  "next_cursor": "gyz"
}

Esse processo pode ser repetido até que a API retorne next_cursor: null, indicando que não há mais resultados disponíveis.