CNPJ alfanumérico na VTEX e Nuvemshop: como adaptar

Adaptar o CNPJ alfanumérico na VTEX e na Nuvemshop (Tiendanube) é diferente de mexer no seu próprio código: são plataformas SaaS fechadas, então você ataca o problema pelos pontos de extensão certos — JavaScript no checkout, scripts de app e as integrações de back-office (ERP/NF-e). Este tutorial mostra onde plugar a validação correta e o que está fora do seu alcance.

O que muda no CNPJ alfanumérico

A partir de julho de 2026, o novo CNPJ mantém as 14 posições e a mesma máscara XX.XXX.XXX/XXXX-DD, mas as 12 primeiras posições (raiz + ordem) passam a aceitar letras maiúsculas A–Z além dos dígitos 0–9. Os dois dígitos verificadores finais continuam numéricos. Os CNPJs numéricos atuais não mudam e seguem válidos — sua loja precisa aceitar os dois formatos ao mesmo tempo. Para o panorama completo, veja o nosso guia de implementação do CNPJ alfanumérico.

O desafio em plataformas SaaS fechadas

Tanto a VTEX quanto a Nuvemshop são SaaS: você não edita o validador nativo de CNPJ delas. Seja honesto sobre o limite — a validação interna do campo de documento é da plataforma, e até elas liberarem o alfanumérico, o que cabe a você é (1) adicionar/ajustar validação por JavaScript em pontos custom, (2) garantir que o documento gravado no perfil chegue íntegro às integrações e (3) corrigir ERP, emissor de NF-e e planilhas que recebem esse CNPJ. Na prática, o maior risco não é a vitrine: é a integração a jusante que ainda trata CNPJ como número.

Validando CNPJ alfanumérico em JavaScript

Esta é a função que você reaproveita nas duas plataformas: ela normaliza a entrada, confere o formato com um regex que aceita letras nas 12 primeiras posições, rejeita base zerada e compara os dígitos verificadores calculados com os informados. Copie como está — cada linha foi conferida contra os vetores oficiais.

// Valor de cada caractere = código ASCII - 48 ('0'=0..'9'=9, 'A'=17..'Z'=42)
const PESO1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
const PESO2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];

const normalizar = (s) => (s || '').toUpperCase().replace(/[^A-Z0-9]/g, '');

function digito(base, pesos) {
  let soma = 0;
  for (let i = 0; i < base.length; i++) soma += (base.charCodeAt(i) - 48) * pesos[i];
  const resto = soma % 11;
  return resto < 2 ? 0 : 11 - resto;
}

function calcularDV(base12) {            // base12 = 12 primeiras posições
  const d1 = digito(base12, PESO1);
  const d2 = digito(base12 + d1, PESO2);
  return `${d1}${d2}`;
}

function validarCNPJ(cnpj) {
  const c = normalizar(cnpj);
  if (!/^[A-Z0-9]{12}[0-9]{2}$/.test(c)) return false;
  if (/^0{12}/.test(c)) return false;     // base zerada
  return calcularDV(c.slice(0, 12)) === c.slice(12);
}

// console.log(validarCNPJ('12.ABC.345/01DE-35')); // true
// console.log(calcularDV('12ABC34501DE'));         // "35"

VTEX: checkout custom e o campo corporateDocument

Na VTEX, o ponto real de extensão do front-end de checkout é a dupla checkout6-custom.js / checkout6-custom.css — substituída e versionada pelo app oficial Checkout UI Custom (vtex.checkout-ui-custom). É ali que você injeta JavaScript que roda na página do checkout, com acesso à vtexjs.checkout e ao orderForm. O CNPJ da empresa fica no perfil do cliente como clientProfileData.corporateDocument (junto de corporateName, tradeName, stateInscription e do flag isCorporate).

Como você não reescreve o validador nativo, a estratégia é aplicar uma validação complementar no campo custom e só liberar o avanço quando o documento passar na função golden. Escute o evento de atualização do orderForm e cheque o documento corporativo:

