Como integrar dados de CNPJ ao CRM e ao ERP?

Fatos e fontes

• O leiaute da Receita separa dados da empresa, como capital e porte, de dados dos estabelecimentos, como endereço e CNAEs. Receita Federal — leiaute dos dados abertos do CNPJ.
• CFO: a API oferece busca paginada e consulta de dossiê, com autenticação e cotas documentadas. CFO — documentação da API.
• CFO: o endereço do dossiê inclui complemento e codigo_ibge; o código municipal pode ser null e exige tratamento na integração. CFO — endereço no dossiê.
• CFO: telefone e e-mail podem ser devolvidos mascarados; a integração precisa interpretar o estado de acesso. CFO — documentação da API.
• CFO: a consulta de metadados permite conferir limites e uso da conta, sem consumo de quota segundo a documentação. CFO — documentação da API.

Qual chave deve identificar a empresa no CRM ou ERP?

O CNPJ completo é a chave para o estabelecimento. A raiz pode ser mantida em outro campo para agrupar unidades da pessoa jurídica. Usar apenas a razão social como chave de atualização cria risco de unir homônimos ou sobrescrever uma filial com dados de outra.

Quais campos ajudam a preencher o cadastro no ERP?

O dossiê cadastral pode alimentar a identificação de clientes e fornecedores. O mapeamento abaixo descreve campos da API; cada ERP define seus próprios nomes e regras de gravação.

Os campos completos estão em dossiê da API. O guia de código IBGE pelo CNPJ detalha a conversão municipal. Parâmetros fiscais da emissão precisam de uma etapa própria de validação: o CNAE descreve a atividade cadastrada, e o regime tributário deve conservar fonte e período. Esses registros não preenchem automaticamente todos os campos de uma nota.

Como deve funcionar o fluxo de atualização?

1. Validar e normalizar o CNPJ recebido pelo CRM.
2. Consultar a operação adequada da API com credencial armazenada no servidor.
3. Verificar o status da resposta, o identificador e a referência.
4. Aplicar o mapeamento, preservando campos protegidos por validação humana.
5. Registrar mudanças e erros para revisão ou nova tentativa controlada.

Como tratar campos vazios e falhas?

Um campo ausente não deve apagar automaticamente uma informação validada. Da mesma forma, contato mascarado não deve substituir o endereço de e-mail de trabalho confirmado. A regra pode guardar o retorno em campos de origem e encaminhar conflitos para conferência.

Exemplo hipotético: o CRM tem contato validado em setembro; a consulta de outubro devolve e-mail mascarado por cota. A integração mantém o contato validado e registra o estado da consulta. Substituir o campo principal pela máscara degradaria o cadastro.

Existe um conector pronto para qualquer CRM?

Este roteiro descreve integração pela API. A compatibilidade depende dos recursos de importação, automação ou desenvolvimento do CRM escolhido. A documentação da API orienta a implementação; o guia não pressupõe um conector nativo para uma plataforma específica.

Como tratar cada erro da API?

A decisão deve combinar o status HTTP com error.code. A documentação de erros do CFO diferencia os casos; as ações abaixo são um roteiro de integração.

O que testar antes de colocar a integração em produção?

O teste deve conferir o que será gravado, incluindo os casos em que a consulta retorna dados incompletos. Erros e esgotamento de cota podem ser simulados com respostas de teste, sem consumir deliberadamente o saldo da conta.

1. CNPJ numérico com zero inicial e CNPJ alfanumérico: preservar o identificador como texto durante consulta e gravação.
2. Matriz e filial da mesma raiz: atualizar somente a unidade identificada no cadastro de destino.
3. CNPJ não encontrado, campo vazio e codigo_ibge nulo: manter a informação validada e sinalizar a pendência.
4. Contato mascarado, cota esgotada e manutenção: executar a ação prevista para cada retorno.
5. Reprocessamento da mesma resposta: atualizar o registro correspondente sem criar uma segunda ficha para o mesmo CNPJ.
6. Registro da execução: guardar resultado, origem e horários sem incluir a chave da API nos registros de erro.

Fontes e orientações conferidas em 10 de outubro de 2026. Exemplos identificados como hipotéticos ou ilustrativos não representam consultas a empresas reais.