A partir de 06/07/2026, a Receita Federal passa a emitir o novo CNPJ alfanumérico, e quem mantém uma loja em Magento 2 ou Adobe Commerce precisa garantir que o checkout e os formulários aceitem letras no campo de documento. Se a sua validação atual só reconhece números, novos clientes simplesmente não vão conseguir finalizar o cadastro. Para resolver isso sem reinventar a roda, este post apresenta um módulo gratuito que aplica máscara e validação de CNPJ alfanumérico no Magento 2 de ponta a ponta: server-side, frontend, checkout e CLI.
A base legal é a Instrução Normativa RFB nº 2.229, de 15/10/2024. O motivo da mudança é simples: o CNPJ puramente numérico está se esgotando, já que mais de 60 milhões de inscrições foram emitidas. Em vez de aumentar o tamanho do documento, a Receita optou por permitir letras nas primeiras posições, mantendo as 14 posições e a máscara que você já conhece.
Importante: os CNPJs numéricos atuais NÃO mudam e continuam totalmente válidos. O novo formato vale apenas para novos cadastros e estabelecimentos emitidos a partir de 06/07/2026. Ou seja, a sua loja precisa passar a aceitar o formato novo sem quebrar o suporte ao formato antigo.
⬇️ Baixar o módulo Magento 2 (.zip grátis)
O que é o CNPJ alfanumérico
O CNPJ alfanumérico mantém as mesmas 14 posições e a mesma máscara de hoje, XX.XXX.XXX/XXXX-XX, mas passa a aceitar letras nas 12 primeiras posições. A estrutura fica assim:
- Posições 1 a 12 (alfanuméricas): aceitam dígitos de 0 a 9 e letras de A a Z. São 8 caracteres da raiz mais 4 da ordem do estabelecimento.
- Posições 13 e 14 (dígitos verificadores): continuam sempre numéricos, calculados pelo módulo 11.
Um exemplo válido oficial é 12.ABC.345/01DE-35 (sem máscara, 12ABC34501DE35; dígitos verificadores iguais a 35). Note que as letras aparecem no meio do documento, exatamente onde antes só havia números. A SERPRO e a Receita Federal já disponibilizaram códigos de referência em Java, Python e TypeScript para o novo cálculo.
Impacto do CNPJ alfanumérico no Magento 2 e no Adobe Commerce
Por padrão, o Magento usa o campo vat_id para armazenar o documento fiscal do cliente, tanto no checkout quanto nos formulários de endereço. A maioria das lojas brasileiras adiciona, em cima disso, alguma validação ou máscara que assume apenas dígitos. Com a chegada do CNPJ alfanumérico, esse pressuposto deixa de valer.
Os sintomas mais comuns quando nada é feito:
- O cliente digita um CNPJ com letras e a máscara recusa os caracteres, impedindo o preenchimento.
- A validação do checkout marca o documento como inválido e bloqueia a finalização da compra.
- Integrações com ERP ou emissor de nota fiscal recebem dados truncados ou rejeitam o pedido.
O melhor momento para tratar isso é antes de 06/07/2026, com um componente reutilizável que sirva de fonte única da verdade para validação, em vez de espalhar regex pela loja inteira.
O módulo Roger_CnpjAlfanumerico
O Roger_CnpjAlfanumerico é um módulo gratuito (licença GPL) que prepara o Magento 2 para o CNPJ alfanumérico com o mínimo de configuração. O pacote Composer é roger/module-cnpj-alfanumerico, na versão 1.0.0, e é compatível com Magento Open Source e Adobe Commerce 2.4.x, em PHP 7.4+ e 8.x. Ele também continua validando o CNPJ numérico legado.
O que o módulo entrega:
- Validador server-side reutilizável — a classe
Roger\CnpjAlfanumerico\Model\CnpjValidatoré a fonte da verdade da validação, usada por todo o resto. - Regra de validação no frontend —
validate-cnpj-alfanumerico, registrada tanto no validador do checkout (Magento_Ui) quanto nomage/validation(formulários jQuery, como o de endereço do cliente). - Máscara automática
XX.XXX.XXX/XXXX-XXvia delegação de eventos, funcionando inclusive em campos renderizados pelo Knockout. - Plugin de LayoutProcessor que aplica a regra e a máscara ao campo
vat_iddo checkout automaticamente. - Comando de console para validar e formatar CNPJs direto pela CLI.
⬇️ Baixar o módulo Magento 2 (.zip grátis)
Usa WordPress com WooCommerce em outra loja? Há uma versão equivalente: veja o plugin de CNPJ alfanumérico para WooCommerce e WordPress.
Instalação
Via Composer (recomendado)
O caminho mais limpo é instalar pelo Composer e rodar a sequência padrão de deploy do Magento:
composer require roger/module-cnpj-alfanumerico
bin/magento module:enable Roger_CnpjAlfanumerico
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy pt_BR -f
bin/magento cache:flushInstalação manual (.zip)
Se preferir, baixe o .zip e extraia o conteúdo em app/code/Roger/CnpjAlfanumerico. Em seguida, rode os mesmos comandos module:enable, setup:upgrade, setup:di:compile e cache:flush para registrar e compilar o módulo.
Teste pela linha de comando
Antes de mexer no frontend, vale conferir o validador pela CLI. O comando aceita CNPJ com ou sem máscara e retorna o resultado junto com um código de saída (0 para válido, 1 para inválido), o que é útil em scripts e pipelines:
bin/magento roger:cnpj:validate "12.ABC.345/01DE-35"
# Resultado: VÁLIDO (código de saída 0)
bin/magento roger:cnpj:validate "11.222.333/0001-81"
# Resultado: VÁLIDO (CNPJ numérico legado)
bin/magento roger:cnpj:validate "12ABC34501DE34"
# Resultado: INVÁLIDO (código de saída 1)Repare que o terceiro exemplo é inválido apenas porque o dígito verificador está errado (34 em vez de 35), o que confirma que o cálculo do módulo 11 está funcionando de verdade.
Como aplicar a um campo específico
Por padrão, o módulo mira o campo vat_id do checkout. Se você usa outro campo, como um atributo customizado de CNPJ, basta alterar a constante FIELD_CODE em Plugin/Checkout/LayoutProcessorPlugin.php para o código do seu campo.
Em qualquer outro formulário da loja, o comportamento é ativado por classes e regras no próprio input:
- Adicione a classe
cnpj-alfa-maskpara ativar a máscara automática. - Adicione a regra
validate-cnpj-alfanumericopara ativar a validação.
Como a máscara funciona por delegação de eventos, ela continua valendo mesmo em campos injetados dinamicamente pelo Knockout, sem precisar de inicialização manual.
Uso programático
Quando você precisa validar um CNPJ no seu próprio código (em um observer, um service, uma importação de clientes), injete o validador por dependência e use a mesma fonte da verdade do resto do módulo:
use Roger\CnpjAlfanumerico\Model\CnpjValidator;
public function __construct(CnpjValidator $cnpjValidator)
{
$this->cnpjValidator = $cnpjValidator;
}
if ($this->cnpjValidator->isValid('12.ABC.345/01DE-35')) {
$masked = $this->cnpjValidator->mask('12ABC34501DE35'); // 12.ABC.345/01DE-35
}Os métodos isValid() e mask() aceitam o documento com ou sem máscara, o que evita ter que normalizar a entrada manualmente antes de chamar a validação.
Como funciona o cálculo do dígito verificador
O grande pulo do gato do CNPJ alfanumérico está em como cada caractere entra no cálculo do módulo 11. Em vez de usar o valor numérico do dígito, o algoritmo usa o código ASCII menos 48. Assim, os números 0 a 9 continuam valendo 0 a 9, e as letras passam a valer de A=17 até Z=42 (A=17, B=18, C=19 e assim por diante).
A partir desses valores, aplicam-se os pesos do módulo 11 sobre as 12 primeiras posições para o primeiro dígito, e sobre as 12 posições mais o primeiro dígito para o segundo:
// valor do caractere = código ASCII - 48 (A=17, B=18, ... Z=42)
// DV1: pesos 5 4 3 2 9 8 7 6 5 4 3 2
// DV2: pesos 6 5 4 3 2 9 8 7 6 5 4 3 2
// resto = soma % 11 ; dígito = (resto < 2) ? 0 : 11 - restoEm outras palavras: multiplica-se cada valor pelo peso correspondente, soma-se tudo, calcula-se o resto da divisão por 11 e, se o resto for menor que 2, o dígito é 0; caso contrário, é 11 menos o resto. É exatamente a mesma lógica do CNPJ numérico, com a diferença de que agora as letras também entram na conta. O módulo encapsula tudo isso para você não precisar reimplementar o algoritmo.
Perguntas frequentes (FAQ)
Os CNPJs numéricos atuais vão deixar de funcionar?
Não. Os CNPJs numéricos já emitidos continuam válidos e não mudam. O formato alfanumérico vale para novos cadastros e estabelecimentos a partir de 06/07/2026, e o módulo valida os dois formatos.
Preciso fazer alguma mudança no banco de dados?
Não no caso do campo padrão. O vat_id já é um campo de texto, então armazenar letras não exige migração. Se você usa um atributo customizado, garanta apenas que ele seja do tipo texto e aponte a constante FIELD_CODE para ele.
O módulo é compatível com a minha versão do Magento?
Sim, desde que você esteja em Magento Open Source ou Adobe Commerce 2.4.x, com PHP 7.4+ ou 8.x. Esses são os requisitos suportados pela versão 1.0.0.
A máscara funciona no checkout, que é renderizado em Knockout?
Sim. A máscara usa delegação de eventos, então funciona mesmo em campos criados dinamicamente pelo Knockout, incluindo o campo de documento do checkout.
Posso usar o validador fora do checkout?
Pode. A classe Roger\CnpjAlfanumerico\Model\CnpjValidator é injetável por dependência e pode ser usada em qualquer ponto do seu código, além de estar disponível pela CLI com o comando roger:cnpj:validate.
Conclusão
O CNPJ alfanumérico no Magento 2 não é um "talvez": é uma mudança com data marcada e base legal definida. A boa notícia é que adaptar a sua loja não precisa virar um projeto. Com o módulo Roger_CnpjAlfanumerico, você ganha máscara, validação no checkout e nos formulários, validador reutilizável, plugin automático para o campo vat_id e comando de CLI, tudo de graça e compatível com o formato numérico legado. Instale, teste pela linha de comando e deixe a sua loja pronta antes de 06/07/2026.
⬇️ Baixar o módulo Magento 2 (.zip grátis)