Paginação por cursor

Todos os endpoints de listagem da API Topo Contábil utilizam paginação por cursor. Esse método e mais eficiente que paginação por offset, especialmente para grandes volumes de dados, pois não sofre com problemas de registros duplicados ou saltados quando dados são inseridos entre páginas.

Como funciona

Cada resposta de listagem inclui três campos de paginação:

Campo	Tipo	Descrição
`data`	array	Itens da página atual
`cursor`	string \| null	Token para a proxima página (null se não houver mais)
`hasMore`	boolean	Indica se existem mais páginas

Parametros de consulta

Parametro	Tipo	Padrão	Descrição
`limit`	integer	25	Itens por página (1-100)
`cursor`	string	-	Cursor da página anterior

Exemplo básico

Primeira páginabash

# Primeira página (25 itens)
curl -X GET "https://api.topocontabil.com.br/v1/reconciliations?limit=25" \
  -H "Authorization: Bearer SUA_CHAVE_API"

# Resposta inclui cursor:
# { "data": [...], "cursor": "eyJpZCI6IjEyMyJ9", "hasMore": true }

# Proxima página
curl -X GET "https://api.topocontabil.com.br/v1/reconciliations?limit=25&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer SUA_CHAVE_API"

# Última página
# { "data": [...], "cursor": null, "hasMore": false }

Iterar por todas as páginas

Para percorrer todos os resultados, repita as requisições até que hasMore seja false.

Iterar por todas as páginasbash

#!/bin/bash
CURSOR=""
PAGE=1

while true; do
  URL="https://api.topocontabil.com.br/v1/reconciliations?limit=100"
  if [ -n "$CURSOR" ]; then
    URL="$URL&cursor=$CURSOR"
  fi

  RESPONSE=$(curl -s -X GET "$URL" \
    -H "Authorization: Bearer SUA_CHAVE_API")

  echo "Página $PAGE:"
  echo "$RESPONSE" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f"  Itens: {len(data['data'])}")
print(f"  Mais: {data['hasMore']}")
"

  HAS_MORE=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['hasMore'])")
  CURSOR=$(echo "$RESPONSE" | python3 -c "import sys,json; c=json.load(sys.stdin)['cursor']; print(c if c else '')")

  if [ "$HAS_MORE" = "False" ]; then
    break
  fi

  PAGE=$((PAGE + 1))
done

Rate limiting

Ao iterar por muitas páginas, respeite os limites de taxa da API. Verifique os headers X-RateLimit-Remaining e X-RateLimit-Reset e aguarde quando necessário.

Cursor vs Offset

A API Topo Contábil usa paginação por cursor em vez de offset por três motivos principais:

Consistencia: novos registros inseridos entre requisições não causam duplicações ou itens saltados
Performance: cursores utilizam indices do banco de dados, enquanto offsets grandes exigem varredura sequencial
Escalabilidade: o tempo de resposta e constante independente da posição na lista

Cursores são opacos

O valor do cursor e uma string opaca -- não tente decodifica-lo ou construi-lo manualmente. Use apenas os valores retornados pela API.