// checkout6-custom.js (servido pelo app Checkout UI Custom)
// Reaproveita validarCNPJ() do bloco acima.
$(window).on('orderFormUpdated.vtex', function (_evt, orderForm) {
  const doc = orderForm && orderForm.clientProfileData
    ? orderForm.clientProfileData.corporateDocument : null;
  if (!doc) return; // pessoa física ou ainda não preenchido

  const ok = validarCNPJ(doc);
  const $campo = $('#client-corporateDocument, [name="corporateDocument"]');
  $campo.toggleClass('error', !ok);

  if (!ok) {
    $campo.attr('aria-invalid', 'true');
    console.warn('CNPJ alfanumérico inválido no checkout:', doc);
  } else {
    $campo.removeAttr('aria-invalid');
  }
});

Nuvemshop (Tiendanube): validar via app/script

Na Nuvemshop, a customização de tema com LiquidJS é limitada e o checkout é majoritariamente controlado pela plataforma — não dá para trocar o validador nativo. O caminho suportado é o app com a API de Scripts (escopo write_scripts): você registra um script que é injetado na vitrine do lojista e executa no navegador do cliente, podendo ler campos por seletores HTML e validar de forma assíncrona. Os scripts disparam em onload ou onfirstinteraction. Para fluxos de pagamento próprios, existe ainda o Checkout SDK.

// Script registrado via API de Scripts da Nuvemshop (escopo write_scripts).
// Validação complementar de um campo custom de CNPJ no formulário.
document.addEventListener('blur', function (e) {
  const alvo = e.target;
  if (!alvo.matches('[name="cnpj"], [data-cnpj]')) return;

  const ok = validarCNPJ(alvo.value); // função golden injetada no mesmo script
  alvo.setCustomValidity(ok ? '' : 'CNPJ inválido');
  alvo.classList.toggle('cnpj-invalido', !ok);
}, true);

Como o checkout nativo é fechado, a regra prática é: valide onde você controla (campos custom, formulários de cadastro B2B, páginas de conta) e trate a vitrine como melhor esforço. A garantia de integridade fica no back-office.

Integrações: ERP, NF-e e o que recebe o CNPJ

É aqui que a maioria das lojas quebra. O CNPJ alfanumérico que entra na VTEX ou na Nuvemshop é repassado para ERP, emissor de NF-e, gateway antifraude, planilhas e BI. Audite cada conector: colunas de CNPJ devem ser texto (largura 14 sem máscara), nunca INT/BIGINT; comparações do tipo = 12345 e ordenação numérica passam a falhar. Confirme com o seu emissor de NF-e que ele aceita o documento alfanumérico — esse é o gargalo fiscal mais sério. Normalize sempre para maiúsculas antes de enviar.

Como testar

Perguntas frequentes

Dá para mudar a validação nativa de CNPJ da VTEX ou da Nuvemshop?

Não diretamente — são SaaS fechados. Você adiciona validação complementar por JavaScript (checkout custom na VTEX, API de Scripts na Nuvemshop) e ajusta campos custom. A validação nativa do documento é evoluída pela própria plataforma; acompanhe os anúncios delas até julho de 2026.

Onde a VTEX guarda o CNPJ da empresa?

No perfil do cliente dentro do orderForm, no campo clientProfileData.corporateDocument, ao lado de corporateName, tradeName, stateInscription e do flag isCorporate. Você lê e valida esse campo no checkout6-custom.js servido pelo app Checkout UI Custom.

Minha integração com ERP/NF-e vai quebrar com o CNPJ alfanumérico?

Vai, se algum ponto tratar CNPJ como número. Garanta colunas de texto (14 caracteres, maiúsculas), elimine comparações e ordenações numéricas e confirme com o emissor de NF-e que ele aceita o documento alfanumérico antes de emitir em produção.

Trabalha com outras plataformas? Veja também o tutorial de CNPJ alfanumérico no Magento 2 e o de CNPJ alfanumérico no WooCommerce/WordPress.