Documentação da API LeadCNPJ

Referência

Anatomia da resposta de GET /v1/empresa/:cnpj

A resposta tem duas seções: dados públicos da Receita Federal (sempre presentes quando o CNPJ existe) e enriquecimento (presente quando há cache ou quando ?enriquecer=true foi enviado). Abaixo o JSON completo com tudo que a API pode retornar, anotado:

{
  "data": {
    // ─── BLOCO 1: IDENTIFICAÇÃO (sempre presente) ─────────────────────
    "cnpj": "12345678000190",            // sempre, 14 dígitos sem máscara
    "cnpj_formatado": "12.345.678/0001-90", // sempre, com máscara para apresentação
    "cnpj_basico": "12345678",           // sempre, 8 primeiros dígitos
    "razao_social": "Empresa Exemplo LTDA",  // sempre, normalizado (Title Case + acronimos legais em CAPS)
    "nome_empresa": "Empresa Exemplo LTDA",  // razao_social sem prefixo numérico (útil pra MEI)
    "nome_fantasia": "Marca Exemplo",    // pode ser null. Normalizado igual a razao_social
    "matriz_filial": "matriz",           // "matriz" | "filial"

    // ─── BLOCO 2: SITUAÇÃO E DATAS (sempre presente, ISO 8601) ───────
    "situacao": {
      "codigo": "02",                     // 01 Nula | 02 Ativa | 03 Suspensa | 04 Inapta | 08 Baixada
      "descricao": "Ativa",
      "data": "2013-03-07"                // pode ser null
    },
    "data_inicio_atividades": "2013-03-07",  // pode ser null

    // ─── BLOCO 3: ENQUADRAMENTO LEGAL ────────────────────────────────
    "natureza_juridica": {
      "codigo": "2062",                   // sempre
      "descricao": "Sociedade Empresária Limitada"  // null se código fora do catálogo
    },
    "porte_empresa": {
      "codigo": "01",                     // 01 ME | 03 EPP | 05 Demais | 00 Não Informado
      "descricao": "Microempresa (ME)"
    },
    "capital_social": 100000,             // numérico (BRL). null quando ausente

    // ─── BLOCO 4: ATIVIDADES ECONÔMICAS (CNAE) ───────────────────────
    "cnae_principal": {
      "codigo": "6201501",                // sempre
      "descricao": "Desenvolvimento de programas de computador..."  // null se fora do catálogo
    },
    "cnae_secundario": [                  // array (pode estar vazio)
      { "codigo": "6202300", "descricao": "Desenvolvimento e licenciamento..." }
      // 0..N itens
    ],

    // ─── BLOCO 5: ENDEREÇO (sempre presente, campos individuais podem ser null) ──
    // Todos os campos vêm normalizados em Title Case pra uso direto em CRM.
    "endereco": {
      "tipo_logradouro": "Avenida",       // normalizado. Pode ser null
      "logradouro": "Exemplo",            // normalizado. Pode ser null
      "numero": "1000",                   // string. "S/N" padronizado. null se 0/vazio
      "complemento": "Sala 100",          // normalizado (whitespace + Title Case)
      "bairro": "Bairro Exemplo",         // normalizado. Pode ser null
      "cep": "01310100",                  // 8 dígitos sem máscara
      "cep_formatado": "01310-100",       // com máscara. null se cep ausente
      "municipio": "São Paulo",           // normalizado. Pode ser null
      "uf": "SP",                         // 2 letras (sempre uppercase). Pode ser null
      "completo": "Avenida Exemplo, 1000, Sala 100, Bairro Exemplo, São Paulo - SP, 01310-100"
                                          // string montada pronta pra CRM/e-mail. Pula campos null.
    },

    // ─── BLOCO 6: CONTATO RFB (telefone e e-mail declarados na Receita) ─────
    // Telefones com placeholder "(0000) 00000000" do RFB viram null
    // automaticamente. E-mails são lowercased + validados (RFB armazena em CAPS).
    "contato": {
      "telefone_principal": "(11) 3000-0000",  // mascarado. null se placeholder/vazio
      "telefone_secundario": null,             // null se só tem 1 ou placeholder
      "email": "contato@empresaexemplo.com.br" // lowercased. null se ausente/inválido
    },

    // ─── BLOCO 7: REGIME TRIBUTÁRIO ──────────────────────────────────
    "regime_tributario": {
      "simples_nacional": true,           // boolean (não null)
      "mei": false                        // boolean (não null)
    },

    // ─── BLOCO 8: QSA — sócios e administradores (array, pode estar vazio) ──
    // Vazio para EI (Empresário Individual) e MEI sem outros sócios.
    "qsa": [
      {
        "tipo": "pessoa_fisica",          // pessoa_fisica | pessoa_juridica | estrangeiro | desconhecido
        "nome": "Fulano da Silva",        // normalizado (Title Case + conectores pt-BR em minúscula)
        "documento": "***123456**",       // PF: CPF mascarado pela RFB. PJ: CNPJ completo. null pra estrangeiro sem doc.
        "qualificacao": {
          "codigo": "49",                 // código RFB de qualificação societária
          "descricao": "Sócio-Administrador"  // null se código fora do catálogo
        },
        "data_entrada": "2020-01-15",     // ISO 8601. pode ser null
        "faixa_etaria": {                 // null pra PJ e estrangeiro
          "codigo": 4,                    // 1..9
          "descricao": "31-40 anos"       // 0-12 | 13-20 | 21-30 | 31-40 | 41-50 | 51-60 | 61-70 | 71-80 | 80+
        }
      }
    ],

    // ─── BLOCO 9: ENRIQUECIMENTO (null quando não há cache) ──────────
    // Quando presente, score_completude resume o quanto cada módulo entregou.
    // Sub-módulos individuais (google, website) podem ser null se aquela fonte
    // específica ainda não foi consultada — diferente de "consultado e vazio".
    "enriquecimento": {
      "score_completude": 75,             // 0..100. Calculado pelo backend.
      "atualizado_em": "2026-04-10T20:54:26",  // última atualização de qualquer módulo

      // WhatsApp principal detectado (consolidado de todas as fontes)
      "whatsapp": "https://api.whatsapp.com/send?phone=5511999999999",  // string ou null

      // ─── 9a: Localização e listagem pública (TTL 30 dias) ─────────
      "google": {                         // null se módulo ainda não consultado
        "nome": "Empresa Exemplo",        // displayName público. pode ser null
        "telefone": "+55 11 99999-9999",  // pode ser null
        "website": "https://empresaexemplo.com.br/",  // pode ser null
        "rating": 4.5,                    // 1.0..5.0. pode ser null se sem reviews
        "rating_count": 42,               // pode ser 0
        "status": "OPERATIONAL",          // OPERATIONAL | CLOSED_TEMPORARILY | CLOSED_PERMANENTLY
        "horario_atendimento": [          // array de strings descrevendo cada dia. Pode estar vazio.
          "segunda-feira: 09:00 – 18:00",
          "terca-feira: 09:00 – 18:00",
          "domingo: Fechado"
        ],
        "endereco": "Av. Exemplo, 1000 - Bairro Exemplo, São Paulo - SP, 01310-100, Brasil",
        "maps_url": "https://maps.google.com/?cid=00000000000000000",
        "place_id": "ChIJExamplePlaceId000000",
        "atualizado_em": "2026-04-10T20:54:25"
      },

      // ─── 9b: Sinais do site da empresa (TTL 45 dias) ─────────────
      "website": {                        // null se módulo ainda não consultado
        "url": "https://empresaexemplo.com.br",  // URL consultada
        "emails": [                       // array. Vazio se nenhum encontrado.
          "contato@empresaexemplo.com.br",
          "comercial@empresaexemplo.com.br"
        ],
        "telefones": [
          "(11) 3000-0000"
        ],
        "redes_sociais": {                // objeto. Chaves: linkedin | instagram | facebook | twitter | youtube | whatsapp
          "linkedin": "https://linkedin.com/company/empresa-exemplo",  // valores podem ser null
          "instagram": "https://instagram.com/empresaexemplo/",
          "facebook": "https://facebook.com/empresaexemplo",
          "twitter": null,
          "youtube": null,
          "whatsapp": "https://api.whatsapp.com/send?phone=5511999999999"
        },
        "paginas_varridas": [             // array de URLs que foram processadas
          "https://empresaexemplo.com.br",
          "https://empresaexemplo.com.br/contato/"
        ],
        "atualizado_em": "2026-04-10T20:54:25"
      },

      // ─── 9c: Contatos consolidados (merge de TODAS as fontes, deduplicado) ──
      // Atalho prático: já é o merge de fontes públicas na web + RFB.
      // Sempre presente quando enriquecimento existe (mesmo que arrays vazios).
      "contatos_consolidados": {
        "emails": [                       // dedup case-insensitive
          "contato@empresaexemplo.com.br",
          "comercial@empresaexemplo.com.br"
        ],
        "telefones": [
          "(11) 30000000",
          "+55 11 99999-9999"
        ],
        "redes_sociais": { /* mesmo shape do website.redes_sociais */ }
      },

      // ─── 9d: Decisores via fontes públicas (TTL 90 dias) ────────
      // Array. Vazio se a fonte ainda não consultou OU se não achou nada.
      "decisores": [
        {
          "nome": "FULANO DA SILVA",      // sempre presente quando item existe
          "cargo": "Diretor Comercial",   // null se não inferido
          "email": "fulano@empresaexemplo.com.br", // null se não encontrado
          "linkedin_url": "https://linkedin.com/in/fulano-exemplo",  // null se não achou
          "snippet": "..."                // trecho de texto que motivou a inclusão
        }
      ]
    }
  },
  "meta": {
    "creditos_consumidos": 1,             // 1 normalmente. 2 com ?enriquecer=true.
    "creditos_restantes": 841             // saldo da conta após o débito desta call
  }
}

