API CapiBLU — v1

1. Introdução

A API do CapiBLU expõe o que a plataforma alcança: cadastro de empresas da Receita Federal, quadro de sócios com CPF resolvido, possíveis decisores com cargo, vínculos empregatícios da RAIS, telefones priorizados por atualidade e parentes.

O que dá para fazer

• Buscar empresas por UF, município, CNAE, porte e capital social
• Trazer sócios com CPF resolvido e decisores com cargo e nível de decisão
• Consultar quem trabalha (ou trabalhou) numa empresa, pela RAIS
• Descobrir onde uma pessoa trabalha, a partir do CPF
• Montar contatos prontos para abordagem, com telefone do mais atual para o mais antigo
• Puxar o JSON bruto de cada fonte quando precisar de um campo que a tela não mostra
• Acompanhar o próprio consumo e o limite diário

Pré-requisito: um token de API, gerado por um administrador no painel administrativo.

2. Autenticação

Toda requisição leva o token no header:

Authorization: Bearer capi_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxx

Como obter

Um administrador cria o token no painel (aba Painel administrativo → Tokens de API). O valor em claro aparece uma única vez, na criação — o CapiBLU guarda apenas o hash. Se perder, revogue e gere outro.

Escopos

Token leitura que chamar rota paga recebe 403 com explicação. Serve para entregar acesso a um sistema de leitura sem risco de ele gerar custo.

3. Conceitos gerais

3.1 Datas

ISO 8601 em UTC: 2026-08-19T17:00:00Z. Datas que vêm de base pública (RAIS, Receita) podem chegar no formato original dd/mm/aaaa — nesse caso o campo tem sufixo _br.

3.2 Filtros

GET /api/v1/empresas?uf=MG&municipio=GOVERNADOR%20VALADARES&porte=05

3.3 Paginação

3.4 Estrutura das respostas

Todo retorno bem-sucedido usa o mesmo envelope:

{
  "data": [ ... ],
  "meta": { "total": 100, "page": 1, "limit": 20, "fonte": "Receita Federal" }
}

E todo erro tem corpo previsível:

{ "error": { "code": "cnpj_invalido", "message": "CNPJ deve ter 14 dígitos." } }

3.5 Custo por chamada

Rotas marcadas gasta consulta consomem o limite diário do usuário dono do token — o mesmo contador da plataforma. Rotas base local não consomem nada. Veja o saldo em GET /conta.

4.1 Conta

{
  "data": {
    "usuario": { "id": 1, "nome": "Rebeca", "email": "rebeca@…", "role": "admin" },
    "token": { "id": 3, "nome": "Integração CRM", "escopo": "consulta" },
    "limites": { "consultas_por_dia": 100, "usadas_hoje": 12, "restantes_hoje": 88, "ilimitado": false }
  },
  "meta": { "gerado_em": "2026-08-19T20:14:03Z" }
}

4.2 Empresas

{ "data": [ { "nome": "CELIO COUTINHO DA CUNHA",
              "qualificacao": "Sócio-Administrador",
              "cpf": "03702149600", "data_entrada": "2021-06-10" } ],
  "meta": { "total": 1, "fonte": "Receita Federal (QSA)" } }

4.3 Pessoas

4.4 Telefones

4.5 JSON bruto das fontes

Cada fonte devolve muito mais campo do que a tela mostra. Nestas rotas o meta.bruto vem true: o data é o JSON da fonte, sem tradução nossa. Use quando precisar de um campo que a API tratada não expõe.

Todas gastam consulta e são JSON bruto.

4.6 Visões compostas — tudo numa chamada

GET /empresas/{cnpj}/completo?incluir=cadastro,socios,decisores,funcionarios,conexoes,assertiva,linkedin

{
  "data": { "cadastro": {...}, "socios": [...], "decisores": {...} },
  "meta": {
    "blocos": ["cadastro", "socios", "decisores"],
    "falhas": { "funcionarios": "A base RAIS respondeu 504." }
  }
}

GET /pessoas/{cpf}/completo?incluir=cadastro,mk,assertiva,vinculos,parentes,serasa

4.7 Lote

curl -X POST "$BASE/enriquecimento" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"cnpjs":["06990590000123"],
       "campos":["rfb_razao","rfb_municipio","as_empresa_tel"]}'

{ "meta": { "testadas": 3, "com_decisor": 1, "taxa": 33.3, "consultas_gastas": 6 } }

4.8 Apoio, consumo e dossiê

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/dossie/cnpj/06990590000123?insight=true" -o dossie.pdf

5. Administração de tokens

Estas rotas usam sessão de administrador, não token de API — é o que a tela do painel consome.

O token herda o limite diário do usuário a que pertence. Para dar mais folga a uma integração, ajuste o limite desse usuário no painel.

6. Objetos e relacionamentos

7. Casos de uso comuns

Enriquecer um CRM com quem decide

# 1. acha as empresas do perfil
curl -H "Authorization: Bearer $CAPIBLU_TOKEN" \
  "$BASE/empresas?uf=MG&porte=05&capital_min=1000000&limit=50"

# 2. para cada CNPJ, pega contatos com telefone
curl -H "Authorization: Bearer $CAPIBLU_TOKEN" \
  "$BASE/empresas/06990590000123/contatos?max_decisores=2&tipo_telefone=celular"

Descobrir onde um lead trabalha, a partir do CPF

curl -H "Authorization: Bearer $CAPIBLU_TOKEN" \
  "$BASE/pessoas/03702149600/vinculos"

Validar de quem é um número que ligou

curl -H "Authorization: Bearer $CAPIBLU_TOKEN" \
  "$BASE/telefones/33997332652"

Controlar custo antes de rodar em lote

curl -H "Authorization: Bearer $CAPIBLU_TOKEN" "$BASE/conta"
# → data.limites.restantes_hoje diz quantas consultas ainda cabem

curl -X POST "$BASE/prospeccao/cobertura" -H "Authorization: Bearer $CAPIBLU_TOKEN" \
  -H 'Content-Type: application/json' -d '{"cnpjs":["…","…"]}'
# → meta.taxa diz se vale rodar a lista inteira

8. Boas práticas

1. Um token por integração, com nome que diga quem usa. Revogar fica cirúrgico.
2. Escopo leitura por padrão. Só suba para consulta o que precisa gastar.
3. Trate o 429. O limite é diário e por usuário: espere o dia virar ou peça mais folga a um admin.
4. Cacheie do seu lado. CNPJ e RAIS mudam devagar; consultar o mesmo documento duas vezes no mesmo dia é dinheiro fora.
5. Não trate ausência como erro. 200 com data: [] e um meta.aviso é resposta legítima.
6. Peça só os blocos que usa em /completo — cada bloco pago cobra separado.