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

Comece em 5 minutos

Objetivo: fazer a sua primeira busca com a Orbio API e entender a resposta.

Pré‑requisitos

  • Uma API key válida (crie em /app/api-keys).
  • curl instalado (ou Postman).

1) Faça a primeira busca

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": 20,
    "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": true,
        "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
    }
  }
}

2) Leia a resposta

json
{
  "request_id": "req_01HX...",
  "snapshot": "2026-01",
  "snapshot_date": "2026-01-31",
  "provenance": {
    "rfb_snapshot": "2026-01",
    "ibge_population_year": "not_available",
    "ceis_as_of_date": "not_available"
  },
  "accounts": [
    {
      "cnpj": "00000000000000",
      "legal_name": "SOFTWARE EXEMPLO LTDA",
      "uf": "SP"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

O que observar:

  • snapshot: base do mês usada na busca.
  • snapshot_date: data do snapshot (proveniencia).
  • provenance: metadados de origem (por fonte).
  • spec: filtros reprodutiveis gerados/normalizados (sempre presente; omitido no snippet acima).
  • next_cursor + has_more: paginação.

3) Se der erro

Erros seguem RFC 9457 (Problem Details) e incluem code canônico + request_id.

json
{
  "type": "https://orbioapi.com.br/problems/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Limite de requisições excedido.",
  "instance": "/v1/accounts/search",
  "code": "rate_limit_exceeded",
  "request_id": "req_01HX..."
}

Veja exemplos completos em Erros e códigos.

Próximos passos