Guia de integração da API
Como o seu sistema consulta dados de CPF, CNPJ, processos, sanções, fundos e outras fontes pelo Consultas Hub, e como interpretar a resposta.
Visão geral
O Consultas Hub reúne dezenas de fontes brasileiras de dados atrás de uma API REST única. O seu sistema faz uma chamada e o hub cuida do resto:
- escolhe a fonte;
- tenta a próxima fonte se a primeira falhar;
- valida o documento antes de gastar;
- usa o cache;
- apura e registra o custo de cada chamada;
- registra a chamada para auditoria.
A resposta vem sempre num formato padronizado, o mesmo para qualquer fonte que tenha respondido.
| Item | Valor |
|---|---|
| URL base | https://api.jabuticaba.cloud |
| Versão | /api/v1 |
| Formato | JSON UTF-8, com campos em camelCase |
| Autenticação | OAuth 2.0 client credentials (token Bearer) |
| Contrato OpenAPI | /swagger/consumo/swagger.json · interface interativa em /swagger |
Início rápido
- Receba a credencial. O administrador do hub cadastra o seu sistema e entrega um
client_ide umclient_secret, junto com as consultas liberadas. O segredo é mostrado uma única vez: guarde-o no cofre de segredos do seu servidor. - Obtenha um token.
curl -s -X POST https://api.jabuticaba.cloud/connect/token \ -d grant_type=client_credentials \ -d client_id=SEU_CLIENT_ID \ -d client_secret="$HUB_CLIENT_SECRET" \ -d scope=ConsultasHub - Chame uma consulta.
curl -s -X POST https://api.jabuticaba.cloud/api/v1/consultas/cnpj.cadastro \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"parametros": {"cnpj": "53.798.634/0001-06"}}'
Autenticação
Toda rota /api/v1 exige um token de acesso. O token é obtido no endpoint OAuth com o fluxo client_credentials. É uma integração entre servidores: não existe login de usuário.
POST /connect/token
| Campo (form-urlencoded) | Valor |
|---|---|
grant_type | client_credentials |
client_id | Identificador do seu sistema, entregue pelo administrador |
client_secret | Segredo do seu sistema |
scope | ConsultasHub |
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}
Envie o token em todas as chamadas no cabeçalho Authorization: Bearer <access_token>.
O token vale 1 hora. Reaproveite-o até perto de expirar, em vez de pedir um novo a cada chamada: o endpoint de token tem limite próprio por IP (veja Limites).
| Situação | Resposta |
|---|---|
Segredo ou client_id inválido | 401 {"error":"invalid_client"} |
| Chamada à API sem token, ou com token expirado | 401 sem corpo |
| Consulta não liberada para o seu sistema | 403 ConsultasHub:SemPermissao |
| Rota administrativa | 403. Credenciais de sistema não acessam /api/v1/admin |
Endpoints
| Método | Rota | Para quê |
|---|---|---|
| GET | /api/v1/consultas | Catálogo: as consultas, com os parâmetros de entrada, o schema de retorno, o custo e o cache de cada uma |
| GET | /api/v1/consultas/{consultaId} | Detalhe de uma consulta |
| POST | /api/v1/consultas/{consultaId} | Executa uma consulta |
| POST | /api/v1/consultas/{consultaId}/lote | Executa a mesma consulta para até 50 entradas |
| GET | /api/v1/pacotes | Catálogo de pacotes (dossiês que combinam várias consultas) |
| GET | /api/v1/pacotes/{pacoteId} | Detalhe de um pacote |
| POST | /api/v1/pacotes/{pacoteId} | Executa o pacote e devolve o dossiê consolidado |
| POST | /api/v1/historico/consultar | O que o seu sistema já consultou sobre um documento |
| POST | /api/v1/historico/comparar | O que mudou no dado de um documento entre duas datas |
| POST | /api/v1/retroativo/vigentes | O último resultado salvo de cada consulta de um documento, sem consultar a fonte de novo |
| POST | /api/v1/retroativo/historico | Todas as versões salvas de uma consulta de um documento |
| POST | /api/v1/transportadores/ficha | Ficha de transportadora de cargas pelo CNPJ, de matriz ou de filial: cadastro, RNTRC, aptidão, sanções, dívida ativa e ambiental, um bloco por verificação. Ver Transportadoras |
| POST | /api/v1/teia | Teia de vínculos societários de um CPF ou CNPJ: os sócios e as outras empresas deles. Só entram as consultas que a sua credencial alcança, conferidas uma a uma; o que ficar de fora vem em avisos |
<tipo>.<assunto>, por exemplo cnpj.cadastro, cpf.processos ou cnpj.sancoes_br. O catálogo é gerado a partir das fontes ativas. Quando uma fonte nova entra no hub, a consulta aparece nele sem mudança de contrato.Executar uma consulta
POST /api/v1/consultas/{consultaId}
{
"parametros": { "cnpj": "53798634000106" },
"ignorarCache": false,
"provedor": null
}
| Campo | Tipo | Descrição |
|---|---|---|
parametros | objeto de texto | Obrigatório. As chaves são as declaradas pela consulta no catálogo (parametros[].nome). Chaves não declaradas são descartadas. O documento pode vir com ou sem pontuação. |
confirmarCusto | booleano | Aceito por compatibilidade e ignorado: com token válido, as fontes pagas entram na cascata sem confirmação. O custo de cada chamada fica registrado. |
ignorarCache | booleano | Vai à fonte mesmo havendo cache válido. Numa consulta paga, cobra de novo. Em cnpj.cadastro, cnpj.simples_nacional e cnpj.inscricao_estadual pede à fonte o dado em tempo real (consulta instantânea), com teto diário de 300 por aplicação; acima dele a chamada segue como consulta comum. |
provedor | texto | Opcional. Força uma fonte específica, pelo id em fontes[].provedorId no catálogo, em vez de seguir a ordem de fontes. |
Um documento com dígito verificador inválido é recusado antes de qualquer chamada externa, com 400 ParametroInvalido, e não custa nada. O CNPJ alfanumérico (IN RFB 2.229/2024) é aceito.
Resposta (envelope)
Toda consulta bem-sucedida devolve dados, no schema canônico da consulta, e meta, com a procedência. Exemplo real de cnpj.cadastro, reduzido:
{
"dados": {
"cnpj": "53798634000106",
"razaoSocial": "JABUTICABA ADMINISTRADORA DE IMOVEIS LTDA",
"situacao": "ATIVA",
"matriz": true,
"dataAbertura": "2023-11-23T03:00:00Z",
"naturezaJuridica": "206-2 - Sociedade Empresária Limitada",
"capitalSocial": 5085496.00,
"cnaePrincipal": { "codigo": "68.10-2-01", "descricao": "Compra e venda de imóveis próprios" },
"endereco": { "municipio": "RIBEIRAO PRETO", "uf": "SP", "cep": "14027250", "...": "..." },
"socios": [ { "nome": "MARCELO FELICIO ROMANO MACHADO", "qualificacao": "Sócio-Administrador", "documento": null } ]
},
"meta": {
"consulta": "cnpj.cadastro",
"schema": "cnpj_cadastral@v1",
"provedor": "receitaws",
"origem": "https://receitaws.com.br/v1/cnpj/53798634000106/days/30",
"dataReferencia": "2026-09-15T23:59:59Z",
"obtidoEm": "2026-09-23T08:15:09.4530195Z",
"cache": false,
"custo": { "creditos": 0, "modelo": "Assinatura" },
"latenciaMs": 530,
"correlationId": "3a23df820ccbe490a2fef29cbf63fd41",
"tentativas": [ { "provedor": "receitaws", "resultado": "Ok", "httpStatus": 200, "latenciaMs": 530, "mensagem": null } ]
}
}
Campo de meta | Significado |
|---|---|
schema | Contrato versionado de dados. Uma mudança incompatível gera nova versão (@v2) e não quebra quem usa a @v1. |
provedor / origem | A fonte que respondeu e a URL consultada, sem credenciais. |
dataReferencia | Quando a fonte atualizou o dado. Vem null quando a fonte não informa. |
obtidoEm | Quando o hub buscou o dado. Numa resposta de cache, é a data da coleta original. |
cache | true quando a resposta veio do cache, sem tocar a fonte e sem custo. |
parcial | true quando a fonte respondeu mas parte do que a consulta confere não foi conferida nesta chamada (hoje, sanções sem o cadastro do RJ). O campo cobertura em dados diz o que faltou. Resposta parcial não fica em cache: repetir a chamada tenta de novo. |
resultadoSalvo / salvoEm | resultadoSalvo: true quando nenhuma fonte respondeu nesta chamada e dados é o último resultado que o hub tinha guardado para a mesma consulta com os mesmos parâmetros. salvoEm é a data em que uma consulta ao vivo confirmou esse resultado pela última vez; vem null nas respostas normais. Não é verificação de agora: confira a idade antes de decidir. tentativas traz as falhas reais desta chamada, cache vem false e o custo é zero. |
custo | Créditos efetivamente debitados nesta chamada e o modelo de cobrança da fonte. |
correlationId | Identificador da chamada. Informe-o ao suporte para rastrear um caso. |
tentativas | As fontes percorridas, em ordem, com o resultado de cada uma: Ok, NaoEncontrado, ErroLogico, ErroRede, ErroAutenticacao, LimiteExcedido, CredencialAusente (a fonte não está configurada neste ambiente), ParametroAusente (a fonte exige um parâmetro que não veio), ProvedorExcluido ou FilaCheia (a vez na fila da fonte não chegou a tempo e ela não foi consultada; a cascata seguiu para a próxima). |
null é informação. Um campo nulo em dados quer dizer que a fonte que respondeu não cobre aquele campo, ou que ele estava vazio na origem. fontes[].camposCobertos, no catálogo, diz de antemão o que cada fonte preenche. dados: null com 200 quer dizer "consultado e não encontrado".Lote
POST /api/v1/consultas/{consultaId}/lote
Executa a mesma consulta para 1 a 50 entradas. Cada item tem o mesmo formato do corpo de uma execução simples. A resposta é uma lista na mesma ordem. Cada posição traz o envelope, quando deu certo, ou o código de erro, e a falha de um item não derruba os outros.
// pedido
{ "itens": [
{ "parametros": { "cnpj": "53798634000106" } },
{ "parametros": { "cnpj": "00000000000191" } }
] }
// resposta 200
[
{ "indice": 0, "envelope": { "dados": { ... }, "meta": { ... } }, "erro": null },
{ "indice": 1, "envelope": null, "erro": "ConsultasHub:SemPermissao" }
]
Pacotes (dossiê)
Um pacote executa várias consultas sobre o mesmo documento e devolve um dossiê consolidado, por exemplo cadastro, sanções, processos e mídia. Liste os pacotes em GET /api/v1/pacotes; filtre com ?documento=cpf ou ?documento=cnpj, que filtra pelo tipo de documento e não recebe número.
POST /api/v1/pacotes/{pacoteId}
{
"documento": "53798634000106",
"nome": null,
"dataNascimento": null,
"ignorarCache": false,
"itens": null,
"semTeia": false
}
| Campo | Descrição |
|---|---|
documento | CPF ou CNPJ, conforme o tipo do pacote. |
confirmarCusto / tetoCreditos | Aceitos por compatibilidade e ignorados: a execução não exige confirmação nem teto. |
nome / dataNascimento | Opcionais. Melhoram as buscas feitas por nome (processos, mídia) e o casamento de pessoa física. |
semTeia | Opcional. true não monta a teia societária nos pacotes que a incluem (usado em lote, para não repetir a mesma teia). |
itens | Opcional. Executa só as chaves de item indicadas, em vez do pacote inteiro. |
A resposta traz:
dados, por bloco;itens[], com o desfecho de cada verificação:Ok,NaoEncontrado,NaoConclusivo,NaoExecutadoouNaoCoberto, junto com o motivo, a fonte e o custo;meta, com o custo total, o resumo e se o dossiê saiucompleto.
Histórico
Para não colocar o documento na URL, o histórico usa POST com o documento no corpo. Seu sistema vê apenas o que ele próprio consultou.
POST /api/v1/historico/consultar
{ "documento": "53798634000106" }
POST /api/v1/historico/comparar
{ "documento": "53798634000106", "de": "2026-09-01T00:00:00Z", "ate": "2026-09-23T00:00:00Z" }
Catálogo de consultas
O catálogo completo e atual está em GET /api/v1/consultas. Para cada consulta, ele traz:
parametros[], com nome, tipo, obrigatoriedade e exemplo;- o
schemade retorno; fontes[], com a ordem, o custo, os campos cobertos e o cache;custoMinimoCreditoseexigeConfirmacaoDeCusto. Este último é só informativo: indica que toda fonte disponível da consulta cobra crédito. Não há confirmação a enviar.
Seu sistema só executa as consultas liberadas para a credencial dele.
Para ver o catálogo aqui, cole um token de acesso válido. O token fica só na memória desta aba: não é gravado nem enviado a nenhum outro lugar além deste hub.
Amostra de 28 consultas medidas em 23/09/2026
Instantâneo de 28 consultas testadas com dados reais naquela data. O catálogo tem mais (85 em 07/10/2026): a lista completa e atual vem do endpoint acima.
| Consulta | Descrição | Parâmetros (* obrigatório) | Schema | Tempo medido |
|---|---|---|---|---|
cnpj.ambiental | Embargos ambientais do IBAMA | cnpj* | listas_restritivas@v1 | 50.4 s |
cnpj.bens | Bens registrados em nome da empresa | cnpj* | bens_localizados@v1 | 1.2 min* |
cnpj.cadastro | Dados cadastrais de CNPJ | cnpj* dias | cnpj_cadastral@v1 | 2.0 s |
cnpj.criminal | Processos criminais da parte | documento* nome* | processos_judiciais@v1 | 1.4 s |
cnpj.divida_ativa | Divida ativa da Uniao | cnpj* | divida_ativa@v1 | 1.3 s |
cnpj.documentos_fundo | Documentos do fundo no FNET (informes, fatos relevantes, assembleias) | cnpj* limite | resultado_da_fonte@v1 | 1.6 s |
cnpj.fundo | Ficha de fundo de investimento (cadastro CVM) | cnpj* | fundo_investimento@v1 | 0.6 s |
cnpj.fundos_geridos | Fundos por gestora ou administradora (cadastro CVM) | cnpj* | resultado_da_fonte@v1 | 1.4 s |
cnpj.processos | Processos judiciais de pessoa juridica | cnpj* nome* | processos_judiciais@v1 | 7.8 s |
cnpj.registro_bacen | Autorizacao do Banco Central (instituicao em funcionamento) | cnpj* | registro_bacen@v1 | 0.5 s |
cnpj.registro_cvm | Registro na CVM: corretora, distribuidora ou fundo | cnpj* | registro_cvm@v1 | 5.1 s |
cnpj.regulatorio | Sancoes de reguladores do mercado de capitais | cnpj* nome* | listas_restritivas@v1 | 10.1 s |
cnpj.sancoes_br | Sancoes administrativas (CEIS, CNEP, leniencia) | cnpj* | listas_restritivas@v1 | 7.8 s |
cnpj.sancoes_internacionais | Sancoes internacionais | cnpj* nome* | listas_restritivas@v1 | 2.6 min* |
cnpj.simples_nacional | Opcao pelo Simples Nacional e MEI | cnpj* | situacao_no_simples@v1 | 1.2 s |
cnpj.trabalho_escravo | Cadastro de empregadores (lista suja) | cnpj* | listas_restritivas@v1 | 1.4 s |
cpf.ambiental | Embargos ambientais do IBAMA | cpf* | listas_restritivas@v1 | 0.8 s |
cpf.bens | Bens registrados em nome da pessoa | cpf* | bens_localizados@v1 | 0.6 s |
cpf.cadastro | Cadastro de pessoa fisica (CPF Hub) | cpf* data_nascimento | cpf_cadastral@v1 | 1.3 s |
cpf.criminal | Processos criminais da parte | documento* nome* | processos_judiciais@v1 | 0.8 s |
cpf.divida_ativa | Divida ativa da Uniao | cpf* nome* | divida_ativa@v1 | 1.0 s |
cpf.pep | Pessoa exposta politicamente (CGU) | cpf* | listas_restritivas@v1 | 0.8 s |
cpf.processos | Processos judiciais de pessoa fisica | cpf* nome* | processos_judiciais@v1 | 3.0 s |
cpf.regulatorio | Sancoes de reguladores do sistema financeiro | cpf* nome | listas_restritivas@v1 | 0.8 s |
cpf.sancoes_br | Sancoes administrativas (CEIS, CNEP, leniencia) | cpf* | listas_restritivas@v1 | 1.9 s |
cpf.sancoes_internacionais | Sancoes internacionais | cpf* nome* | listas_restritivas@v1 | 0.6 s |
cpf.servidor | Vinculo com o servico publico federal | cpf* | listas_restritivas@v1 | 1.4 min* |
cpf.trabalho_escravo | Cadastro de empregadores (lista suja) | cpf* | listas_restritivas@v1 | 0.6 s |
O tempo é o medido em 23/09/2026. Todas têm fonte sem custo (pública ou por assinatura); * primeira carga da lista, as chamadas seguintes respondem do cache. Quatro delas têm também uma fonte paga no fim da cascata, que só entra quando as gratuitas falham: cnpj.cadastro (CNPJá, 1 crédito), cnpj.fundo (Mais Retorno, 1), cpf.cadastro (cpfcnpj e SintegraWS, 1) e cpf.sancoes_internacionais (Didit, 1). Consultas em que toda fonte cobra: cnpj.estabelecimentos (1 crédito) e empresa.pesquisa (1). A cnpj.inscricao_estadual tenta primeiro a ReceitaWS, sem custo, e cai nas fontes pagas (2 créditos) quando ela falha ou não traz inscrição. Em cpf.participacoes, informe cpf e nome (os dois obrigatórios): a base da Receita publica o CPF mascarado, e o nome é o que separa a pessoa dos homônimos de máscara. As fontes pagas dessa consulta (SintegraWS e CNPJá, 1 crédito) entram sozinhas depois da base da Receita.
cpf.politico,cpf.participacoes,cnpj.rntrc, as consultas de dívida ativa e as de listas públicas leem bases que o hub ingere (TSE, sócios da Receita, ANTT, PGFN, IBAMA, TCU...). Enquanto a carga não termina, a resposta é502NenhumProvedorRespondeu: o hub não afirma ausência sem ter a base. Emcpf.participacoes, a CNPJá filtra pelo CPF mascarado e devolve outras pessoas; o hub só mantém o registro cujo nome confere com o informado.cpf.midia_adversaecnpj.midia_adversausam o GDELT, que aplica limite próprio de chamadas. Quando ele recusa, o hub repete uma vez e depois responde502. Tente de novo mais tarde.
Listas públicas federais
Estas consultas conferem o documento, de uma vez, em cadastros e listas de órgãos federais que o hub carrega toda semana a partir dos dados abertos. Todas são gratuitas, casam por documento (não por nome) e devolvem o schema registros_publicos@v1.
| Consulta | Parâmetro | Fontes conferidas |
|---|---|---|
cnpj.regulatorio_setorial | cnpj* | ANEEL (autos de infração, termos de intimação e notificação, penas de editais), ANS (penalidades a operadoras), MTE (empresas com amianto e benzeno) |
cpf.regulatorio_setorial | cpf* | ANEEL: autos, intimações e penas de editais lavrados contra pessoa física |
cnpj.ambiental_termos / cpf.ambiental_termos | cnpj* / cpf* | IBAMA: termos de destruição/inutilização e de suspensão (os embargos ficam em *.ambiental) |
cnpj.registros_setoriais | cnpj* | SUSEP (empresas reguladas), CVM (companhias abertas), ANVISA (autorização de funcionamento), ANTT (transporte interestadual de passageiros e operadores multimodais), MDS (CEBAS e CNEAS) |
cnpj.otm | cnpj* | ANTT: operadores de transporte multimodal habilitados, com certificado e vigência |
cnpj.direitos_minerarios / cpf.direitos_minerarios | cnpj* / cpf* | ANM: titularidade de processos no Cadastro Mineiro (requerimentos, alvarás, lavras, licenciamentos, PLG, cessões) |
cnpj.participacoes_setor_eletrico | cnpj* | ANEEL: composição societária declarada pelos agentes do setor elétrico, no ano mais recente |
cnpj.contratos_publicos / cpf.contratos_publicos | cnpj* / cpf* | Compras.gov.br: contratos do ano corrente em que o documento é o fornecedor |
cnpj.ambiental_autos / cpf.ambiental_autos | cnpj* / cpf* | IBAMA: autos de infração lavrados de 2016 em diante, com tipo, valor, status e cancelamento. Auto lavrado não é auto mantido: confira o status |
cnpj.tcu_inidoneos | cnpj* | TCU: licitantes declarados inidôneos, com processo, deliberação e até quando vale |
cpf.tcu_restricoes | cpf* | TCU: inidôneos para licitar e inabilitados para cargo em comissão e função de confiança |
cnpj.anvisa_afe | cnpj* | ANVISA: autorização de funcionamento por estabelecimento, com as atividades autorizadas (entre elas, transportar) |
cnpj.transporte_produtos_perigosos | cnpj* | IBAMA: autorização ambiental para transporte interestadual de produtos perigosos, com validade (três meses), classes de risco e estados de atuação |
cnpj.transporte_residuos | cnpj* | IBAMA (relatório anual): transporte de resíduos sólidos declarado, com o gerador e o ano |
POST /api/v1/consultas/cnpj.regulatorio_setorial
{ "parametros": { "cnpj": "15.413.826/0001-50" } }
// 200 (resumido)
{
"dados": {
"documento": "15413826000150",
"total": 9,
"registros": [
{ "fonte": "aneel_auto_infracao", "lista": "ANEEL - Autos de infracao", "orgao": "ANEEL",
"nome": "ENERGISA Mato Grosso do Sul - Distribuidora de Energia S/A - EMS",
"papel": "Agente fiscalizado", "situacao": "Multa", "data": "2019-03-22T00:00:00Z",
"referencia": "0001/2019-AGEPAN-SFE", "detalhe": "Fiscalizador: AGEPAN | Natureza: Indicadores de Continuidade | Valor: 813956,38 | ..." }
],
"fontesConsultadas": [
{ "fonte": "aneel_auto_infracao", "lista": "ANEEL - Autos de infracao",
"origem": "https://dadosabertos.aneel.gov.br/dataset/auto-de-infracao",
"registrosNaBase": 1589, "carregadaEm": "2026-09-23T00:00:00Z" }
],
"confiancaCasamento": "DocumentoExato",
"cobertura": "..."
},
"meta": { "consulta": "cnpj.regulatorio_setorial", "schema": "registros_publicos@v1", "provedor": "listas-publicas", "...": "..." }
}
total: 0comfontesConsultadaspreenchido significa que o documento foi conferido nessas listas e não consta.carregadaEmdiz de quando é a versão conferida.- Se alguma fonte ainda não terminou de carregar, ela aparece na
coberturacomo "NAO conferida". Se nenhuma carregou, a resposta é502: o hub não afirma "nada consta" sem ter a base. - A CPF só entram as fontes que publicam o CPF inteiro. CPF mascarado (
***.123.456-**) nunca é casado.
Custos, cota e cache
- Créditos. Cada fonte tem um custo em créditos por chamada bem-sucedida, e
0significa gratuita ou por assinatura. O custo aparece no catálogo, antes da chamada, e emmeta.custo, depois dela. - Sem trava de custo. Com token válido, o hub executa as fontes pagas sem confirmação; cada chamada fica registrada com o custo.
- Consumo registrado. Os créditos gastos por sistema são contados por mês para o relatório de custos, mas não bloqueiam a chamada. Fonte com franquia contratada esgotada é pulada, e a cascata segue para a próxima.
- Cache. Cada consulta declara um TTL em
fontes[].cacheHoras. Uma resposta de cache (meta.cache: true) não cobra e responde em milissegundos.
Transportadoras de cargas
Consultas sobre o registro e a habilitação de quem transporta carga. Todas sem custo, sobre bases abertas que o hub carrega (ANTT todo mês; IBAMA, ANVISA e TCU toda semana).
| Consulta | Parâmetros (* obrigatório) | O que devolve |
|---|---|---|
cnpj.rntrc | cnpj*, rntrc | Registro Nacional de Transportadores Rodoviários de Cargas: número, situação (a ANTT publica só ATIVO e PENDENTE), categoria (ETC empresa, CTC cooperativa), equiparado, datas e o histórico por competência |
cnpj.otm | cnpj* | Operador de transporte multimodal habilitado, com certificado e vigência |
cnpj.aptidao_transportador | cnpj*, cnae_principal, cnaes_secundarios, data_abertura, alguma_ie_habilitada | Parecer (Apto, AptoComRessalvas, Inapto, Inconclusivo, NaoSeAplica) com as verificações. Sem os parâmetros opcionais, que vêm do cadastro, o parecer sai Inconclusivo: prefira a ficha, que os preenche sozinha |
cnpj.estabelecimentos | cnpj* | Matriz e filiais pela raiz, com situação e CNAE. 1 crédito (CNPJá) |
- Filial. A ANTT registra o transportador, quase sempre pelo CNPJ da matriz.
cnpj.rntrcaceita o CNPJ da filial e resolve pela raiz:cnpjRegistradodiz qual CNPJ consta na ANTT,casamentovemDocumentoouRaiz, econfiancaCasamentovemRaizDoCnpjquando o registro é de outro estabelecimento da mesma empresa. - Número do documento fiscal. A ANTT publica o RNTRC com 9 dígitos; o CT-e e o MDF-e levam 8.
numeroRntrcNoDocumentoFiscaltraz o número em 8 dígitos. - Conferência do número declarado. Com o parâmetro
rntrc(o número lido de um CT-e, 8 ou 9 dígitos), a resposta trazrntrcInformadoConferee, quando o número é de outra empresa,titularDoRntrcInformado. O número do documento serve para conferir, não para cadastrar: em amostra de 26 transportadoras, 5 declaravam no CT-e um número que não era o delas. - Validade. Não existe na base aberta; o certificado tem hoje validade indeterminada.
POST /api/v1/transportadores/ficha
{ "cnpj": "11193322000200", "rntrc": "00123456", "incluirEstabelecimentos": false, "incluirProcessos": false, "semCadastro": false }
Junta numa chamada cadastro, Simples, RNTRC, OTM, aptidão, sanções, TCU, dívida ativa, embargos e autos ambientais, trabalho escravo, produtos perigosos, ANVISA e resíduos. Devolve resumo, blocos[], avisos[], correlationId, custoCreditos e latenciaMs.
- Cada bloco tem
statuspróprio:ok,nada_encontrado(conferido, sem registro),nao_verificado(a conferência não foi feita; não é "não consta") ousem_permissao(a consulta do bloco não está liberada para a sua credencial). - Para CNPJ de filial, os blocos conferidos por documento vêm também para a matriz, com o sufixo
_matriz.resumo.cnpjDaMatrizsó vem quando a Receita confirma a matriz; nunca é presumido. - Grave o RNTRC só com
resumo.podeGravarRntrc = true. - A ficha tem prazo total de 90 s e executa até 4 blocos por vez; o bloco que não responder no prazo volta
nao_verificado. Use um tempo limite de cliente de pelo menos 100 s. Sem cache, uma ficha de filial leva de 20 a 45 s. incluirEstabelecimentosacrescenta matriz e filiais (1 crédito);incluirProcessosacrescenta os processos pela razão social (busca por nome, aproximada);semCadastropula o cadastro na Receita, que é o gargalo em lote.
O pacote cnpj.transportador reúne as mesmas verificações no formato de dossiê.
Ex-sócios e pessoa física por nome
Quem saiu do quadro societário. cnpj.qsa_historico (parâmetro cnpj, casa pela raiz; custo zero) devolve os vínculos encerrados que o hub monta comparando, mês a mês, a base aberta de sócios da Receita. Cobre de 2023-05 em diante e não depende de o hub ter consultado a empresa antes. Cada item de dados.dados[] traz nome_socio, tipo_socio, qualificacao (código da Receita), data_entrada, constava_ate e ausente_desde (meses, AAAA-MM), evento e o documento do ex-sócio: documento_socio com tipo_de_documento = cpf_mascarado (pessoa física, ***NNNNNN**) ou cnpj_raiz (pessoa jurídica, com cnpj_matriz_presumido: raiz + 0001, não conferido).
evento vale saida, qualificacao_alterada (a pessoa continua, com outro papel) ou nao_verificado. Trate como ex-sócio apenas saida.Pessoa física só pelo nome. Do ex-sócio pessoa física só se conhece o nome e o CPF mascarado, e as consultas cpf.* exigem o CPF completo. As consultas pessoa.processos, pessoa.criminal, pessoa.midia_adversa, pessoa.sancoes_internacionais e pessoa.sancoes_br fazem a busca sem CPF. Parâmetros: nome (obrigatório; pelo menos duas palavras e oito letras, sem dígitos) e cpf_mascarado (opcional; obrigatório em pessoa.sancoes_br, onde filtra por máscara + nome; aceita ***NNNNNN** ou os seis dígitos). Enviar cpf, cnpj, documento ou onze dígitos na máscara responde 400. Custo zero em todas.
confiancaCasamento nunca sai DocumentoExato, e a cobertura diz que a busca foi só pelo nome. Sem resultado por nome não é "nada consta" da pessoa. Nada é gravado sob CPF. Em processos, mídia e sanções internacionais a máscara não filtra (as fontes não publicam documento); ela só é registrada na cobertura. Cada aplicação precisa ter essas consultas liberadas.Processos: ler a publicação e chegar ao tribunal
As consultas de processos (cnpj.processos, cpf.processos, cnpj.criminal, cpf.criminal, cnpj.processos_socios) buscam por nome no Diário de Justiça Eletrônico Nacional e, para até 50 processos, conferem cada um na base nacional do CNJ.
- Tempo. O detalhamento na base nacional tem orçamento de 45 s (30 s na de sócios). Ao estourar, a resposta volta com todos os processos achados,
detalhamentoParcial: trueeprocessosSemDetalhe; os que ficaram sem detalhe trazem o que o diário mostrou. Repetir mais tarde, sem cache, completa. acesso, em cada processo.numeroCnj(o número decomposto nos seis campos dos formulários),consultaDireta(endereço que abre o processo — só para tribunal em que isso foi conferido com um processo real),consultaPublicacomestadoDaConsultaPublicaeexige(captcha,login...),diario(o diário nacional já filtrado pelo processo, sem captcha nem login) ecomoAcessar[], o passo a passo.tribunalPorExtensoevita confundir, por exemplo, TRF3 com TRT3.
POST /api/v1/consultas/processo.comunicacoes
{ "parametros": { "numero": "1234567-89.2024.8.26.0100" } }
As publicações de um processo no diário nacional, com o texto, pelo número do CNJ (20 dígitos, com ou sem a máscara). Devolve numero, tribunal, tribunalPorExtenso, acesso, total, truncado e comunicacoes[], da mais recente para a mais antiga: disponibilizadaEm, orgao, classe, tipoDeComunicacao, tipoDeDocumento (como o tribunal informou: sentença, despacho...), texto, textoCortado, link e partes[].
- É o texto da comunicação publicada, não o documento assinado nos autos. Vem sem marcação HTML; mostre-o como texto. Parte dos tribunais publica o texto numa linha só.
- Até 30 comunicações por processo e 60.000 caracteres por texto; o que passar disso é avisado em
truncadoetextoCortado. Sem custo; cache de 6 horas.
Como ler três retornos
cnpj.cadastro, campomatriz.true,falseou nulo: é o que a Receita informa para o estabelecimento. Não deduza a matriz pelo0001. Resposta que estava em cache antes de o campo existir vem sem ele até o cache vencer (1 dia).- Dívida ativa (
cnpj.divida_ativa,cpf.divida_ativa). A PGFN publica, a cada trimestre, o estoque inteiro de inscrições; cada competência é uma foto, não um lote novo.total,totalDeInscricoes,valorTotaleajuizadassomam só a foto mais recente de cada base. Cada linha deinscricoes[]trazvigente; as defalsesão histórico. - Processos, campo
link. É o endereço do documento da publicação no tribunal, não o do processo. Em tribunal com PJe ele abre a conferência do documento; o texto aparece no ícone "Visualizar", em janela nova, que o navegador costuma bloquear. A busca de processos é por nome e só enxerga o que foi publicado no Diário de Justiça Eletrônico Nacional: não é certidão negativa.
Erros
Os erros de negócio saem em JSON:
{
"error": {
"code": "ConsultasHub:ParametroInvalido",
"message": "Parametro invalido ou ausente.",
"data": { "parametro": "cnpj", "motivo": "CNPJ invalido (digitos verificadores nao conferem)" }
}
}
Envie Accept-Language: pt-BR para receber message em português. Trate o erro pelo code, que é estável, e não pela mensagem.
| HTTP | error.code | Quando | O que fazer |
|---|---|---|---|
| 400 | ConsultasHub:ParametroInvalido | Parâmetro obrigatório ausente ou documento inválido. data.parametro e data.motivo explicam. | Corrigir a entrada. Não repetir. |
| 400 | (validação) | Corpo fora do formato: mais de 20 parâmetros, valor acima de 512 caracteres, lote vazio ou com mais de 50 itens. | Corrigir o pedido. |
| 401 | — | Sem token, token expirado ou inválido. | Pedir um novo token. |
| 403 | ConsultasHub:SemPermissao | A consulta não está liberada para o seu sistema, ou a credencial foi desativada. | Falar com o administrador. |
| 404 | ConsultasHub:ConsultaDesconhecida / PacoteDesconhecido | O id não existe no catálogo. | Conferir em GET /api/v1/consultas ou /api/v1/pacotes. |
| 404 | ConsultasHub:ProvedorIndisponivel | O provedor forçado não atende a consulta. | Remover provedor ou escolher outro do catálogo. |
| 413 | — | Corpo acima de 1 MB. Dependendo do cliente HTTP, aparece como conexão encerrada pelo servidor. | Dividir o lote. |
| 429 | ConsultasHub:LimiteDeTaxa | Limite de chamadas por minuto atingido. | Esperar o tempo do cabeçalho Retry-After, em segundos. |
| 502 | ConsultasHub:NenhumProvedorRespondeu | Todas as fontes falharam e não havia resultado salvo para a mesma pergunta. data.tentativas resume o que cada uma devolveu. | Tentar de novo mais tarde, com espera crescente. |
| 500 | — | Falha interna. | Repetir com espera crescente e informar o correlationId ao suporte. |
Limites de uso
| Limite | Valor padrão | Chave |
|---|---|---|
| Chamadas à API por minuto | 120 | por client_id |
| Pedidos de token por minuto | 20 | por IP |
| Requisições gerais por minuto | 600 | por IP |
| Itens por lote | 50 | por chamada |
| Parâmetros por consulta | 20, com valores de até 512 caracteres | por chamada |
| Tamanho do corpo | 1 MB | por chamada |
| Validade do token | 3.600 s | por token |
Fila, prioridade e transbordo. Cada fonte tem duas faixas de espera: chamada interativa (consulta avulsa, ficha, pacote) passa na frente de lote (rota /lote, agendamentos e execuções em segundo plano). Quando a espera estimada numa fonte passa de 5 s e há outra fonte adiante, ela é pulada (tentativa FilaCheia) e a próxima responde, mesmo que seja paga. A espera pela vez tem prazo de 30 s para chamada interativa e de 10 min para lote; estourado, a tentativa termina em FilaCheia e a cascata segue. Fila cheia nunca vira "não encontrado": sem fonte que responda, o desfecho é NenhumProvedorRespondeu ou o último resultado salvo, marcado em meta.resultadoSalvo.
Algumas fontes externas têm ritmo próprio. O hub enfileira e cadencia as chamadas a elas, e por isso uma consulta pode levar alguns segundos. Consultas a listas grandes (sanções internacionais, embargos) podem levar de 1 a 3 minutos na primeira chamada depois que a lista expira; as seguintes respondem do cache. Use timeout de cliente de 300 s.
Segurança e LGPD
- O segredo fica no servidor. Nunca coloque o
client_secretem aplicativo móvel, front-end, repositório ou log. Se houver suspeita de vazamento, peça a rotação: o segredo antigo para de emitir token na hora. - Só HTTPS. O hub responde apenas em HTTPS (TLS 1.2 ou superior), com HSTS.
- O documento nunca vai na URL. CPF e CNPJ vão sempre no corpo JSON, para não aparecerem em log de proxy ou de navegador.
- Base legal. Seu sistema é responsável por ter base legal (LGPD, art. 7º) para consultar dados pessoais de terceiros. Toda chamada é auditada com o
client_id, a data, a consulta e a fonte. - Mínimo necessário. Peça ao administrador só as consultas de que o seu processo realmente precisa.
Exemplos completos
Os exemplos leem o segredo de uma variável de ambiente e reaproveitam o token até perto de expirar.
BASE=https://api.jabuticaba.cloud
TOKEN=$(curl -s -X POST $BASE/connect/token \
-d grant_type=client_credentials -d client_id=$HUB_CLIENT_ID \
-d client_secret="$HUB_CLIENT_SECRET" -d scope=ConsultasHub | jq -r .access_token)
curl -s -X POST $BASE/api/v1/consultas/cnpj.cadastro \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "Accept-Language: pt-BR" \
-d '{"parametros":{"cnpj":"53798634000106"}}' | jq '.dados.razaoSocial, .meta.custo'using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
public sealed class ConsultasHubClient(HttpClient http, string clientId, string clientSecret)
{
private string? _token;
private DateTimeOffset _expira;
private async Task<string> TokenAsync(CancellationToken ct)
{
if (_token is not null && DateTimeOffset.UtcNow < _expira) return _token;
var r = await http.PostAsync("/connect/token", new FormUrlEncodedContent(new Dictionary<string, string>
{
["grant_type"] = "client_credentials", ["client_id"] = clientId,
["client_secret"] = clientSecret, ["scope"] = "ConsultasHub"
}), ct);
r.EnsureSuccessStatusCode();
var j = await r.Content.ReadFromJsonAsync<JsonElement>(ct);
_token = j.GetProperty("access_token").GetString();
_expira = DateTimeOffset.UtcNow.AddSeconds(j.GetProperty("expires_in").GetInt32() - 60);
return _token!;
}
public async Task<JsonElement> ConsultarAsync(string consultaId, object parametros,
bool confirmarCusto = false, CancellationToken ct = default)
{
using var req = new HttpRequestMessage(HttpMethod.Post, $"/api/v1/consultas/{consultaId}")
{
Content = JsonContent.Create(new { parametros, confirmarCusto })
};
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", await TokenAsync(ct));
req.Headers.AcceptLanguage.ParseAdd("pt-BR");
var r = await http.SendAsync(req, ct);
var corpo = await r.Content.ReadFromJsonAsync<JsonElement>(ct);
if (!r.IsSuccessStatusCode)
throw new InvalidOperationException($"{(int)r.StatusCode} {corpo.GetProperty("error").GetProperty("code")}");
return corpo;
}
}
// uso
var http = new HttpClient { BaseAddress = new Uri("https://api.jabuticaba.cloud"), Timeout = TimeSpan.FromSeconds(300) };
var hub = new ConsultasHubClient(http, "SEU_CLIENT_ID", Environment.GetEnvironmentVariable("HUB_CLIENT_SECRET")!);
var r = await hub.ConsultarAsync("cnpj.cadastro", new { cnpj = "53798634000106" });
Console.WriteLine(r.GetProperty("dados").GetProperty("razaoSocial"));import os, time, requests
BASE = "https://api.jabuticaba.cloud"
_token = {"valor": None, "expira": 0}
def token():
if _token["valor"] and time.time() < _token["expira"]:
return _token["valor"]
r = requests.post(f"{BASE}/connect/token", data={
"grant_type": "client_credentials", "client_id": os.getenv("HUB_CLIENT_ID"),
"client_secret": os.getenv("HUB_CLIENT_SECRET"), "scope": "ConsultasHub"}, timeout=30)
r.raise_for_status()
j = r.json()
_token.update(valor=j["access_token"], expira=time.time() + j["expires_in"] - 60)
return _token["valor"]
def consultar(consulta_id, parametros, confirmar_custo=False):
r = requests.post(f"{BASE}/api/v1/consultas/{consulta_id}",
json={"parametros": parametros, "confirmarCusto": confirmar_custo},
headers={"Authorization": f"Bearer {token()}", "Accept-Language": "pt-BR"},
timeout=300)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "60")))
return consultar(consulta_id, parametros, confirmar_custo)
if not r.ok:
raise RuntimeError(f"{r.status_code} {r.json().get('error', {}).get('code')}")
return r.json()
env = consultar("cnpj.cadastro", {"cnpj": "53798634000106"})
print(env["dados"]["razaoSocial"], env["meta"]["custo"])// Node 18+ (fetch nativo)
const BASE = "https://api.jabuticaba.cloud";
let cache = { token: null, expira: 0 };
async function token() {
if (cache.token && Date.now() < cache.expira) return cache.token;
const r = await fetch(`${BASE}/connect/token`, {
method: "POST",
body: new URLSearchParams({
grant_type: "client_credentials", client_id: process.env.HUB_CLIENT_ID,
client_secret: process.env.HUB_CLIENT_SECRET, scope: "ConsultasHub" })
});
if (!r.ok) throw new Error(`token: ${r.status}`);
const j = await r.json();
cache = { token: j.access_token, expira: Date.now() + (j.expires_in - 60) * 1000 };
return cache.token;
}
async function consultar(consultaId, parametros, confirmarCusto = false) {
const r = await fetch(`${BASE}/api/v1/consultas/${consultaId}`, {
method: "POST",
headers: { Authorization: `Bearer ${await token()}`, "Content-Type": "application/json", "Accept-Language": "pt-BR" },
body: JSON.stringify({ parametros, confirmarCusto }),
signal: AbortSignal.timeout(300_000)
});
const corpo = await r.json().catch(() => ({}));
if (!r.ok) throw new Error(`${r.status} ${corpo.error?.code ?? ""}`);
return corpo;
}
const env = await consultar("cnpj.cadastro", { cnpj: "53798634000106" });
console.log(env.dados.razaoSocial, env.meta.custo);<?php
$base = 'https://api.jabuticaba.cloud';
$ch = curl_init("$base/connect/token");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'client_credentials', 'client_id' => getenv('HUB_CLIENT_ID'),
'client_secret' => getenv('HUB_CLIENT_SECRET'), 'scope' => 'ConsultasHub'])]);
$token = json_decode(curl_exec($ch), true)['access_token'];
$ch = curl_init("$base/api/v1/consultas/cnpj.cadastro");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 300,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", 'Content-Type: application/json', 'Accept-Language: pt-BR'],
CURLOPT_POSTFIELDS => json_encode(['parametros' => ['cnpj' => '53798634000106']])]);
$env = json_decode(curl_exec($ch), true);
echo $env['dados']['razaoSocial'];Suporte
Para pedir credencial, liberar consultas ou relatar um problema, fale com o administrador do hub. Informe sempre o client_id e, para problemas numa chamada, o meta.correlationId ou o horário exato. Nunca envie o client_secret.
Consultas Hub · API v1 · este guia descreve o comportamento verificado em chamadas reais.