Integração CNPJá

Neste artigo

1. Objetivo e Escopo
  1.1 Objetivo
  1.2 Escopo
  1.3 Público-alvo
  1.4 Convenções adotadas neste documento

2. Visão Geral da Solução
  2.1 Como funciona
  2.2 Componentes da solução

3. Pré-requisitos e Configuração
  3.1 Conta e chave de API na CNPJá
  3.2 Parâmetros do sistema
  3.3 Seleção da chave de API por empresa
  3.4 Validação de usuário nos campos de CNPJ

4. Operação
  4.1 Cadastro de clientes
  4.2 Cadastro de fornecedores
  4.3 Campos preenchidos automaticamente
  4.4 Regras de tratamento dos dados
  4.5 Inscrição estadual

5. Documentação Técnica de Fontes
  5.1 CNPJA00 — classe de comunicação com a API
  5.2 CNPJA01 — atualização dos cadastros
  5.3 Fluxo de execução

6. API CNPJá: custos, cache e limites

7. Tratamento de Erros e Diagnóstico

8. Quando acionar o suporte técnico

1. Objetivo e Escopo

1.1 Objetivo

Documentar a integração entre o TOTVS Protheus e a API do CNPJá, que realiza o preenchimento automático dos dados cadastrais de clientes e fornecedores a partir do CNPJ informado, reduzindo digitação manual e erros de cadastro.

1.2 Escopo

Este documento cobre:

• A visão geral e o funcionamento da solução;
• A configuração necessária no Protheus (parâmetros, validação de usuário e chave de API);
• A operação nos cadastros de clientes (SA1) e de fornecedores (SA2);
• A documentação técnica dos fontes ADVPL CNPJA00 e CNPJA01;
• O diagnóstico das ocorrências mais frequentes.

Não fazem parte do escopo deste documento:

• Contratação, faturamento e gestão de créditos junto à CNPJá;
• Instalação de patches e compilação de fontes no ambiente do cliente;
• Customizações específicas do cliente fora dos fontes aqui descritos.

1.3 Público-alvo

Os capítulos 3 e 4 destinam-se à equipe de operação e à consultoria funcional. Os capítulos 5 a 7 destinam-se à equipe técnica (desenvolvimento ADVPL e suporte). Pressupõe-se conhecimento prévio do TOTVS Protheus e dos cadastros de clientes e fornecedores.

1.4 Convenções adotadas neste documento

2. Visão Geral da Solução

2.1 Como funciona

O CNPJá é um serviço que consolida dados públicos de empresas brasileiras (Receita Federal, Simples Nacional, Cadastro Centralizado de Contribuintes, SINTEGRA e SUFRAMA) e os disponibiliza por meio de uma API REST. A integração consulta essa API assim que o usuário informa um CNPJ completo (14 dígitos) no cadastro e preenche automaticamente os campos de razão social, nome fantasia, endereço, contatos e inscrição estadual.

Resumo do fluxo

1. O usuário informa o CNPJ no campo A1_CGC (clientes) ou A2_CGC (fornecedores);
2. Ao sair do campo, a validação de usuário aciona a função U_CNPJA01();
3. A função consulta a API CNPJá (GET /office/{CNPJ}) usando a classe CNPJA00;
4. Os dados retornados são tratados (maiúsculas, remoção de acentos, ajuste de tamanho) e gravados nos campos da tela;
5. O usuário revisa os dados e confirma o cadastro normalmente.

2.2 Componentes da solução

3. Pré-requisitos e Configuração

3.1 Conta e chave de API na CNPJá

A API Comercial da CNPJá exige uma conta e uma Chave de API, enviada no cabeçalho Authorization de cada requisição. A chave é gerada automaticamente no cadastro da conta e fica disponível na página de Chave de API do portal da CNPJá. O consumo é controlado por créditos e por limite de requisições por minuto, ambos vinculados ao plano contratado (ver capítulo 6).

A CNPJá disponibiliza dois ambientes:

3.2 Parâmetros do sistema

3.3 Seleção da chave de API por empresa

A classe CNPJA00 identifica o CNPJ da empresa/filial logada no Protheus (campo M0_CGC do cadastro de empresas) e, com base nele, define qual chave de API será enviada à CNPJá. Isso permite que grupos com mais de um CNPJ, ou clientes distintos atendidos pelo mesmo repositório de fontes, utilizem contas CNPJá separadas.

A regra é aplicada em ResolveToken(), na seguinte ordem (a última regra atendida prevalece):

1. Empresa de teste (código 99): utiliza a chave da conta de testes;
2. CNPJ pertencente a uma lista de CNPJs associados a uma conta: utiliza a chave dessa conta;
3. Nenhuma regra atendida: a chave fica vazia e a requisição é enviada sem o cabeçalho Authorization.

3.4 Validação de usuário nos campos de CNPJ

Para que a consulta seja disparada automaticamente, inclua a expressão abaixo na Validação de Usuário (dicionário de dados, tabela SX3) de cada campo:

Clientes — campo A1_CGC

IIF(!IsBlind() .And. Len(AllTrim(M->A1_CGC)) == 14, U_CNPJA01(), .T.)

Fornecedores — campo A2_CGC

IIF(!IsBlind() .And. Len(AllTrim(M->A2_CGC)) == 14, U_CNPJA01(), .T.)

A função identifica automaticamente a tabela de destino pela rotina em execução: quando a rotina é MATA020 (Fornecedores), atualiza a SA2; nos demais casos (por exemplo, MATA030 ou CRMA980 — Clientes), atualiza a SA1.

4. Operação

4.1 Cadastro de clientes

Caminho: Faturamento → Atualizações → Cadastros → Clientes (rotina MATA030 ou CRMA980, conforme a versão).

