{ "openapi": "3.1.0", "info": { "title": "EvoDATA API", "version": "1.0.0", "summary": "Cadastro público de CNPJ da Receita Federal em JSON.", "description": "Busca por filtros combináveis, ficha completa de estabelecimento, consulta a pessoas físicas e tabelas de referência.\n\n**Dois regimes de acesso.** Os recursos de empresa e as tabelas de referência são públicos e não autenticados, classificados pelo endereço IP, com teto de 20 requisições por minuto. Os recursos de pessoa física exigem chave de API e conta em plano pago, e sobem para 120 requisições por minuto.\n\nA chave é emitida no painel, em Chaves de API, e enviada no cabeçalho `Authorization: Bearer `.", "contact": { "name": "EvoDATA", "url": "https://evodata.app/api/docs" } }, "servers": [ { "url": "https://evodata.app/api/v1" } ], "tags": [ { "name": "Empresas", "description": "Consulta ao cadastro de CNPJ. Público." }, { "name": "Pessoas", "description": "Consulta a pessoas físicas. Exige chave e plano pago." }, { "name": "Referências", "description": "Tabelas auxiliares para montar filtros. Público." } ], "paths": { "/empresas": { "get": { "tags": [ "Empresas" ], "operationId": "buscarEmpresas", "summary": "Busca paginada de estabelecimentos", "description": "Ao menos um filtro é obrigatório. O parâmetro `situacao` tem padrão `02` e não satisfaz sozinho essa exigência.\n\nFiltros de domínio fechado descartam em silêncio valores desconhecidos, em vez de devolver erro.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Termo sobre razão social ou nome fantasia, conforme buscar_em. Valor só com dígitos e 8+ deles é reinterpretado como cnpj.", "schema": { "type": "string" }, "example": "padaria" }, { "name": "buscar_em", "in": "query", "required": false, "description": "Campo onde o termo incide.", "schema": { "type": "string", "enum": [ "razao", "fantasia", "ambos" ], "default": "razao" } }, { "name": "cnpj", "in": "query", "required": false, "description": "CNPJ completo ou raiz. Pontuação ignorada. Tem precedência sobre q.", "schema": { "type": "string" }, "example": "62170939000151" }, { "name": "uf", "in": "query", "required": false, "description": "Siglas de estado.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "DF", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "EX" ] } } ] }, "example": "SP,RJ" }, { "name": "municipio", "in": "query", "required": false, "description": "Códigos de município da Receita, não o nome.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "example": "7107" }, { "name": "bairro", "in": "query", "required": false, "description": "Nome do bairro, casamento por prefixo.", "schema": { "type": "string" }, "example": "Centro" }, { "name": "cep", "in": "query", "required": false, "description": "Prefixo de CEP; só dígitos contam.", "schema": { "type": "string" }, "example": "01310" }, { "name": "cnae", "in": "query", "required": false, "description": "Códigos CNAE de 7 dígitos.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "example": "4721102" }, { "name": "cnae_secundario", "in": "query", "required": false, "description": "Casa também no CNAE secundário, não só no principal.", "schema": { "type": "boolean" } }, { "name": "natureza", "in": "query", "required": false, "description": "Códigos de natureza jurídica.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "example": "2135" }, { "name": "situacao", "in": "query", "required": false, "description": "Códigos de situação cadastral. Padrão 02 (ativa).", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "enum": [ "01", "02", "03", "04", "08" ] } } ] }, "example": "02,08" }, { "name": "matriz_filial", "in": "query", "required": false, "description": "Restringe a matrizes ou filiais. Ausente traz ambas.", "schema": { "type": "string", "enum": [ 1, 2 ] } }, { "name": "porte", "in": "query", "required": false, "description": "Códigos de porte declarado.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "enum": [ "00", "01", "03", "05" ] } } ] }, "example": "01,03" }, { "name": "abertura_de", "in": "query", "required": false, "description": "Data de abertura mínima.", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "abertura_ate", "in": "query", "required": false, "description": "Data de abertura máxima.", "schema": { "type": "string", "format": "date" }, "example": "2025-12-31" }, { "name": "capital_min", "in": "query", "required": false, "description": "Capital social mínimo.", "schema": { "type": "number", "description": "Aceita \"1500.50\" e \"1.500,50\"." }, "example": 10000 }, { "name": "capital_max", "in": "query", "required": false, "description": "Capital social máximo.", "schema": { "type": "number", "description": "Aceita \"1500.50\" e \"1.500,50\"." }, "example": 5000000 }, { "name": "mei", "in": "query", "required": false, "description": "Ternário: 1 só MEI, 0 exclui MEI, ausente é indiferente.", "schema": { "type": "string", "enum": [ "1", "0", "true", "false", "S", "N" ] } }, { "name": "simples", "in": "query", "required": false, "description": "Ternário: 1 só optantes, 0 exclui, ausente é indiferente.", "schema": { "type": "string", "enum": [ "1", "0", "true", "false", "S", "N" ] } }, { "name": "com_email", "in": "query", "required": false, "description": "Somente com e-mail preenchido.", "schema": { "type": "boolean" } }, { "name": "com_telefone", "in": "query", "required": false, "description": "Somente com telefone preenchido.", "schema": { "type": "boolean" } }, { "name": "com_celular", "in": "query", "required": false, "description": "Somente com telefone identificado como celular.", "schema": { "type": "boolean" } }, { "name": "com_geo", "in": "query", "required": false, "description": "Somente com coordenadas resolvidas.", "schema": { "type": "boolean" } }, { "name": "funcionarios_min", "in": "query", "required": false, "description": "Funcionários estimados, mínimo. Dado de enriquecimento.", "schema": { "type": "integer" }, "example": 10 }, { "name": "funcionarios_max", "in": "query", "required": false, "description": "Funcionários estimados, máximo. Dado de enriquecimento.", "schema": { "type": "integer" }, "example": 500 }, { "name": "size_class", "in": "query", "required": false, "description": "Classe de tamanho estimada.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "enum": [ "micro", "pequena", "media", "grande" ] } } ] }, "example": "media,grande" }, { "name": "rating_min", "in": "query", "required": false, "description": "Avaliação mínima no Google Places, 0 a 5.", "schema": { "type": "number", "description": "Aceita \"1500.50\" e \"1.500,50\"." }, "example": 4 }, { "name": "ordenar", "in": "query", "required": false, "description": "Ordenação desejada. Pode ser recusada em conjuntos grandes — nesse caso a resposta segue 200 e traz a explicação em avisos.", "schema": { "type": "string", "enum": [ "relevancia", "abertura_desc", "abertura_asc", "capital_desc", "razao_asc" ], "default": "relevancia" } }, { "name": "pagina", "in": "query", "required": false, "description": "Página, começando em 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Página de resultados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespostaBusca" } } } }, "422": { "$ref": "#/components/responses/FiltrosAusentes" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "503": { "$ref": "#/components/responses/ConsultaExpirada" } } } }, "/empresas/lote": { "post": { "tags": [ "Empresas" ], "operationId": "obterEmpresasEmLote", "summary": "Extração em lote de estabelecimentos", "description": "Resolve até `max_itens_lote` CNPJs numa única chamada. Cada item é tratado como uma chamada independente a `/empresas/{cnpj}` — inválido, não encontrado e sem crédito são erros por item, dentro de `resultados`, e nunca derrubam a resposta como um todo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoteEmpresasRequisicao" } } } }, "responses": { "200": { "description": "Lote processado. Verifique cada item de `resultados` individualmente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoteEmpresasResposta" } } } }, "422": { "$ref": "#/components/responses/LoteInvalido" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/empresas/{cnpj}": { "get": { "tags": [ "Empresas" ], "operationId": "obterEmpresa", "summary": "Ficha completa de um estabelecimento", "description": "Aceita CNPJ com ou sem máscara. Os dígitos verificadores são conferidos antes de qualquer consulta ao banco.", "parameters": [ { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9.\\-\\/]{14,18}$" }, "example": "62.170.939/0001-51" } ], "responses": { "200": { "description": "Estabelecimento encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dados" ], "properties": { "dados": { "$ref": "#/components/schemas/EmpresaFicha" } } } } } }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "422": { "$ref": "#/components/responses/CnpjInvalido" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/pessoas": { "get": { "tags": [ "Pessoas" ], "operationId": "buscarPessoas", "summary": "Busca de pessoas físicas", "security": [ { "chaveApi": [] } ], "description": "Exige chave de API e conta em plano pago.\n\nAo menos um filtro é obrigatório. O CPF sempre volta mascarado — a busca por CPF confirma uma identidade que o cliente já possui, não permite varrer identidades.\n\n**Dois filtros são recusados de propósito**, com 422 `filtro_nao_suportado`: CPF parcial e domínio de e-mail (`@provedor.com`). Nenhum índice cobre esses casos sobre centenas de milhões de linhas, e aceitá-los devolveria resultado plausível e errado, ou nenhum resultado depois do tempo limite.", "parameters": [ { "name": "nome", "in": "query", "required": false, "description": "Início do nome, sem acento. Casa por prefixo.", "schema": { "type": "string" }, "example": "MARIA DA SILVA" }, { "name": "nome_mae", "in": "query", "required": false, "description": "Início do nome da mãe. Casa por prefixo.", "schema": { "type": "string" }, "example": "ANA" }, { "name": "cpf", "in": "query", "required": false, "description": "CPF completo, 11 dígitos. Pontuação ignorada. Parcial é recusado.", "schema": { "type": "string" }, "example": "00000000191" }, { "name": "rg", "in": "query", "required": false, "description": "Número de RG, igualdade exata.", "schema": { "type": "string" } }, { "name": "titulo_eleitor", "in": "query", "required": false, "description": "Título de eleitor, só dígitos.", "schema": { "type": "integer" } }, { "name": "pis", "in": "query", "required": false, "description": "PIS/NIT, só dígitos.", "schema": { "type": "integer" } }, { "name": "sexo", "in": "query", "required": false, "description": "Sexo.", "schema": { "type": "string", "enum": [ "M", "F" ] } }, { "name": "estado_civil", "in": "query", "required": false, "description": "Estado civil.", "schema": { "type": "string", "enum": [ "S", "C", "D", "V", "O" ] } }, { "name": "nasc_de", "in": "query", "required": false, "description": "Nascimento mínimo.", "schema": { "type": "string", "format": "date" }, "example": "1980-01-01" }, { "name": "nasc_ate", "in": "query", "required": false, "description": "Nascimento máximo.", "schema": { "type": "string", "format": "date" }, "example": "1990-12-31" }, { "name": "cbo", "in": "query", "required": false, "description": "Código de ocupação, casa por prefixo.", "schema": { "type": "string" }, "example": "2521" }, { "name": "uf", "in": "query", "required": false, "description": "Estado do endereço.", "schema": { "type": "string", "enum": [ "AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO", "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR", "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO" ] }, "example": "SP" }, { "name": "cidade", "in": "query", "required": false, "description": "Cidade do endereço, sem acento e por prefixo.", "schema": { "type": "string" }, "example": "SAO PAULO" }, { "name": "bairro", "in": "query", "required": false, "description": "Bairro, por prefixo.", "schema": { "type": "string" }, "example": "CENTRO" }, { "name": "logradouro", "in": "query", "required": false, "description": "Nome do logradouro, sem \"Rua\"/\"Av\".", "schema": { "type": "string" }, "example": "PAULISTA" }, { "name": "cep", "in": "query", "required": false, "description": "CEP completo, 8 dígitos.", "schema": { "type": "string" }, "example": "01310100" }, { "name": "uf_emissao", "in": "query", "required": false, "description": "UF de emissão do RG.", "schema": { "type": "string", "enum": [ "AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO", "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR", "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO" ] } }, { "name": "email", "in": "query", "required": false, "description": "E-mail completo ou o começo dele. Domínio sozinho é recusado.", "schema": { "type": "string" }, "example": "joao@" }, { "name": "ddd", "in": "query", "required": false, "description": "DDD do telefone.", "schema": { "type": "integer", "minimum": 11, "maximum": 99 }, "example": 11 }, { "name": "telefone", "in": "query", "required": false, "description": "Telefone completo, só dígitos.", "schema": { "type": "integer" } }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens retornados.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Pessoas encontradas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespostaPessoas" } } } }, "401": { "$ref": "#/components/responses/CredencialInvalida" }, "403": { "$ref": "#/components/responses/PlanoSemApi" }, "422": { "$ref": "#/components/responses/FiltroPessoaInvalido" }, "429": { "$ref": "#/components/responses/LimiteExcedido" }, "503": { "$ref": "#/components/responses/ConsultaExpirada" } } } }, "/pessoas/lote": { "post": { "tags": [ "Pessoas" ], "operationId": "obterPessoasEmLote", "summary": "Extração em lote de pessoas físicas", "security": [ { "chaveApi": [] } ], "description": "Exige chave de API e conta em plano pago. Resolve até `max_itens_lote` IDs internos numa única chamada. Cada item é tratado como uma chamada independente a `/pessoas/{id}` — inválido, não encontrado e sem crédito são erros por item, dentro de `resultados`, e nunca derrubam a resposta como um todo.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LotePessoasRequisicao" } } } }, "responses": { "200": { "description": "Lote processado. Verifique cada item de `resultados` individualmente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LotePessoasResposta" } } } }, "401": { "$ref": "#/components/responses/CredencialInvalida" }, "403": { "$ref": "#/components/responses/PlanoSemApi" }, "422": { "$ref": "#/components/responses/LoteInvalido" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/pessoas/{id}": { "get": { "tags": [ "Pessoas" ], "operationId": "obterPessoa", "summary": "Ficha completa de uma pessoa física", "security": [ { "chaveApi": [] } ], "description": "Exige chave de API e conta em plano pago. O `id` é o identificador interno devolvido pela busca — não é o CPF, que nunca sai em claro.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador interno, vindo do campo `id` da busca." } ], "responses": { "200": { "description": "Pessoa encontrada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/PessoaFicha" } } } } } }, "401": { "$ref": "#/components/responses/CredencialInvalida" }, "403": { "$ref": "#/components/responses/PlanoSemApi" }, "404": { "$ref": "#/components/responses/NaoEncontrado" }, "429": { "$ref": "#/components/responses/LimiteExcedido" } } } }, "/referencias/cnae": { "get": { "tags": [ "Referências" ], "operationId": "buscarCnae", "summary": "Busca CNAE por descrição", "description": "Termos com menos de 2 caracteres devolvem lista vazia com status 200.\n\nO `codigo` retorna como número, sem zero à esquerda; ao repassar para o filtro `cnae`, trate como texto de 7 posições.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2 }, "example": "padaria" } ], "responses": { "200": { "description": "Atividades correspondentes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "integer", "examples": [ 4721102 ] }, "descricao": { "type": "string" } } } } } } } } } } } }, "/referencias/municipios/{uf}": { "get": { "tags": [ "Referências" ], "operationId": "listarMunicipios", "summary": "Municípios de um estado", "description": "Devolve o código que o filtro `municipio` espera. A sigla não diferencia maiúsculas.", "parameters": [ { "name": "uf", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "AC", "AL", "AP", "AM", "BA", "CE", "DF", "ES", "GO", "MA", "MT", "MS", "MG", "PA", "PB", "PR", "PE", "PI", "RJ", "RN", "RS", "RO", "RR", "SC", "SP", "SE", "TO", "EX" ] }, "example": "DF" } ], "responses": { "200": { "description": "Municípios do estado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string" }, "nome": { "type": "string" } } } } } } } } }, "422": { "$ref": "#/components/responses/UfInvalida" } } } } }, "components": { "securitySchemes": { "chaveApi": { "type": "http", "scheme": "bearer", "description": "Chave emitida no painel. Restrita a administradores e a contas em plano pago; conta no plano gratuito recebe 403." } }, "schemas": { "Empresa": { "type": "object", "description": "Estabelecimento do cadastro de CNPJ. Campos de enriquecimento e de Google Places existem apenas para parte da base; espere null como caso comum.", "properties": { "cnpj": { "type": "string", "description": "14 dígitos, sem pontuação." }, "cnpj_formatado": { "type": "string", "description": "Com máscara 00.000.000/0000-00." }, "razao_social": { "type": "string", "description": "Razão social registrada." }, "nome_fantasia": { "type": [ "string", "null" ], "description": "Nome fantasia, quando declarado." }, "nome_exibicao": { "type": "string", "description": "Fantasia quando existe, senão razão social." }, "situacao": { "type": "string", "description": "Rótulo legível da situação cadastral." }, "situacao_codigo": { "type": "string", "enum": [ "01", "02", "03", "04", "08" ] }, "ativa": { "type": "boolean", "description": "Atalho para situacao_codigo === \"02\"." }, "tipo_unidade": { "type": "string", "description": "Matriz ou Filial." }, "cnae_codigo": { "type": "string", "description": "CNAE principal, 7 dígitos." }, "cnae": { "type": "string", "description": "Descrição do CNAE principal." }, "uf": { "type": "string", "description": "Sigla do estado." }, "municipio": { "type": "string", "description": "Nome do município." }, "bairro": { "type": [ "string", "null" ], "description": "Bairro." }, "cep": { "type": [ "string", "null" ], "description": "CEP com máscara." }, "endereco": { "type": "string", "description": "Logradouro, número e complemento." }, "telefone": { "type": [ "string", "null" ], "description": "Telefone principal formatado." }, "email": { "type": [ "string", "null" ], "description": "E-mail declarado à Receita." }, "porte": { "type": "string", "description": "Porte declarado, legível." }, "natureza": { "type": "string", "description": "Natureza jurídica, legível." }, "capital_social": { "type": "number", "description": "Capital social em reais." }, "abertura": { "type": [ "string", "null" ], "format": "date" }, "funcionarios": { "type": [ "integer", "null" ], "description": "Estimativa. Enriquecimento." }, "porte_estimado": { "type": [ "string", "null" ], "description": "Classe estimada. Enriquecimento." }, "faturamento_estimado": { "type": [ "number", "null" ], "description": "Estimativa. Enriquecimento." }, "confianca_estimativa": { "type": [ "string", "null" ], "description": "Confiança das estimativas. Enriquecimento." }, "latitude": { "type": [ "number", "null" ], "description": "Google Places." }, "longitude": { "type": [ "number", "null" ], "description": "Google Places." }, "avaliacao": { "type": [ "number", "null" ], "description": "Nota 0 a 5. Google Places." }, "avaliacoes_total": { "type": [ "integer", "null" ], "description": "Quantidade de avaliações. Google Places." }, "site": { "type": [ "string", "null" ], "description": "Site oficial. Google Places." } } }, "EmpresaFicha": { "allOf": [ { "$ref": "#/components/schemas/Empresa" }, { "type": "object", "properties": { "cnpj_basico": { "type": "string", "description": "Raiz de 8 dígitos, comum a todas as unidades." }, "situacao_desde": { "type": [ "string", "null" ], "format": "date" }, "situacao_especial": { "type": [ "string", "null" ], "description": "Situação especial, quando houver." }, "telefone_secundario": { "type": [ "string", "null" ], "description": "Segundo telefone declarado." }, "cnaes_secundarios": { "type": "array", "items": { "type": "object", "properties": { "codigo": { "type": "string" }, "descricao": { "type": "string" } } } }, "simples": { "$ref": "#/components/schemas/Simples" }, "socios": { "type": "array", "items": { "$ref": "#/components/schemas/Socio" } }, "unidades": { "type": "array", "items": { "$ref": "#/components/schemas/Unidade" } } } } ] }, "Simples": { "type": [ "object", "null" ], "properties": { "optante": { "type": "boolean", "description": "Optante pelo Simples Nacional." }, "desde": { "type": [ "string", "null" ], "format": "date" }, "excluido_em": { "type": [ "string", "null" ], "format": "date" }, "mei": { "type": "boolean", "description": "Enquadrado como MEI." }, "mei_desde": { "type": [ "string", "null" ], "format": "date" }, "mei_excluido_em": { "type": [ "string", "null" ], "format": "date" } } }, "Socio": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome do sócio ou razão social." }, "documento": { "type": "string", "description": "CNPJ formatado para PJ; CPF mascarado como ***.456.789-** para PF. A Receita publica o CPF já parcial e não há como recompô-lo." }, "tipo": { "type": "string", "enum": [ "Pessoa jurídica", "Pessoa física", "Estrangeiro" ] }, "eh_pessoa_juridica": { "type": "boolean", "description": "Verdadeiro quando o sócio é PJ." }, "qualificacao": { "type": "string", "description": "Qualificação societária, legível." }, "entrada": { "type": [ "string", "null" ], "format": "date" }, "faixa_etaria": { "type": [ "string", "null" ], "description": "Faixa etária, quando informada." }, "representante": { "type": [ "string", "null" ], "description": "Representante legal, quando houver." } } }, "Unidade": { "type": "object", "description": "Unidade que compartilha a mesma raiz de CNPJ, incluindo a consultada.", "properties": { "cnpj": { "type": "string", "description": "14 dígitos." }, "cnpj_formatado": { "type": "string", "description": "Com máscara." }, "nome_fantasia": { "type": [ "string", "null" ], "description": "Nome fantasia." }, "tipo": { "type": "string", "description": "Matriz ou Filial." }, "eh_matriz": { "type": "boolean", "description": "Verdadeiro para a matriz." }, "situacao": { "type": "string", "description": "Situação cadastral, legível." }, "ativa": { "type": "boolean", "description": "Situação é ativa." }, "uf": { "type": "string", "description": "Sigla do estado." }, "municipio": { "type": "string", "description": "Nome do município." }, "cnae": { "type": "string", "description": "Descrição do CNAE principal." }, "abertura": { "type": [ "string", "null" ], "format": "date" } } }, "RespostaBusca": { "type": "object", "required": [ "dados", "paginacao", "avisos" ], "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Empresa" } }, "paginacao": { "$ref": "#/components/schemas/Paginacao" }, "avisos": { "type": "array", "items": { "type": "string" }, "description": "Mensagens sobre a consulta que não impedem a resposta. Hoje só é preenchido quando a ordenação pedida foi recusada." } } }, "Paginacao": { "type": "object", "properties": { "pagina": { "type": "integer", "description": "Página corrente." }, "por_pagina": { "type": "integer", "description": "Itens nesta página." }, "total": { "type": "integer", "description": "Total de resultados. Ver total_exato antes de usar." }, "total_exato": { "type": "boolean", "description": "Falso significa que total é a estimativa do planejador do PostgreSQL, não uma contagem: acima de 5.000 resultados contar de verdade levaria minutos. Trate como ordem de grandeza." }, "tem_proxima": { "type": "boolean", "description": "Existe página seguinte." } } }, "LoteEmpresasRequisicao": { "type": "object", "required": [ "cnpjs" ], "properties": { "cnpjs": { "type": "array", "description": "CNPJs com ou sem máscara, até o limite do lote.", "minItems": 1, "maxItems": 100, "items": { "type": "string" }, "example": [ "62.170.939/0001-51", "11222333000181" ] } } }, "LoteEmpresasResposta": { "type": "object", "required": [ "resultados", "resumo" ], "properties": { "resultados": { "type": "array", "items": { "type": "object", "required": [ "cnpj" ], "description": "Um item por CNPJ enviado, na mesma ordem. Ou traz `dados` (sucesso), ou `erro`+`mensagem` (falha isolada deste item).", "properties": { "cnpj": { "type": [ "string", "null" ], "description": "Dígitos do CNPJ, ou null quando o item enviado não era sequer um texto/número." }, "dados": { "$ref": "#/components/schemas/EmpresaFicha" }, "cobranca": { "type": "object", "description": "Ausente quando a chamada é anônima — visitante não tem carteira e a ficha segue livre.", "properties": { "creditos": { "type": "integer", "description": "Créditos debitados por este item. 0 quando já paga." }, "ja_paga_na_competencia": { "type": "boolean", "description": "A ficha já havia sido cobrada neste mês." } } }, "erro": { "type": "string", "enum": [ "cnpj_invalido", "nao_encontrado", "creditos_insuficientes" ] }, "mensagem": { "type": "string", "description": "Texto em português. Não compare por ela." } } } }, "resumo": { "type": "object", "properties": { "total": { "type": "integer", "description": "Itens enviados no lote." }, "sucesso": { "type": "integer", "description": "Itens resolvidos com dados." }, "creditos_debitados": { "type": "integer", "description": "Soma dos créditos debitados no lote. Ausente em chamada anônima." }, "saldo": { "type": "integer", "description": "Saldo de créditos após o lote. Ausente em chamada anônima." } } } } }, "Pessoa": { "type": "object", "description": "Linha da busca de pessoas. O CPF é sempre mascarado.", "properties": { "id": { "type": "integer", "description": "Identificador interno; use-o em /pessoas/{id}." }, "nome": { "type": [ "string", "null" ], "description": "Nome completo." }, "cpf": { "type": "string", "description": "CPF mascarado no formato ***.XXX.XXX-**. O número completo não é exposto por nenhum endpoint." }, "nome_mae": { "type": [ "string", "null" ], "description": "Nome da mãe." }, "sexo": { "type": [ "string", "null" ], "description": "Código M ou F." }, "sexo_descricao": { "type": [ "string", "null" ], "description": "Rótulo legível." }, "nascimento": { "type": [ "string", "null" ], "format": "date" }, "idade": { "type": [ "integer", "null" ], "description": "Idade calculada na data da consulta." }, "estado_civil": { "type": [ "string", "null" ], "description": "Código de estado civil." }, "estado_civil_descricao": { "type": [ "string", "null" ], "description": "Rótulo legível." }, "cbo": { "type": [ "string", "null" ], "description": "Código de ocupação." }, "cidade": { "type": [ "string", "null" ], "description": "Cidade de um endereço conhecido." }, "uf": { "type": [ "string", "null" ], "description": "UF desse endereço." }, "ddd": { "type": [ "integer", "null" ], "description": "DDD de um telefone conhecido." }, "telefone": { "type": [ "integer", "null" ], "description": "Número desse telefone." } } }, "PessoaFicha": { "allOf": [ { "$ref": "#/components/schemas/Pessoa" }, { "type": "object", "properties": { "obito_em": { "type": [ "string", "null" ], "format": "date" }, "nome_pai": { "type": [ "string", "null" ], "description": "Nome do pai." }, "rg": { "type": [ "string", "null" ], "description": "Número do RG." }, "orgao_emissor": { "type": [ "string", "null" ], "description": "Órgão emissor do RG." }, "uf_emissao": { "type": [ "string", "null" ], "description": "UF de emissão do RG." }, "nacionalidade": { "type": [ "string", "null" ], "description": "Nacionalidade." }, "situacao_cadastral": { "type": [ "integer", "null" ], "description": "Código de situação cadastral." }, "situacao_cadastral_em": { "type": [ "string", "null" ], "format": "date" }, "documentos": { "type": "object", "properties": { "pis": { "type": [ "integer", "null" ], "description": "PIS/NIT." }, "titulo_eleitor": { "type": [ "integer", "null" ], "description": "Título de eleitor." }, "zona": { "type": [ "string", "null" ], "description": "Zona eleitoral." }, "secao": { "type": [ "string", "null" ], "description": "Seção eleitoral." } } }, "score": { "type": [ "object", "null" ], "properties": { "csb8": { "type": [ "integer", "null" ], "description": "Score CSB8, 0 a 1000." }, "csb8_faixa": { "type": [ "string", "null" ], "description": "Faixa de risco do CSB8." }, "csba": { "type": [ "integer", "null" ], "description": "Score CSBA." }, "csba_faixa": { "type": [ "string", "null" ], "description": "Faixa de risco do CSBA." } } }, "perfil_financeiro": { "type": [ "object", "null" ], "properties": { "classe": { "type": [ "string", "null" ], "description": "Classe de poder aquisitivo." }, "codigo_classe": { "type": [ "integer", "null" ], "description": "Código da classe." }, "faixa": { "type": [ "string", "null" ], "description": "Faixa de renda estimada." } } }, "enderecos": { "type": "array", "items": { "type": "object", "properties": { "logradouro": { "type": [ "string", "null" ], "description": "Tipo e nome do logradouro." }, "numero": { "type": [ "string", "null" ], "description": "Número." }, "complemento": { "type": [ "string", "null" ], "description": "Complemento." }, "bairro": { "type": [ "string", "null" ], "description": "Bairro." }, "cidade": { "type": [ "string", "null" ], "description": "Cidade." }, "uf": { "type": [ "string", "null" ], "description": "UF." }, "cep": { "type": [ "string", "null" ], "description": "CEP, 8 dígitos sem máscara." }, "atualizado_em": { "type": [ "string", "null" ], "description": "Data da última atualização na origem." } } } }, "telefones": { "type": "array", "items": { "type": "object", "properties": { "ddd": { "type": [ "integer", "null" ], "description": "DDD." }, "numero": { "type": [ "integer", "null" ], "description": "Número." }, "tipo": { "type": [ "integer", "null" ], "description": "Código do tipo." }, "tipo_descricao": { "type": [ "string", "null" ], "description": "Residencial, Comercial ou Celular." }, "informado_em": { "type": [ "string", "null" ], "description": "Data em que a origem informou." } } } }, "emails": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Endereço." }, "prioridade": { "type": [ "integer", "null" ], "description": "Ordem de preferência na origem." }, "qualidade": { "type": [ "string", "null" ], "description": "Classificação de qualidade." }, "blacklist": { "type": "boolean", "description": "Consta em lista de bloqueio." } } } }, "vinculos": { "type": "array", "items": { "type": "object", "properties": { "nome": { "type": [ "string", "null" ], "description": "Nome do vínculo." }, "cpf": { "type": "string", "description": "CPF mascarado do vínculo." }, "vinculo": { "type": [ "string", "null" ], "description": "Grau de parentesco." } } } } } } ] }, "RespostaPessoas": { "type": "object", "required": [ "dados", "paginacao", "consulta" ], "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Pessoa" } }, "paginacao": { "type": "object", "properties": { "por_pagina": { "type": "integer", "description": "Teto pedido." }, "retornados": { "type": "integer", "description": "Linhas nesta resposta." }, "tem_mais": { "type": "boolean", "description": "Existem mais linhas além das retornadas." }, "amostra": { "type": "boolean", "description": "Verdadeiro quando o filtro condutor casou candidatos demais e a lista é um recorte deles, não o conjunto completo. Refine os filtros para obter cobertura." } } }, "consulta": { "type": "object", "properties": { "condutor": { "type": "string", "description": "Tabela por onde a consulta entrou. Útil para entender por que uma combinação ficou lenta." }, "ms": { "type": "integer", "description": "Tempo de execução em milissegundos." } } } } }, "LotePessoasRequisicao": { "type": "object", "required": [ "ids" ], "properties": { "ids": { "type": "array", "description": "IDs internos (campo `id` da busca), até o limite do lote.", "minItems": 1, "maxItems": 100, "items": { "type": "integer" }, "example": [ 123, 456 ] } } }, "LotePessoasResposta": { "type": "object", "required": [ "resultados", "resumo" ], "properties": { "resultados": { "type": "array", "items": { "type": "object", "required": [ "id" ], "description": "Um item por ID enviado, na mesma ordem. Ou traz `dados` (sucesso), ou `erro`+`mensagem` (falha isolada deste item).", "properties": { "id": { "type": [ "integer", "null" ], "description": "ID enviado, ou null quando o item não era um inteiro válido." }, "dados": { "$ref": "#/components/schemas/PessoaFicha" }, "cobranca": { "type": "object", "description": "Ausente quando a chamada é anônima — visitante não tem carteira e a ficha segue livre.", "properties": { "creditos": { "type": "integer", "description": "Créditos debitados por este item. 0 quando já paga." }, "ja_paga_na_competencia": { "type": "boolean", "description": "A ficha já havia sido cobrada neste mês." } } }, "erro": { "type": "string", "enum": [ "id_invalido", "nao_encontrado", "creditos_insuficientes" ] }, "mensagem": { "type": "string", "description": "Texto em português. Não compare por ela." } } } }, "resumo": { "type": "object", "properties": { "total": { "type": "integer", "description": "Itens enviados no lote." }, "sucesso": { "type": "integer", "description": "Itens resolvidos com dados." }, "creditos_debitados": { "type": "integer", "description": "Soma dos créditos debitados no lote." }, "saldo": { "type": "integer", "description": "Saldo de créditos após o lote." } } } } }, "Erro": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "string", "description": "Código estável, seguro para comparar em código." }, "mensagem": { "type": "string", "description": "Texto em português voltado a quem lê. A redação pode mudar; não compare por ela." } } } }, "responses": { "FiltrosAusentes": { "description": "erro=filtros_ausentes — nenhum filtro informado além do padrão de situação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "CnpjInvalido": { "description": "erro=cnpj_invalido — os dígitos verificadores não conferem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "UfInvalida": { "description": "erro=uf_invalida — sigla fora da tabela oficial.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "NaoEncontrado": { "description": "erro=nao_encontrado — CNPJ válido, mas ausente da base.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "LoteInvalido": { "description": "erro=lote_vazio — nenhum item enviado; ou erro=lote_excede_limite — quantidade acima do teto de max_itens_lote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "LimiteExcedido": { "description": "Limite de requisições excedido. Consulte o cabeçalho Retry-After.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até liberar." }, "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } } } }, "CredencialInvalida": { "description": "erro=credencial_ausente ou credencial_invalida — chave não enviada, inválida, revogada ou expirada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "PlanoSemApi": { "description": "erro=plano_sem_api — a chave é válida, mas a conta não tem direito de uso. A API exige plano pago; o plano gratuito acessa só pela web.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "FiltroPessoaInvalido": { "description": "erro=filtros_ausentes quando nenhum filtro foi informado; erro=filtro_nao_suportado para CPF parcial ou domínio de e-mail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } }, "ConsultaExpirada": { "description": "erro=consulta_expirada — a combinação de filtros excedeu o tempo limite no banco. Repetir tende a falhar de novo; acrescente um recorte mais estreito.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erro" } } } } } } }