Paginação

Os formatos de paginação usados nas listagens da API externa e como percorrer todas as páginas.

Todas as listagens da API externa são paginadas no servidor. Não existe endpoint que devolva a coleção inteira — percorra as páginas.

Parâmetros de consulta

Query string
pageintegeropcionalpadrão 1

Número da página, começando em 1.

pageSizeintegeropcionalpadrão 20

Quantidade de itens por página. Mínimo 1, máximo 100.

Exemplo
curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/items?page=2&pageSize=50" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

Formatos de resposta

A API usa dois formatos de envelope paginado, dependendo do endpoint.

Formato pagination

Usado nas listagens de lotes e de itens de lote.

200 OK
{
  "success": true,
  "data": {
    "items": [],
    "pagination": {
      "total": 137,
      "page": 2,
      "pageSize": 50,
      "totalPages": 3
    }
  }
}
CampoDescrição
totalTotal de registros que atendem ao filtro
pagePágina atual
pageSizeItens por página
totalPagesTotal de páginas

Formato com hasNext

Alguns endpoints acrescentam ajudantes de navegação ao envelope:

200 OK
{
  "success": true,
  "data": {
    "items": [],
    "total": 137,
    "page": 2,
    "pageSize": 50,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": true
  }
}

Listagem de lotes de notificações

O endpoint Listar lotes devolve a coleção sob a chave lotes (não items), acompanhada de pagination com limit no lugar de pageSize. Consulte a página do endpoint para o formato exato.

Percorrendo todas as páginas

Node.js
async function listarTodosItens(batchId, apiKey) {
  const base = 'https://external-api.arbitralis.com.br/api/external/v1';
  const itens = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `${base}/extrajudicial/negotiations/batches/${batchId}/items?page=${page}&pageSize=100`,
      { headers: { 'X-API-KEY': apiKey } }
    );

    const { data } = await response.json();

    itens.push(...data.items);
    totalPages = data.pagination.totalPages;
    page += 1;
  } while (page <= totalPages);

  return itens;
}
Python
import requests

BASE = "https://external-api.arbitralis.com.br/api/external/v1"


def listar_todos_itens(batch_id: str, api_key: str) -> list:
    itens = []
    page = 1
    total_pages = 1

    while page <= total_pages:
        response = requests.get(
            f"{BASE}/extrajudicial/negotiations/batches/{batch_id}/items",
            headers={"X-API-KEY": api_key},
            params={"page": page, "pageSize": 100},
        )
        data = response.json()["data"]

        itens.extend(data["items"])
        total_pages = data["pagination"]["totalPages"]
        page += 1

    return itens

Respeite o limite de requisições

Percorrer muitas páginas em sequência consome o seu teto de 60 requisições por minuto. Use pageSize=100 para reduzir o número de chamadas e adicione uma pausa entre páginas em coleções grandes. Ver Limite de requisições.

Ordenação e filtros

Os filtros disponíveis variam por endpoint e estão documentados em cada página. O padrão mais comum:

ParâmetroOnde se aplica
statusListagem de lotes e de itens
sortBy / sortOrderListagem de lotes de notificações
startDate / endDateListagem de lotes de notificações

Ao paginar com filtros, mantenha os mesmos parâmetros em todas as páginas — trocar o filtro no meio da varredura produz resultados inconsistentes.