Exports

Base URL: https://api.orbioapi.com.br

Autenticação

Authorization: Bearer <API_KEY>

POST /v1/exports

Cria um export assíncrono (CSV ou HTML) em modo enqueue-only.

Notas sobre secondary_cnae_mode:

off: apenas CNAE principal.
fallback: modo econômico (2 fases) permitido em todos os planos.
full: permitido apenas no plano Scale+ e quando habilitado globalmente.

Headers

Idempotency-Key: <string> (obrigatório)

Body da requisição

Campos:

spec (object, obrigatório)
output (object, obrigatório)
- format: csv ou html
- include_explain: boolean
- fields: lista de campos
limit (int, opcional)

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
  }
}

Observações:

O POST /v1/exports não executa query de dados no request path.
preview_accounts no create é sempre [].

`GET /v1/exports/{export_id}`

Consulta um export.

Status possíveis:

queued
running
done
failed

Quando status = done, download_url é retornado.

json

{
  "export_id": "exp_123",
  "status": "done",
  "format": "csv",
  "snapshot": "2026-01",
  "snapshot_date": "2026-01-31",
  "row_count": 1200,
  "size_bytes": 456789,
  "expires_at": "2026-02-10T12:00:00Z",
  "download_url": "/v1/exports/exp_123/download"
}

`GET /v1/exports/{export_id}/download`

Retorna 303 See Other com Location para URL assinada.

GET /v1/exports

Lista exports do tenant.

Query params:

limit (1–200)
cursor (opcional)

Resposta:

json

{
  "exports": [
    {
      "export_id": "exp_123",
      "status": "done",
      "format": "csv",
      "snapshot": "2026-01",
      "snapshot_date": "2026-01-31",
      "row_count": 1200,
      "size_bytes": 456789,
      "expires_at": "2026-02-10T12:00:00Z",
      "download_url": "/v1/exports/exp_123/download"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMi0wNVQxMjozMDowMFoiLCJleHBvcnRfaWQiOiJleHBfMTIzIn0=",
  "has_more": false
}

Quando has_more = true, a API também retorna header Link com rel="next".

Erros

401/403: autenticação
404: export não encontrado
409: EXPORT_NOT_READY ou EXPORT_FAILED
410: export expirado
422: validação da requisição
429: rate limit

Veja exemplos em Erros e códigos.