Ecomciencia · API pública

Consulta de CNPJ sobre os dados abertos da Receita Federal

Themis responde no mesmo contrato da Consulta CNPJ v2 do SERPRO: mesmos caminhos, mesmos nomes de campo, mesmos códigos de retorno. Um cliente escrito para a API deles funciona apontando para esta, trocando a URL base e as credenciais.

Situação: consultando…
Competência: —
Registros: —
Base construída em: —

Endpoints

Autenticação OAuth2 client_credentials. O token é um Bearer com validade de uma hora.

Rota	Autenticação	Devolve
`POST /token`	Basic (Key/Secret)	Emite o Bearer
`GET /v2/basica/{ni}`	Bearer	Dados cadastrais, sem o quadro societário
`GET /v2/qsa/{ni}`	Bearer	Quadro de sócios e administradores
`GET /v2/empresa/{ni}`	Bearer	Cadastrais e quadro societário juntos
`GET /saude`	nenhuma	Competência em disco e sinal de vida
`POST /mcp`	Bearer (token MCP)	Camada MCP para agentes de IA — ver abaixo

Como autenticar

Dois passos: trocar a credencial pelo token, usar o token.

# 1. Consumer Key e Secret viram um Bearer de 1 hora
curl -X POST https://themis.ecomciencia.com/token \
  -H "Authorization: Basic $(echo -n 'SUA_KEY:SEU_SECRET' | base64)" \
  -d 'grant_type=client_credentials'

# {"access_token":"...","token_type":"Bearer","expires_in":3600,"scope":"default"}

# 2. A consulta
curl https://themis.ecomciencia.com/v2/empresa/00000000000191 \
  -H "Authorization: Bearer SEU_TOKEN"

Para agentes de IA: MCP

Além do contrato do SERPRO, o Themis fala o Model Context Protocol em POST /mcp — o padrão aberto pelo qual plataformas agênticas descobrem e usam ferramentas. O agente consulta CNPJ como uma ferramenta, sem código de integração, e deixa de preencher razão social ou situação cadastral de memória.

Plugar e usar

Registre a URL e o token no cliente MCP do agente. As ferramentas aparecem sozinhas, com descrição e parâmetros.

Segredo fora do modelo

O token fica na configuração do cliente. O modelo vê as ferramentas, nunca a credencial.

Resposta feita para agente

Enxuta, sem os campos que o contrato do SERPRO manda sempre nulos, com capital social exato e a competência do dado em toda resposta.

Salvaguardas no protocolo

O servidor avisa ao modelo que a base é um retrato mensal, que texto de cadastro é dado e não instrução, e que base fora do ar é valor desconhecido — não dado inventado.

Ferramenta	O que faz	Cobrada
`validar_cnpj`	Confere o dígito verificador, numérico ou alfanumérico, sem consultar a base	não
`situacao_cadastral`	Resposta curta: razão social, matriz ou filial, situação com data e motivo, abertura e município	sim
`consultar_empresa`	Cadastro completo: natureza jurídica, porte, capital, endereço, contato, CNAEs e Simples. Sócios só com `incluir_socios`	sim
`themis://competencia`	Recurso: competência, data de construção e tamanho da base servida	não

# OpenClaw
openclaw mcp add themis --url https://themis.ecomciencia.com/mcp \
  --header "Authorization=Bearer SEU_TOKEN_MCP"

# Claude Code
claude mcp add --transport http themis https://themis.ecomciencia.com/mcp \
  --header "Authorization: Bearer SEU_TOKEN_MCP"

# .mcp.json (Claude Code e clientes com o mesmo formato)
{"mcpServers": {"themis": {"type": "http",
  "url": "https://themis.ecomciencia.com/mcp",
  "headers": {"Authorization": "Bearer SEU_TOKEN_MCP"}}}}

O token do MCP é outro. Não é o Bearer de uma hora do /token: é emitido pela Ecomciencia para a sua credencial, vale até um ano e só funciona em /mcp — as rotas REST o recusam, e o /mcp recusa o token delas. Revogar a credencial ou trocar o Consumer Secret o invalida na hora. Para obter, use o formulário abaixo e diga na finalidade que o uso é por agente (MCP).

Sócio só quando a tarefa pede. O quadro societário traz nome de pessoa física; consultar_empresa só o devolve com incluir_socios: true, para não mandar dado pessoal ao contexto do modelo — e ao provedor dele — sem necessidade.

Junto com o Hestia, o agente confere o cadastro inteiro. Com o Hestia, a consulta de CEP da mesma casa, um agente consulta o CNPJ aqui, pega o CEP do endereço cadastrado e confere o logradouro nos Correios — as duas fontes oficiais, sem ninguém no meio.

Mesma cota, mesma cobrança, autenticação por cabeçalho. Cada consulta pelo MCP conta como uma consulta da API. Funciona com qualquer cliente MCP que envie cabeçalho de autorização — conferido com o cliente oficial do protocolo e com o OpenClaw. Conectores que exigem login OAuth ainda não são atendidos.

Documentação

A especificação é gerada a partir do próprio código, então ela descreve o que está no ar agora — não uma versão anterior.

Swagger UI

Referência navegável, com os esquemas de cada resposta e a possibilidade de experimentar as chamadas.

Abrir /docs →

ReDoc

A mesma especificação em leitura corrida, melhor para ler de ponta a ponta antes de implementar.

Abrir /redoc →

OpenAPI 3.1

O documento cru, para gerar cliente automaticamente ou importar no Postman e no Insomnia.

Baixar /openapi.json →

Situação do serviço

Qual competência está sendo servida, quantos registros e quando a base foi construída.

Consultar /saude →

Duas diferenças em relação ao SERPRO

Nenhuma é defeito de implementação — são propriedades da fonte. Estão documentadas no OpenAPI, no campo onde mordem, e ficam aqui porque mudam o que dá para fazer com a resposta.

O CPF dos sócios vem mascarado (***794780**). É assim que o dado é publicado pela Receita Federal. O SERPRO, como canal autorizado, devolve o número completo; esta API não tem acesso a ele.

A base é um retrato mensal, não tempo real. Empresa aberta ontem não está aqui; baixa da semana passada ainda aparece ativa. O /saude informa a competência exata que está sendo servida, para que a decisão de confiar no dado seja de quem consulta.