Resumo: o que sempre vem vs o que é condicional

Bloco	Garantia	Notas
Identificação (1)	Sempre	nome_fantasia pode ser null
Situação + datas (2)	Sempre	Datas vêm em ISO 8601. situacao.data pode ser null
Natureza jurídica + porte (3)	Sempre	descricao pode ser null se código fora do catálogo
CNAE principal (4)	Sempre	cnae_secundario é array, pode estar vazio
Endereço (5)	Sempre	Campos individuais podem ser null
Contato RFB (6)	Sempre	Todos os 3 campos podem ser null. Frequentemente desatualizados — prefira enriquecimento.contatos_consolidados quando disponível
Regime tributário (7)	Sempre	Ambos campos são boolean, nunca null
QSA (8)	Sempre	Array. Vazio para EI/MEI sem outros sócios. faixa_etaria é null para sócios PJ/estrangeiros
Enriquecimento (9)	Condicional	null quando não há cache. Use ?enriquecer=true pra forçar (+1 consulta). Sub-módulos (google, website, decisores) podem ser null individualmente

Quirks importantes

A API já trata os quirks comuns da Receita Federal pra você (veja Normalização automática na introdução). Os pontos abaixo são particularidades que permanecem visíveis no payload por razões válidas:

• CPF mascarado pela RFB: sócios pessoa física vêm com CPF no formato ***123456** (apenas dígitos 4–9 visíveis). É padrão da RFB e proteção LGPD — não tem como "desmascarar" via API.
• CNPJ de sócio PJ vem completo: diferente do CPF, CNPJ de sócio pessoa jurídica vem sem mascarar — você pode passar de volta no GET /v1/empresa/:cnpj pra explorar a matriz societária.
• Telefones placeholder já são null: a RFB usa (0000) 00000000 e variantes como "campo declarado vazio". A API detecta esses padrões e devolve null automaticamente — você não precisa tratar 0000 no seu lado.
• E-mails já vêm em lowercase + validados: a RFB armazena em CAIXA ALTA, mas a API faz lowercase + FILTER_VALIDATE_EMAIL antes de devolver. Listas de e-mails em enriquecimento também são dedup'd case-insensitive — você não precisa rodar strtolower() nem deduplicar manualmente.
• Datas em ISO 8601: a RFB usa YYYYMMDD ou '00000000' pra ausente. A API converte para YYYY-MM-DD ou null automaticamente — você não precisa tratar.
• Endereço em CAIXA ALTA já é Title Case: a RFB devolve "RUA AQUIDABAN", a API entrega "Rua Aquidaban" pronta pra CRM. Acrônimos legais (LTDA, ME, S/A) e UFs preservados em CAPS.
• Array vazio ≠ null: em enriquecimento.decisores, [] significa "fonte consultada, nada encontrado"; o módulo inteiro ser null significa "ainda não consultado". Mesma lógica em website e google.