Como usar

O Minha Receita oferece duas APIs web:

a principal é para consulta de CNPJ
a de grafos é para consulta de relações entre pessoas físicas e jurídicas

URL

Nos exemplos a seguir, substitua https://minhareceita.org por http://0.0.0.0:8000 caso esteja rodando o servidor localmente.

API principal

A API web tem apenas um endpoint principal: /<número do CNPJ>.

Caminho da URL	Tipo de requisição	Código esperado na resposta	Conteúdo esperado na resposta
`/`	`POST`	405	`{"message": "Essa URL aceita apenas o método GET."}`
`/`	`HEAD`	405	`{"message": "Essa URL aceita apenas o método GET."}`
`/`	`GET`	302	Redireciona para essa documentação.
`/foobar`	`GET`	400	`{"message": "CNPJ foobar inválido."}`
`/00000000000000`	`GET`	404	`{"message": "CNPJ 00.000.000/0000-00 não encontrado."}`
`/00.000.000/0000-00`	`GET`	404	`{"message": "CNPJ 00.000.000/0000-00 não encontrado."}`
`/33683111000280`	`GET`	200	Ver Exemplo de resposta válida abaixo.
`/33.683.111/0002-80`	`GET`	200	Ver Exemplo de resposta válida abaixo.
`/?uf=SP`	`GET`	200	Ver Busca paginada abaixo.

Exemplos

Exemplo de requisição usando o `curl`

$ curl https://minhareceita.org/33683111000280

Exemplo de resposta válida

JSON

{
    "cnpj": "33683111000280",
    "identificador_matriz_filial": 2,
    "descricao_identificador_matriz_filial": "FILIAL",
    "nome_fantasia": "REGIONAL BRASILIA-DF",
    "situacao_cadastral": 2,
    "descricao_situacao_cadastral": "ATIVA",
    "data_situacao_cadastral": "2004-05-22",
    "motivo_situacao_cadastral": 0,
    "descricao_motivo_situacao_cadastral": "SEM MOTIVO",
    "nome_cidade_no_exterior": "",
    "codigo_pais": null,
    "pais": null,
    "data_inicio_atividade": "1967-06-30",
    "cnae_fiscal": 6204000,
    "cnae_fiscal_descricao": "Consultoria em tecnologia da informação",
    "descricao_tipo_de_logradouro": "AVENIDA",
    "logradouro": "L2 SGAN",
    "numero": "601",
    "complemento": "MODULO G",
    "bairro": "ASA NORTE",
    "cep": "70836900",
    "uf": "DF",
    "codigo_municipio": 9701,
    "codigo_municipio_ibge": 5300108,
    "municipio": "BRASILIA",
    "ddd_telefone_1": "",
    "ddd_telefone_2": "",
    "ddd_fax": "",
    "situacao_especial": "",
    "data_situacao_especial": null,
    "opcao_pelo_simples": null,
    "data_opcao_pelo_simples": null,
    "data_exclusao_do_simples": null,
    "opcao_pelo_mei": null,
    "data_opcao_pelo_mei": null,
    "data_exclusao_do_mei": null,
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "codigo_natureza_juridica": 2011,
    "natureza_juridica": "Empresa Pública",
    "qualificacao_do_responsavel": 16,
    "capital_social": 1061004800,
    "codigo_porte": 5,
    "porte": "DEMAIS",
    "ente_federativo_responsavel": null,
    "regime_tributario": null,
    "qsa": [
        {
            "identificador_de_socio": 2,
            "nome_socio": "ANDRE DE CESERO",
            "cnpj_cpf_do_socio": "***220050**",
            "codigo_qualificacao_socio": 10,
            "qualificacao_socio": "Diretor",
            "data_entrada_sociedade": "2016-06-16",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 6,
            "faixa_etaria": "Entre 51 a 60 anos"
        },
        {
            "identificador_de_socio": 2,
            "nome_socio": "ANTONIO DE PADUA FERREIRA PASSOS",
            "cnpj_cpf_do_socio": "***595901**",
            "codigo_qualificacao_socio": 10,
            "qualificacao_socio": "Diretor",
            "data_entrada_sociedade": "2016-12-08",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 7,
            "faixa_etaria": "Entre 61 a 70 anos"
        },
        {
            "identificador_de_socio": 2,
            "nome_socio": "WILSON BIANCARDI COURY",
            "cnpj_cpf_do_socio": "***414127**",
            "codigo_qualificacao_socio": 10,
            "qualificacao_socio": "Diretor",
            "data_entrada_sociedade": "2019-06-18",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 8,
            "faixa_etaria": "Entre 71 a 80 anos"
        },
        {
            "identificador_de_socio": 2,
            "nome_socio": "GILENO GURJAO BARRETO",
            "cnpj_cpf_do_socio": "***099595**",
            "codigo_qualificacao_socio": 16,
            "qualificacao_socio": "Presidente",
            "data_entrada_sociedade": "2020-02-03",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 5,
            "faixa_etaria": "Entre 41 a 50 anos"
        },
        {
            "identificador_de_socio": 2,
            "nome_socio": "RICARDO CEZAR DE MOURA JUCA",
            "cnpj_cpf_do_socio": "***989951**",
            "codigo_qualificacao_socio": 10,
            "qualificacao_socio": "Diretor",
            "data_entrada_sociedade": "2020-05-12",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 5,
            "faixa_etaria": "Entre 41 a 50 anos"
        },
        {
            "identificador_de_socio": 2,
            "nome_socio": "ANTONINO DOS SANTOS GUERRA NETO",
            "cnpj_cpf_do_socio": "***073447**",
            "codigo_qualificacao_socio": 5,
            "qualificacao_socio": "Administrador",
            "data_entrada_sociedade": "2019-02-11",
            "codigo_pais": null,
            "pais": null,
            "cpf_representante_legal": "***000000**",
            "nome_representante_legal": "",
            "codigo_qualificacao_representante_legal": 0,
            "qualificacao_representante_legal": null,
            "codigo_faixa_etaria": 7,
            "faixa_etaria": "Entre 61 a 70 anos"
        }
    ],
    "cnaes_secundarios": [
        {
            "codigo": 6201501,
            "descricao": "Desenvolvimento de programas de computador sob encomenda"
        },
        {
            "codigo": 6202300,
            "descricao": "Desenvolvimento e licenciamento de programas de computador customizáveis"
        },
        {
            "codigo": 6203100,
            "descricao": "Desenvolvimento e licenciamento de programas de computador não-customizáveis"
        },
        {
            "codigo": 6209100,
            "descricao": "Suporte técnico, manutenção e outros serviços em tecnologia da informação"
        },
        {
            "codigo": 6311900,
            "descricao": "Tratamento de dados, provedores de serviços de aplicação e serviços de hospedagem na internet"
        }
    ]
}

