Razão social e nome fantasia

São dois nomes com donos diferentes. A razão social identifica a pessoa jurídica no registro: é o nome do contrato social, o que assina contrato e emite nota. O nome fantasia identifica o estabelecimento no mercado: é o que está na fachada, e pode variar de uma filial para outra ou simplesmente não existir.

Qual é de quem

• Razão social: da empresa. Todos os estabelecimentos da mesma raiz devolvem a mesma string. Nunca vem nula. Carrega o sufixo da natureza jurídica quando ele existe, como LTDA ou SA.
• Nome fantasia: do estabelecimento. Vem null quando a empresa não declarou, e isso é comum — a ausência não indica problema de cadastro.

Os dois chegam como a Receita Federal publica: caixa alta, sem acentuação, com abreviação de fantasia da própria empresa. Não são texto editorial, e não devem ir para uma tela de cliente sem tratamento.

Como a API devolve

"razao_social": "BANCO DO BRASIL SA",
"nome_fantasia": "DIRECAO GERAL"

Perfil basic, os dois como texto. A busca de empresas não filtra por nome: os recortes são CNAE, UF, município, porte, situação, natureza jurídica, capital e data de abertura. Nome não é chave de busca porque não é chave de nada.

Como usar

• Cadastro: a chave é o CNPJ do estabelecimento, e a raiz agrupa a empresa. Nome serve para exibir, nunca para identificar.
• Deduplicação: casar base por nome produz falso positivo (duas empresas com razão social parecida) e falso negativo (a mesma empresa escrita com e sem ponto, com e sem LTDA). Normalize e case por CNPJ; use o nome só para conferência humana.
• Exibição: mostre o nome fantasia quando existir e a razão social como segundo nome; para documento fiscal, sempre a razão social.
• Enriquecimento: se o que você tem é só o nome, resolva primeiro para CNPJ por outro caminho e depois consulte — a API responde por CNPJ e por filtro estrutural.

Campos completos em Campos da resposta.