Paginacao por cursor

Todos os endpoints de listagem da API Topo Contabil utilizam paginacao por cursor. Esse metodo e mais eficiente que paginacao por offset, especialmente para grandes volumes de dados, pois nao sofre com problemas de registros duplicados ou saltados quando dados sao inseridos entre paginas.

Como funciona

Cada resposta de listagem inclui tres campos de paginacao:

Campo	Tipo	Descricao
`data`	array	Itens da pagina atual
`cursor`	string \| null	Token para a proxima pagina (null se nao houver mais)
`hasMore`	boolean	Indica se existem mais paginas

Parametros de consulta

Parametro	Tipo	Padrao	Descricao
`limit`	integer	25	Itens por pagina (1-100)
`cursor`	string	-	Cursor da pagina anterior

Exemplo basico

Primeira paginabash

# Primeira pagina (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 pagina
curl -X GET "https://api.topocontabil.com.br/v1/reconciliations?limit=25&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer SUA_CHAVE_API"

# Ultima pagina
# { "data": [...], "cursor": null, "hasMore": false }

Iterar por todas as paginas

Para percorrer todos os resultados, repita as requisicoes ate que hasMore seja false.

Iterar por todas as paginasbash

#!/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 "Pagina $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 paginas, respeite os limites de taxa da API. Verifique os headers X-RateLimit-Remaining e X-RateLimit-Reset e aguarde quando necessario.

Cursor vs Offset

A API Topo Contabil usa paginacao por cursor em vez de offset por tres motivos principais:

Consistencia: novos registros inseridos entre requisicoes nao causam duplicacoes 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 posicao na lista

Cursores sao opacos

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