Para mais detalhes sobre os dados, consulte o Dicionário de dados e a Sobre os dados.

Busca paginada

Aviso

Essa funcionalidade está em fase de testes e mudanças podem ocorrer nos parâmetros e estrutura da resposta até que uma implementação e um formato garanta os requisitos de performance.

A busca paginada aceita um ou mais desses parâmetros na URL:

Campo de busca	Descrição
`cnae_fiscal`	Código do CNAE fiscal
`cnae`	Busca o código tanto no CNAE fiscal como nos CNAES secundários
`cnpf`	Busca por CPF ou CNPJ da pessoa no quadro societário, ver detalhes sobre a formatação
`municipio`	Código do município (apenas números) pelo IBGE ou SIAFI
`natureza_juridica`	Código da natureza jurídica
`uf`	Sigla da UF com duas letras

Configurações	Descrição
`limit`	Número máximo de CNPJ por página (o máximo é 1.000)
`cursor`	Valor a ser passado para requisitar a próxima página da busca

Por exemplo, a empresa do JSON anterior pode ser encontrada (bem como outras semelhantes) com: GET /?uf=DF&cnae=6209100.

Dica

Mais de um valor pode ser passado, seja repetindo o parâmetro, seja separando os valores por vírgulas. Por exemplo, para buscas no Rio Grande do Norte, Paraíba e Pernambuco, todas essas são opções válidas:

GET /?uf=rn&uf=pb&uf=pe
GET /?uf=rn,pb,pe
GET /?uf=rn,pb&uf=pe

O mesmo vale para todos os campos de busca.

Busca por CPF ou CNPJ da pessoa no quadro societário

Importante

Não utilizar pontuação ou barras nesses valores.

Para buscar por CPF, utilizar * como os três primeiros caracteres e como os dois últimos. Por exemplo, para buscar pelo CPF 123.456.789-01, utilizar ***456789** — é assim que o CPF dos sócios aparece no banco de dados original.

Dica

Buscar apenas por CNPJ ou CPF do quadro societário tende a não funcionar (erro de tempo esgotado, timeout). Afunilar a busca acrescentando uma UF tende a ajudar.

