Consultas Hub· Guia de integração Swagger

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:

A resposta vem sempre num formato padronizado, o mesmo para qualquer fonte que tenha respondido.

ItemValor
URL basehttps://api.jabuticaba.cloud
Versão/api/v1
FormatoJSON UTF-8, com campos em camelCase
AutenticaçãoOAuth 2.0 client credentials (token Bearer)
Contrato OpenAPI/swagger/consumo/swagger.json · interface interativa em /swagger

Início rápido

  1. Receba a credencial. O administrador do hub cadastra o seu sistema e entrega um client_id e um client_secret, junto com as consultas liberadas. O segredo é mostrado uma única vez: guarde-o no cofre de segredos do seu servidor.
  2. 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
  3. 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_typeclient_credentials
client_idIdentificador do seu sistema, entregue pelo administrador
client_secretSegredo do seu sistema
scopeConsultasHub
{
  "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çãoResposta
Segredo ou client_id inválido401 {"error":"invalid_client"}
Chamada à API sem token, ou com token expirado401 sem corpo
Consulta não liberada para o seu sistema403 ConsultasHub:SemPermissao
Rota administrativa403. Credenciais de sistema não acessam /api/v1/admin

Endpoints

MétodoRotaPara quê
GET/api/v1/consultasCatá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}/loteExecuta a mesma consulta para até 50 entradas
GET/api/v1/pacotesCatá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/consultarO que o seu sistema já consultou sobre um documento
POST/api/v1/historico/compararO que mudou no dado de um documento entre duas datas
POST/api/v1/retroativo/vigentesO último resultado salvo de cada consulta de um documento, sem consultar a fonte de novo
POST/api/v1/retroativo/historicoTodas as versões salvas de uma consulta de um documento
POST/api/v1/transportadores/fichaFicha 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/teiaTeia 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
Os identificadores seguem o padrão <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
}
CampoTipoDescrição
parametrosobjeto de textoObrigató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.
confirmarCustobooleanoAceito por compatibilidade e ignorado: com token válido, as fontes pagas entram na cascata sem confirmação. O custo de cada chamada fica registrado.
ignorarCachebooleanoVai à 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.
provedortextoOpcional. 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 metaSignificado
schemaContrato versionado de dados. Uma mudança incompatível gera nova versão (@v2) e não quebra quem usa a @v1.
provedor / origemA fonte que respondeu e a URL consultada, sem credenciais.
dataReferenciaQuando a fonte atualizou o dado. Vem null quando a fonte não informa.
obtidoEmQuando o hub buscou o dado. Numa resposta de cache, é a data da coleta original.
cachetrue quando a resposta veio do cache, sem tocar a fonte e sem custo.
parcialtrue 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 / salvoEmresultadoSalvo: 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.
custoCréditos efetivamente debitados nesta chamada e o modelo de cobrança da fonte.
correlationIdIdentificador da chamada. Informe-o ao suporte para rastrear um caso.
tentativasAs 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
}
CampoDescrição
documentoCPF ou CNPJ, conforme o tipo do pacote.
confirmarCusto / tetoCreditosAceitos por compatibilidade e ignorados: a execução não exige confirmação nem teto.
nome / dataNascimentoOpcionais. Melhoram as buscas feitas por nome (processos, mídia) e o casamento de pessoa física.
semTeiaOpcional. true não monta a teia societária nos pacotes que a incluem (usado em lote, para não repetir a mesma teia).
itensOpcional. Executa só as chaves de item indicadas, em vez do pacote inteiro.

A resposta traz:

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

O catálogo completo e atual está em GET /api/v1/consultas. Para cada consulta, ele traz:

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.

ConsultaDescriçãoParâmetros (* obrigatório)SchemaTempo medido
cnpj.ambientalEmbargos ambientais do IBAMAcnpj*listas_restritivas@v150.4 s
cnpj.bensBens registrados em nome da empresacnpj*bens_localizados@v11.2 min*
cnpj.cadastroDados cadastrais de CNPJcnpj* diascnpj_cadastral@v12.0 s
cnpj.criminalProcessos criminais da partedocumento* nome*processos_judiciais@v11.4 s
cnpj.divida_ativaDivida ativa da Uniaocnpj*divida_ativa@v11.3 s
cnpj.documentos_fundoDocumentos do fundo no FNET (informes, fatos relevantes, assembleias)cnpj* limiteresultado_da_fonte@v11.6 s
cnpj.fundoFicha de fundo de investimento (cadastro CVM)cnpj*fundo_investimento@v10.6 s
cnpj.fundos_geridosFundos por gestora ou administradora (cadastro CVM)cnpj*resultado_da_fonte@v11.4 s
cnpj.processosProcessos judiciais de pessoa juridicacnpj* nome*processos_judiciais@v17.8 s
cnpj.registro_bacenAutorizacao do Banco Central (instituicao em funcionamento)cnpj*registro_bacen@v10.5 s
cnpj.registro_cvmRegistro na CVM: corretora, distribuidora ou fundocnpj*registro_cvm@v15.1 s
cnpj.regulatorioSancoes de reguladores do mercado de capitaiscnpj* nome*listas_restritivas@v110.1 s
cnpj.sancoes_brSancoes administrativas (CEIS, CNEP, leniencia)cnpj*listas_restritivas@v17.8 s
cnpj.sancoes_internacionaisSancoes internacionaiscnpj* nome*listas_restritivas@v12.6 min*
cnpj.simples_nacionalOpcao pelo Simples Nacional e MEIcnpj*situacao_no_simples@v11.2 s
cnpj.trabalho_escravoCadastro de empregadores (lista suja)cnpj*listas_restritivas@v11.4 s
cpf.ambientalEmbargos ambientais do IBAMAcpf*listas_restritivas@v10.8 s
cpf.bensBens registrados em nome da pessoacpf*bens_localizados@v10.6 s
cpf.cadastroCadastro de pessoa fisica (CPF Hub)cpf* data_nascimentocpf_cadastral@v11.3 s
cpf.criminalProcessos criminais da partedocumento* nome*processos_judiciais@v10.8 s
cpf.divida_ativaDivida ativa da Uniaocpf* nome*divida_ativa@v11.0 s
cpf.pepPessoa exposta politicamente (CGU)cpf*listas_restritivas@v10.8 s
cpf.processosProcessos judiciais de pessoa fisicacpf* nome*processos_judiciais@v13.0 s
cpf.regulatorioSancoes de reguladores do sistema financeirocpf* nomelistas_restritivas@v10.8 s
cpf.sancoes_brSancoes administrativas (CEIS, CNEP, leniencia)cpf*listas_restritivas@v11.9 s
cpf.sancoes_internacionaisSancoes internacionaiscpf* nome*listas_restritivas@v10.6 s
cpf.servidorVinculo com o servico publico federalcpf*listas_restritivas@v11.4 min*
cpf.trabalho_escravoCadastro de empregadores (lista suja)cpf*listas_restritivas@v10.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.

