Paginação com cursor

Objetivo: percorrer resultados usando next_cursor.

Como funciona

A primeira resposta retorna next_cursor e has_more.
next_cursor é opaco: trate como string.

POST /v1/accounts/search (search interativo)

Na primeira página, envie spec (e pode enviar limit e output).
Na próxima página, envie cursor + o mesmo spec usado para gerar aquele cursor. Recomenda-se reusar o spec retornado na resposta anterior (já vem normalizado).
Com cursor, não envie overrides (limit, output).
Se o cursor não corresponder ao spec, a API retorna 422 cursor_mismatch.

GET endpoints (ex.: list exports)

Em endpoints GET paginados, envie cursor e, se necessário, limit.
Regra prática: não aumente limit ao paginar (mantenha igual ou menor).

Exemplo (1ª página)

http

POST https://api.orbioapi.com.br/v1/accounts/search
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "spec": {
    "kind": "account_query",
    "spec_version": "2.0",
    "entity": "company",
    "limit": 50,
    "filters": {
      "industry": {
        "cnae_any_of": ["6201-5/00"],
        "cnae_exclude": [],
        "secondary_cnae_mode": "off",
        "text_hints": []
      },
      "geo": {
        "uf_any_of": ["SP"],
        "municipality_ibge_any_of": [],
        "municipality_tom_any_of": []
      },
      "company": {
        "registration_status_any_of": [],
        "company_size_code_any_of": [],
        "headquarters_only": true,
        "simples_opt_in": null,
        "mei_opt_in": null,
        "started_after": null,
        "started_before": null
      },
      "contact": {
        "require_email": false,
        "require_phone": false,
        "require_any_contact": false
      }
    },
    "sort": [],
    "scoring": { "strategy": "balanced", "random_seed": null },
    "output": {
      "format": "json",
      "include_explain": false,
      "fields": ["cnpj", "legal_name", "uf"]
    },
    "explain": {
      "assumptions": [],
      "warnings": [],
      "unmapped_constraints": [],
      "confidence": 0.9
    }
  }
}

Resposta:

json

{
  "accounts": [
    {
      "cnpj": "00000000000000",
      "legal_name": "SOFTWARE EXEMPLO LTDA",
      "uf": "SP"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ==",
  "has_more": true
}

Exemplo (próxima página)

http

POST https://api.orbioapi.com.br/v1/accounts/search
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "cursor": "eyJvZmZzZXQiOjUwfQ==",
  "spec": {
    "...": "use o mesmo spec que gerou o cursor (ideal: o spec retornado na resposta anterior)"
  }
}

Verificação

has_more = false indica fim.
next_cursor = null quando não há próxima página.

Erros comuns

422: cursor inválido.
422 cursor_mismatch: cursor usado com spec diferente.

Veja exemplos em Erros e códigos.