Exemplo de JSON de resposta:

{"data": […], "cursor": "42"}

Data

data contém uma sequência de JSON como o do exemplo para uma única empresa.

Cursor

Com uma resposta dessas do exemplo, para requisitar a próxima página, basta adicionar &cursor=33683111000280 ao final da URL.

Quando a resposta estiver sem cursor, isso significa que é a última página da busca.

API de grafos

Para consultar as relações de uma empresa ou de uma pessoa física, use GET /<id>, sendo que o valor de id é o CNPJ para pessoas jurídicas, ou um hash para as demais.

A partir de então navegue no grafo com mais requisições para /<id> para saber em quais outros quadro societários essa pessoa (física ou jurídica) está.

Para descobrir a menor conexão entre duas pessoas físicas ou jurídicas, use GET /<id1>/<id2>. A busca dura no máximo 90 segundos; caso, nesse intervalo, nenhuma conexão seja encontrada, isso não significa que nenhuma conexão é possível.

Exemplos

Exemplo de resposta para GET /33683111000280

[
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "3573de271293797f2abddc036be8f35e",
    "nome": "ALEXANDRE BRANDAO HENRIQUES MAIMONI",
    "cpf": "***641988**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "70ec112375aec9de541ae0b7c54d7cac",
    "nome": "ANDRE PICOLI AGATTE",
    "cpf": "***035378**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "5581a696ef726dcb05b563690e9d3ced",
    "nome": "ARIADNE DE SANTA TERESA LOPES FONSECA",
    "cpf": "***077170**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "76677f4091254d210276fc0febfb97a0",
    "nome": "ERMES FERREIRA COSTA NETO",
    "cpf": "***269764**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "40089c4776191cc8e870d14f2f431477",
    "nome": "OSMAR QUIRINO DA SILVA",
    "cpf": "***109571**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "3d988b184dcd37bc88e9766af21cf25f",
    "nome": "WALLYSON LEMOS DOS REIS OLIVEIRA",
    "cpf": "***286423**"
  },
  {
    "cnpj": "33683111000280",
    "razao_social": "SERVICO FEDERAL DE PROCESSAMENTO DE DADOS (SERPRO)",
    "id": "79292eb5f29feca8f3434e6f44b2f4a4",
    "nome": "WILTON ITAIGUARA GONCALVES MOTA",
    "cpf": "***623503**"
  }
]

Exemplo de resposta para GET /34712359000103/27516314000106

[
  {
    "cnpj": "34712359000103",
    "razao_social": "INSTITUTO DE ACAO CONSERVADORA",
    "id": "c23aa26674515674f7738d6b68c37d6d",
    "nome": "HELOISA WOLF BOLSONARO",
    "cpf": "***791930**"
  },
  {
    "cnpj": "46053446000185",
    "razao_social": "H&E PRODUCOES LTDA",
    "id": "c23aa26674515674f7738d6b68c37d6d",
    "nome": "HELOISA WOLF BOLSONARO",
    "cpf": "***791930**"
  },
  {
    "cnpj": "46053446000185",
    "razao_social": "H&E PRODUCOES LTDA",
    "id": "1defe1dc76aa2a3d5533a0cf1d444fa1",
    "nome": "EDUARDO NANTES BOLSONARO",
    "cpf": "***553657**"
  },
  {
    "cnpj": "27516314000106",
    "razao_social": "BOLSONARO DIGITAL LTDA",
    "id": "1defe1dc76aa2a3d5533a0cf1d444fa1",
    "nome": "EDUARDO NANTES BOLSONARO",
    "cpf": "***553657**"
  }
]

Um aplicativo experimental construído com essa API, também utilizando código aberto, é o Meu Garfo

Endpoints auxiliares

Ambas as APIs oferecem esses endpoints, para os quais a resposta esperada é com status 200:

Caminho da URL	Tipo de requisição	Conteúdo esperado na resposta
`/updated`	`GET`	JSON contendo a data de extração dos dados pela Receita Federal.
`/healthz`	`GET` ou `HEAD`	Resposta sem conteúdo
`/metrics`	`GET`	Métricas do Prometheus para consumo.

Como usar

API principal

Exemplos

Exemplo de requisição usando o curl

Exemplo de resposta válida

Busca paginada

Busca por CPF ou CNPJ da pessoa no quadro societário

Exemplo de JSON de resposta:

Data

Cursor

API de grafos

Exemplos

Endpoints auxiliares

Exemplo de requisição usando o `curl`