1. Acione Incluir;
2. No campo CNPJ/CPF (A1_CGC), informe os 14 dígitos do CNPJ e pressione Tab (ou saia do campo);
3. Aguarde a consulta à CNPJá. Os campos de razão social, nome fantasia, endereço, bairro, município, UF, CEP, telefone, e-mail e inscrição estadual serão preenchidos;
4. Revise os dados, complete os demais campos obrigatórios (loja, tipo, natureza, condição de pagamento etc.) e acione Confirmar.

4.2 Cadastro de fornecedores

Caminho: Compras → Atualizações → Cadastros → Fornecedores (rotina MATA020).

1. Acione Incluir;
2. No campo CNPJ/CPF (A2_CGC), informe os 14 dígitos do CNPJ e saia do campo;
3. Os campos de dados cadastrais serão preenchidos automaticamente;
4. Revise, complete os demais campos obrigatórios e acione Confirmar.

4.3 Campos preenchidos automaticamente

4.4 Regras de tratamento dos dados

• Textos: razão social, fantasia, logradouro, bairro, complemento e município são convertidos para maiúsculas, sem acentos;
• Tamanho: cada valor é cortado ao tamanho do respectivo campo no dicionário de dados (TamSX3);
• Endereço: o campo de endereço é gravado no formato "LOGRADOURO, NÚMERO";
• Código do município: a CNPJá retorna o código IBGE de 7 dígitos (2 do estado + 5 do município). O Protheus recebe apenas os 5 dígitos do município;
• CEP: somente dígitos;
• Telefone e e-mail: utiliza-se o primeiro contato retornado pela API. Se a API não retornar contatos, os campos não são alterados pela consulta;
• Campos ausentes: quando a API não retorna determinada informação, o valor correspondente é gravado vazio.

4.5 Inscrição estadual

A inscrição estadual é obtida pelo parâmetro registrations da API (Cadastro Centralizado de Contribuintes/SINTEGRA):

• Se a API retornar inscrições, é utilizada a primeira da lista;
• Se não houver inscrição retornada, o campo é preenchido com ISENTO;
• Na rotina de clientes, a atualização da inscrição pode ser desabilitada pelo parâmetro lAtuINSCR da função (ver item 5.2).

5. Documentação Técnica de Fontes

5.1 CNPJA00 — classe de comunicação com a API

Arquivo: CNPJA00.prw  |  Autor: Rafael Yera Barchi  |  Criação: 20/10/2025

Classe ADVPL que encapsula as chamadas REST à API CNPJá, utilizando a classe padrão FWREST.

Propriedades

Métodos

Estrutura de retorno do método DoRequest

O método devolve um array de pares chave/valor, sempre na mesma ordem:

Funções auxiliares (internas ao fonte)

• OnlyDigits(cVal) — mantém apenas os dígitos de uma string;
• UrlJoin(cBase, cPath) — concatena URL base e caminho, tratando a barra;
• BuildQueryString(hQuery) — monta a query string codificada a partir de um hash.

Exemplo de uso (utilitário de teste)

User Function ADTsTCNPJA(cCNPJ)
	local oCli := CNPJA00():New()
	local aRet := oCli:GetOffice(cCNPJ)
return aRet

5.2 CNPJA01 — atualização dos cadastros

Arquivo: CNPJA01.prw  |  Função: U_CNPJA01  |  Retorno: .T. em caso de sucesso; .F. em caso de falha.

Assinatura

U_CNPJA01(cCNPJ, cAliasCad, cCodCli, cLjCli, lAtuINSCR)

Modos de execução

Exemplo de chamada em gravação direta (clientes)

lOk := U_CNPJA01("12345678000190", "SA1", "000001", "01", .T.)

Detecção da tabela de destino

A função verifica o nome da rotina em execução (FunName()): se for MATA020, trata como fornecedor (SA2); em qualquer outra rotina, trata como cliente (SA1).

Chamada à API

GET {AD_CNPJAUR}/office/{CNPJ}?registrations=BR

5.3 Fluxo de execução

1. Obtém o CNPJ (parâmetro ou campo da tela) e mantém apenas os dígitos;
2. Instancia CNPJA00 (resolve URL e chave de API) e executa a consulta;
3. Se a resposta for bem-sucedida, interpreta o JSON e carrega os dados em variáveis internas;
4. Aplica os dados ao cadastro (em memória ou gravação direta) conforme as regras do capítulo 4. Se AD_CONSZTM estiver ativo, os valores vêm da tabela ZTM; caso contrário, diretamente da CNPJá;
5. Se a consulta falhar, exibe a mensagem de erro em tela (FWAlertError) ou, em execução sem interface, grava no console do Application Server (ConOut).

6. API CNPJá: custos, cache e limites

As informações abaixo foram extraídas da documentação oficial da CNPJá (cnpja.com/api) e podem ser alteradas pelo fornecedor. Em caso de dúvida, a documentação da CNPJá prevalece.

Códigos de erro retornados pela API

7. Tratamento de Erros e Diagnóstico

Em caso de falha, o sistema exibe a janela Erro na consulta CNPJá - Estabelecimentos com a mensagem retornada. Em execuções sem interface, a mesma mensagem é gravada no console do Application Server.

8. Quando acionar o suporte técnico

Acione o suporte técnico da Atos Data quando:

• O erro apontar para chave de API, parâmetros ou configuração da solução;
• For necessário incluir um novo CNPJ/empresa na seleção de chave de API;
• For necessário habilitar a consulta para novas rotinas de cadastro;
• A ocorrência não for compreendida ou persistir após as ações indicadas no capítulo 7.

Não altere parâmetros, validações de usuário ou fontes por conta própria.