Paginação

Todas as listagens do Sentinex usam cursor-based pagination. Esse modelo é estável sob escritas concorrentes (você não pula nem repete itens enquanto novos chegam) e escalável (não degrada em offsets altos como ?page=10000).

Schema de resposta

{
  "success": true,
  "data": [
    { "id": "a1b2…", "external_id": "ACME-001", "created_at": "2026-05-18T14:32:11Z" },
    { "id": "c3d4…", "external_id": "ACME-002", "created_at": "2026-05-18T14:33:05Z" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjlhYjJjLi4uIiwidHMiOjE3NDc1ODQwMDB9",
    "has_more": true,
    "page_size": 20
  }
}

Campo	Significado
next_cursor	Opaque string para próxima página. null quando esgotado.
has_more	true se há mais (equivalente a next_cursor !== null)
page_size	Quantidade efetiva retornada (≤ limit solicitado)

Query params

GET /vasp/customers?cursor=eyJpZCI6IjlhYjJjLi4uIn0=&limit=50

Param	Default	Máximo	Notas
cursor	null (primeira página)	n/a	Use exatamente como veio em next_cursor
limit	20	100	Pedidos acima de 100 são truncados
order	desc	n/a	asc ou desc por created_at

Loop até esgotar

Node.js

async function* paginate(endpoint, params = {}) {
  let cursor = null;
  do {
    const res = await api.get(endpoint, {
      params: { ...params, cursor, limit: 100 },
    });
    for (const item of res.data) yield item;
    cursor = res.pagination.next_cursor;
  } while (cursor);
}

// Uso:
for await (const customer of paginate('/vasp/customers', { kyc_tier: 'STANDARD' })) {
  console.log(customer.external_id);
}

Go

func IterCustomers(ctx context.Context, client *sentinex.Client, fn func(c Customer) error) error {
    var cursor string
    for {
        res, err := client.Customers.List(ctx, sentinex.ListOpts{
            Cursor: cursor,
            Limit:  100,
        })
        if err != nil { return err }
        for _, c := range res.Data {
            if err := fn(c); err != nil { return err }
        }
        if !res.Pagination.HasMore { return nil }
        cursor = res.Pagination.NextCursor
    }
}

Python

def paginate(endpoint: str, **params):
    cursor = None
    while True:
        res = api.get(endpoint, params={**params, "cursor": cursor, "limit": 100})
        for item in res["data"]:
            yield item
        cursor = res["pagination"]["next_cursor"]
        if not cursor:
            return

for customer in paginate("/vasp/customers", kyc_tier="STANDARD"):
    print(customer["external_id"])

Filtros combinados com paginação

O cursor codifica os filtros usados: você não pode trocar filtros entre páginas.

# ✅ OK
GET /alerts?status=open&cursor=AAA
GET /alerts?status=open&cursor=BBB    # mesma combinação de filtros

# ❌ Erro: vai retornar 400 INVALID_CURSOR
GET /alerts?status=open&cursor=AAA
GET /alerts?status=closed&cursor=AAA  # cursor não vale para status diferente

Se mudar filtros, recomece do cursor null.

Quando usar offset (excepcional)

Apenas listagens administrativas com ?offset=…&page_size=… são suportadas em endpoints /admin/* para uso em dashboards humanos. Nunca use em integrações automatizadas, porque a janela pode mover sob escritas concorrentes.

Cuidado

Decisão D-CRAU-API-PAG-001: cursor para feeds/timelines, offset apenas em telas admin com volume baixo (< 10k registros).

Limites operacionais

• Cursor expira em 24h (INVALID_CURSOR se usar depois)
• limit > 100 é silenciosamente truncado para 100
• Listas que potencialmente retornam > 1M registros (transactions) requerem filtro de janela temporal obrigatório (from, to)