{"openapi":"3.1.0","info":{"title":"CNPJ-XRay — Consulta CNPJ","description":"API de consulta ao CNPJ compatível com a Consulta CNPJ v2 do SERPRO: mesmos\ncaminhos, mesmos nomes de campo, mesmos códigos de retorno.\n\n**Duas diferenças que nenhuma implementação fecha**, porque são da fonte e não\ndo código:\n\n* o **CPF dos sócios vem mascarado** — a Receita publica `***794780**` nos\n  dados abertos; o SERPRO, como canal autorizado, devolve completo;\n* a base é um **retrato mensal**, não tempo real. Uma empresa aberta ontem não\n  está aqui, e uma baixa da semana passada ainda aparece ativa.\n","version":"2.0"},"paths":{"/saude":{"get":{"tags":["operação"],"summary":"Estado do pod e competência dos dados servidos","description":"**Não faz parte do contrato do SERPRO** — é nossa, e fica fora de `/v2/` para não colidir com nenhum caminho futuro deles.\n\nSem autenticação: serve de sonda de vivacidade, e a competência não é informação sensível — é o oposto, quem consome precisa dela para saber a idade do dado.","operationId":"saude_saude_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Saude"}}}}}}},"/token":{"post":{"tags":["autenticação"],"summary":"Emite o token de acesso","description":"OAuth2 `client_credentials`. Envie `Authorization: Basic base64(ConsumerKey:ConsumerSecret)` e `grant_type=client_credentials`.","operationId":"emitir_token_token_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Token"}}}},"401":{"description":"Houve falha na autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}},"security":[{"HTTPBasic":[]}]}},"/v2/basica/{ni}":{"get":{"tags":["consulta"],"summary":"Dados cadastrais, sem o quadro societário","description":"Equivale ao `/v2/basica/{ni}` do SERPRO. `ni` é o CNPJ com 14 dígitos.","operationId":"basica_v2_basica__ni__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ni","in":"path","required":true,"schema":{"type":"string","title":"Ni"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Basica"}}}},"400":{"description":"O número de CNPJ informado não é válido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Houve falha na autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Acesso negado — inclusive quota mensal excedida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Nenhum registro encontrado para o CNPJ informado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Ocorreu um erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/v2/qsa/{ni}":{"get":{"tags":["consulta"],"summary":"Quadro de sócios e administradores","description":"Equivale ao `/v2/qsa/{ni}` do SERPRO. O CPF dos sócios vem mascarado. `ni` é o CNPJ com 14 dígitos.","operationId":"qsa_v2_qsa__ni__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ni","in":"path","required":true,"schema":{"type":"string","title":"Ni"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QSA"}}}},"400":{"description":"O número de CNPJ informado não é válido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Houve falha na autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Acesso negado — inclusive quota mensal excedida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Nenhum registro encontrado para o CNPJ informado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Ocorreu um erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/v2/empresa/{ni}":{"get":{"tags":["consulta"],"summary":"Dados cadastrais e quadro societário","description":"Equivale ao `/v2/empresa/{ni}` do SERPRO. `ni` é o CNPJ com 14 dígitos.","operationId":"empresa_v2_empresa__ni__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"ni","in":"path","required":true,"schema":{"type":"string","title":"Ni"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Empresa"}}}},"400":{"description":"O número de CNPJ informado não é válido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"401":{"description":"Houve falha na autenticação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"403":{"description":"Acesso negado — inclusive quota mensal excedida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"404":{"description":"Nenhum registro encontrado para o CNPJ informado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Ocorreu um erro interno inesperado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}},"components":{"schemas":{"Basica":{"properties":{"ni":{"type":"string","title":"Ni","examples":["11222333000181"]},"tipoEstabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipoestabelecimento","examples":["1"]},"nomeEmpresarial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nomeempresarial","examples":["ACME LTDA"]},"nomeFantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nomefantasia","examples":["ACME"]},"dataAbertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataabertura","examples":["2010-03-01"]},"situacaoCadastral":{"anyOf":[{"$ref":"#/components/schemas/SituacaoCadastral"},{"type":"null"}]},"naturezaJuridica":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"dataSituacaoEspecial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datasituacaoespecial"},"situacaoEspecial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacaoespecial"},"capitalSocial":{"type":"integer","title":"Capitalsocial","description":"Inteiro em CENTAVOS, como no SERPRO. 123456 são R$ 1.234,56.","default":0,"examples":[123456]},"porte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Porte","examples":["03"]},"endereco":{"anyOf":[{"$ref":"#/components/schemas/Endereco"},{"type":"null"}]},"telefone":{"items":{"$ref":"#/components/schemas/Telefone"},"type":"array","title":"Telefone"},"correioEletronico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correioeletronico"},"cnaePrincipal":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"cnaeSecundarias":{"items":{"$ref":"#/components/schemas/Dominio"},"type":"array","title":"Cnaesecundarias"},"informacoesAdicionais":{"anyOf":[{"$ref":"#/components/schemas/InformacoesAdicionais"},{"type":"null"}]}},"type":"object","required":["ni"],"title":"Basica"},"Dominio":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","examples":["2062"]},"descricao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Descricao","examples":["Sociedade Empresária Limitada"]}},"type":"object","title":"Dominio","description":"Par código/descrição das tabelas de domínio.\n\n`descricao` pode vir nula com código presente: a base tem código órfão real\n— 18.253 só em `motivo_situacao_cadastral` — e o JOIN é LEFT para a linha\nnão sumir por causa disso."},"Empresa":{"properties":{"ni":{"type":"string","title":"Ni","examples":["11222333000181"]},"tipoEstabelecimento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipoestabelecimento","examples":["1"]},"nomeEmpresarial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nomeempresarial","examples":["ACME LTDA"]},"nomeFantasia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nomefantasia","examples":["ACME"]},"dataAbertura":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataabertura","examples":["2010-03-01"]},"situacaoCadastral":{"anyOf":[{"$ref":"#/components/schemas/SituacaoCadastral"},{"type":"null"}]},"naturezaJuridica":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"dataSituacaoEspecial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datasituacaoespecial"},"situacaoEspecial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Situacaoespecial"},"capitalSocial":{"type":"integer","title":"Capitalsocial","description":"Inteiro em CENTAVOS, como no SERPRO. 123456 são R$ 1.234,56.","default":0,"examples":[123456]},"porte":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Porte","examples":["03"]},"endereco":{"anyOf":[{"$ref":"#/components/schemas/Endereco"},{"type":"null"}]},"telefone":{"items":{"$ref":"#/components/schemas/Telefone"},"type":"array","title":"Telefone"},"correioEletronico":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Correioeletronico"},"cnaePrincipal":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"cnaeSecundarias":{"items":{"$ref":"#/components/schemas/Dominio"},"type":"array","title":"Cnaesecundarias"},"informacoesAdicionais":{"anyOf":[{"$ref":"#/components/schemas/InformacoesAdicionais"},{"type":"null"}]},"socios":{"items":{"$ref":"#/components/schemas/Socio"},"type":"array","title":"Socios"}},"type":"object","required":["ni"],"title":"Empresa"},"Endereco":{"properties":{"tipoLogradouro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tipologradouro","examples":["RUA"]},"logradouro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logradouro","examples":["DAS FLORES"]},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","examples":["100"]},"complemento":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Complemento"},"cep":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cep","examples":["01001000"]},"bairro":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bairro","examples":["CENTRO"]},"uf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Uf","examples":["SP"]},"municipio":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"pais":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"municipioJurisdicao":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}],"description":"Sempre nulo: o município de jurisdição fiscal não existe nos dados abertos da Receita."}},"type":"object","title":"Endereco"},"Erro":{"properties":{"message":{"type":"string","title":"Message","examples":["O número de CNPJ informado não é válido"]}},"type":"object","required":["message"],"title":"Erro"},"InformacoesAdicionais":{"properties":{"optanteSimples":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Optantesimples","examples":["S"]},"optanteMei":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Optantemei","examples":["N"]},"listaPeriodosSimples":{"items":{"$ref":"#/components/schemas/PeriodoSimples"},"type":"array","title":"Listaperiodossimples","description":"O SERPRO devolve o histórico de períodos; a Receita publica um par opção/exclusão apenas, então esta lista tem no máximo um elemento."}},"type":"object","title":"InformacoesAdicionais"},"PeriodoSimples":{"properties":{"dataInicio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datainicio","examples":["2010-04-01"]},"dataFim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datafim"}},"type":"object","title":"PeriodoSimples"},"QSA":{"properties":{"ni":{"type":"string","title":"Ni","examples":["11222333000181"]},"nomeEmpresarial":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nomeempresarial"},"socios":{"items":{"$ref":"#/components/schemas/Socio"},"type":"array","title":"Socios"}},"type":"object","required":["ni"],"title":"QSA"},"RepresentanteLegal":{"properties":{"cpf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpf"},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome"},"qualificacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao"}},"type":"object","title":"RepresentanteLegal"},"Saude":{"properties":{"status":{"type":"string","title":"Status","examples":["ok"]},"competencia":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Competencia","description":"Competência da Receita de onde vieram os dados. Nula em base construída antes de a proveniência existir.","examples":["2026-09"]},"construidaEm":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Construidaem","description":"Quando a base foi construída — distinto da competência: recarregar uma competência antiga produz arquivo novo com dado velho.","examples":["2026-09-17T16:00:00+00:00"]},"linhas":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Linhas"},"baseSomenteLeitura":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Basesomenteleitura"}},"type":"object","required":["status"],"title":"Saude","description":"Estado do pod e **proveniência do dado que ele está servindo**.\n\nO `competencia` é o campo que importa. Sem ele, um consumidor que receba\numa resposta não tem como saber se o dado é de setembro ou de março — e a\ndiferença aparece justamente onde dói: uma CNAE que saiu do cadastro, uma\nbaixa que ainda não entrou."},"SituacaoCadastral":{"properties":{"codigo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Codigo","examples":["02"]},"data":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data","examples":["2020-05-10"]},"motivo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Motivo"}},"type":"object","title":"SituacaoCadastral"},"Socio":{"properties":{"tipoSocio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tiposocio","examples":["2"]},"cpf":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cpf","description":"MASCARADO. A Receita publica o CPF parcialmente oculto nos dados abertos; o SERPRO, como canal autorizado, devolve completo. Mesmo campo, conteúdo diferente.","examples":["***794780**"]},"nome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nome","examples":["MARIA DA SILVA"]},"qualificacao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualificacao","examples":["49"]},"dataInclusao":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datainclusao","examples":["2010-03-01"]},"pais":{"anyOf":[{"$ref":"#/components/schemas/Dominio"},{"type":"null"}]},"representanteLegal":{"anyOf":[{"$ref":"#/components/schemas/RepresentanteLegal"},{"type":"null"}]}},"type":"object","title":"Socio"},"Telefone":{"properties":{"ddd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ddd","examples":["11"]},"numero":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Numero","examples":["30001000"]}},"type":"object","title":"Telefone"},"Token":{"properties":{"access_token":{"type":"string","title":"Access Token"},"token_type":{"type":"string","title":"Token Type","default":"Bearer","examples":["Bearer"]},"expires_in":{"type":"integer","title":"Expires In","examples":[3600]},"scope":{"type":"string","title":"Scope","default":"default","examples":["default"]}},"type":"object","required":["access_token","expires_in"],"title":"Token"}},"securitySchemes":{"HTTPBasic":{"type":"http","description":"Consumer Key e Consumer Secret","scheme":"basic"},"HTTPBearer":{"type":"http","description":"Token obtido em POST /token","scheme":"bearer"}}}}