Dependem de carga de base ou de fonte instável.
  • 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 é 502 NenhumProvedorRespondeu: o hub não afirma ausência sem ter a base. Em cpf.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_adversa e cnpj.midia_adversa usam o GDELT, que aplica limite próprio de chamadas. Quando ele recusa, o hub repete uma vez e depois responde 502. 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.

ConsultaParâmetroFontes conferidas
cnpj.regulatorio_setorialcnpj*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_setorialcpf*ANEEL: autos, intimações e penas de editais lavrados contra pessoa física
cnpj.ambiental_termos / cpf.ambiental_termoscnpj* / cpf*IBAMA: termos de destruição/inutilização e de suspensão (os embargos ficam em *.ambiental)
cnpj.registros_setoriaiscnpj*SUSEP (empresas reguladas), CVM (companhias abertas), ANVISA (autorização de funcionamento), ANTT (transporte interestadual de passageiros e operadores multimodais), MDS (CEBAS e CNEAS)
cnpj.otmcnpj*ANTT: operadores de transporte multimodal habilitados, com certificado e vigência
cnpj.direitos_minerarios / cpf.direitos_minerarioscnpj* / cpf*ANM: titularidade de processos no Cadastro Mineiro (requerimentos, alvarás, lavras, licenciamentos, PLG, cessões)
cnpj.participacoes_setor_eletricocnpj*ANEEL: composição societária declarada pelos agentes do setor elétrico, no ano mais recente
cnpj.contratos_publicos / cpf.contratos_publicoscnpj* / cpf*Compras.gov.br: contratos do ano corrente em que o documento é o fornecedor
cnpj.ambiental_autos / cpf.ambiental_autoscnpj* / 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_inidoneoscnpj*TCU: licitantes declarados inidôneos, com processo, deliberação e até quando vale
cpf.tcu_restricoescpf*TCU: inidôneos para licitar e inabilitados para cargo em comissão e função de confiança
cnpj.anvisa_afecnpj*ANVISA: autorização de funcionamento por estabelecimento, com as atividades autorizadas (entre elas, transportar)
cnpj.transporte_produtos_perigososcnpj*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_residuoscnpj*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", "...": "..." }
}

Custos, cota e cache

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).

ConsultaParâmetros (* obrigatório)O que devolve
cnpj.rntrccnpj*, rntrcRegistro 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.otmcnpj*Operador de transporte multimodal habilitado, com certificado e vigência
cnpj.aptidao_transportadorcnpj*, cnae_principal, cnaes_secundarios, data_abertura, alguma_ie_habilitadaParecer (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.estabelecimentoscnpj*Matriz e filiais pela raiz, com situação e CNAE. 1 crédito (CNPJá)

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.

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).

Não há data exata de saída, só o último mês em que o vínculo constava. E sumir do quadro nem sempre é saída: 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.

Resultado por nome admite homônimo e não identifica a pessoa: 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.

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[].

Como ler três retornos

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.

HTTPerror.codeQuandoO que fazer
400ConsultasHub:ParametroInvalidoParâ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.
403ConsultasHub:SemPermissaoA consulta não está liberada para o seu sistema, ou a credencial foi desativada.Falar com o administrador.
404ConsultasHub:ConsultaDesconhecida / PacoteDesconhecidoO id não existe no catálogo.Conferir em GET /api/v1/consultas ou /api/v1/pacotes.
404ConsultasHub:ProvedorIndisponivelO 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.
429ConsultasHub:LimiteDeTaxaLimite de chamadas por minuto atingido.Esperar o tempo do cabeçalho Retry-After, em segundos.
502ConsultasHub:NenhumProvedorRespondeuTodas 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

LimiteValor padrãoChave
Chamadas à API por minuto120por client_id
Pedidos de token por minuto20por IP
Requisições gerais por minuto600por IP
Itens por lote50por chamada
Parâmetros por consulta20, com valores de até 512 caracterespor chamada
Tamanho do corpo1 MBpor chamada
Validade do token3.600 spor 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

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'

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.