Export assíncrono (CSV/HTML)

Objetivo: gerar um arquivo grande sem bloquear a requisição.

Passos

Crie o export com POST /v1/exports.
Aguarde o status ficar done em GET /v1/exports/{export_id}.
Baixe via GET /v1/exports/{export_id}/download (redirect 303).

Notas sobre secondary_cnae_mode:

fallback e off são permitidos em todos os planos.
full é permitido apenas no plano Scale+ e quando habilitado globalmente.

1) Criar export

http

POST https://api.orbioapi.com.br/v1/exports
Authorization: Bearer <API_KEY>
Idempotency-Key: <unique-key>
Content-Type: application/json

{
  "spec": {
    "kind": "account_query",
    "spec_version": "2.0",
    "entity": "company",
    "limit": 5000,
    "filters": {
      "industry": { "cnae_any_of": ["6201-5/00"], "cnae_exclude": [], "secondary_cnae_mode": "fallback", "text_hints": ["software B2B"] },
      "geo": { "uf_any_of": ["SP"], "municipality_ibge_any_of": [], "municipality_tom_any_of": [] },
      "company": { "registration_status_any_of": [2], "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": [{ "field": "score", "direction": "desc" }],
    "scoring": { "strategy": "balanced", "random_seed": null },
    "output": { "format": "csv", "include_explain": false, "fields": ["cnpj", "legal_name", "uf"] },
    "explain": { "assumptions": [], "warnings": [], "unmapped_constraints": [], "confidence": 0.74 }
  },
  "output": { "format": "csv", "include_explain": false, "fields": ["cnpj", "legal_name", "uf"] },
  "limit": 5000
}

Resposta (201):

json

Testar

{
  "request_id": "req_01HX...",
  "snapshot": "2026-01",
  "snapshot_date": "2026-01-31",
  "spec": {
    "kind": "account_query",
    "spec_version": "2.0",
    "entity": "company",
    "limit": 5000,
    "filters": {
      "industry": {
        "cnae_any_of": ["6201-5/00"],
        "cnae_exclude": [],
        "secondary_cnae_mode": "fallback",
        "text_hints": ["software"]
      },
      "geo": {
        "uf_any_of": ["SP"],
        "municipality_ibge_any_of": [],
        "municipality_tom_any_of": []
      },
      "company": {
        "registration_status_any_of": [2],
        "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": [{ "field": "score", "direction": "desc" }],
    "scoring": { "strategy": "balanced", "random_seed": null },
    "output": {
      "format": "csv",
      "include_explain": false,
      "fields": ["cnpj", "legal_name", "uf"]
    },
    "explain": {
      "assumptions": [],
      "warnings": [],
      "unmapped_constraints": [],
      "confidence": 0.74
    }
  },
  "preview_accounts": [],
  "export": {
    "export_id": "exp_123",
    "status": "queued",
    "format": "csv",
    "snapshot": "2026-01",
    "snapshot_date": "2026-01-31",
    "row_count": null,
    "size_bytes": null,
    "object_key": null,
    "expires_at": null,
    "download_url": null
  }
}

O create é enqueue-only: o arquivo é processado pelo worker depois do 201.

2) Polling

http

GET https://api.orbioapi.com.br/v1/exports/exp_123
Authorization: Bearer <API_KEY>

Quando status for done, o download_url estará disponível.

3) Download

http

GET https://api.orbioapi.com.br/v1/exports/exp_123/download
Authorization: Bearer <API_KEY>

A resposta é 303 See Other com Location apontando para a URL assinada.

Erros comuns

409 export_not_ready: export ainda em processamento.
409 export_failed: export falhou.
410 export_expired: o link expirou.

Veja exemplos em Erros e códigos.