Paginação

Todos os endpoints de listagem da Liqi retornam resultados paginados. A API suporta paginação baseada em page e limit, permitindo navegar por grandes conjuntos de dados de forma eficiente.

Parâmetros de paginação

Parâmetro	Tipo	Padrão	Descrição
`page`	number	`1`	Número da página (começa em 1)
`limit`	number	`10`	Quantidade de itens por página (max: 100)

Exemplo de uso

Bash

# Primeira página, 10 itens
curl "https://api.liqi.com.br/public/tranches?page=1&limit=10"

# Segunda página, 20 itens
curl "https://api.liqi.com.br/public/tranches?page=2&limit=20"

# Combinando com filtros
curl "https://api.liqi.com.br/public/tranches?status=ACTIVE&page=1&limit=5"

Formato da resposta

Toda listagem paginada retorna um objeto com a seguinte estrutura:

JSON

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "ticker": "ROB1SR06",
      "name": "Robcap I - Série 06",
      "status": "ACTIVE"
    },
    {
      "id": "660f9511-f30c-52e5-b827-557766551111",
      "ticker": "ROB1SR07",
      "name": "Robcap I - Série 07",
      "status": "FUNDRAISING"
    }
  ],
  "count": 47,
  "page": 1,
  "limit": 10
}

Campos da resposta

Campo	Tipo	Descrição
`items`	array	Lista de objetos da página atual
`count`	number	Total de registros que correspondem ao filtro (todas as páginas)
`page`	number	Página atual retornada
`limit`	number	Limite de itens por página usado na consulta

Calculando páginas

Para calcular o total de páginas disponíveis:

TypeScript

const totalPages = Math.ceil(count / limit);

Exemplo

Com count: 47 e limit: 10:

Página	Itens retornados	Primeiro item	Último item
1	10	1	10
2	10	11	20
3	10	21	30
4	10	31	40
5	7	41	47

Navegação programática

Node.js — Buscar todas as páginas

TypeScript

async function fetchAllTranches() {
  const allItems: unknown[] = [];
  let page = 1;
  const limit = 50;

  while (true) {
    const response = await fetch(
      `https://api.liqi.com.br/public/tranches?status=ACTIVE&page=${page}&limit=${limit}`
    );
    const data = await response.json();

    allItems.push(...data.items);

    const totalPages = Math.ceil(data.count / limit);
    if (page >= totalPages) break;

    page++;
  }

  return allItems;
}

Python — Buscar todas as páginas

Python

import requests

def fetch_all_tranches():
    all_items = []
    page = 1
    limit = 50

    while True:
        response = requests.get(
            "https://api.liqi.com.br/public/tranches",
            params={"status": "ACTIVE", "page": page, "limit": limit},
        )
        data = response.json()

        all_items.extend(data["items"])

        total_pages = -(-data["count"] // limit)  # ceil division
        if page >= total_pages:
            break

        page += 1

    return all_items

Limites e validação

Regra	Descrição
`page` minimo	`1` — valores menores retornam erro 400
`limit` minimo	`1` — valores menores retornam erro 400
`limit` máximo	`100` — valores maiores são truncados para 100
Página além do total	Retorna `items: []` com `count` correto

Exemplo: página além do total

Bash

curl "https://api.liqi.com.br/public/tranches?page=999&limit=10"

JSON

{
  "items": [],
  "count": 47,
  "page": 999,
  "limit": 10
}

Boas práticas

Defina um limit adequado — Use limit=50 ou limit=100 para reduzir o número de chamadas, mas evite buscar mais dados do que você precisa
Não itere sem verificar count — Sempre calcule o total de páginas antes de iterar para evitar chamadas desnecessárias
Combine com filtros — Filtre os dados no servidor (via query params) em vez de buscar tudo e filtrar no cliente
Respeite os rate limits — Ao iterar por muitas páginas, adicione um pequeno delay entre chamadas para não exceder o limite

Próximos passos

Erros — Formato e códigos de erro
Rate Limits — Limites de requisição por API
Public API — Endpoints públicos com paginação