Como Testar NF-e, CT-e e MDF-e em Homologação sem Estresse

Se você desenvolve ou faz o controle de qualidade (QA) em ERPs, sistemas de gestão de transporte (TMS) ou plataformas de e-commerce, sabe que testar a integração com a SEFAZ é um dos maiores gargalos do projeto.

Ambientes oficiais de homologação do governo são frequentemente instáveis, exigem certificados digitais válidos que expiram nos momentos mais críticos e apresentam lentidões inexplicáveis. O resultado? Desenvolvedores e QAs estressados esperando respostas de servidores externos para validar uma simples alteração no fluxo de faturamento ou expedição.

Neste guia prático, vamos mostrar o passo a passo para montar uma estratégia de testes robusta e local, validando chaves de acesso de 44 dígitos, simulando rejeições da SEFAZ de forma programática e utilizando geradores de dados estruturados para acelerar seu pipeline de testes integrados.

1. A Anatomia da Chave de Acesso de 44 Dígitos

Antes de testar qualquer fluxo de Nota Fiscal Eletrônica (NF-e), Conhecimento de Transporte Eletrônico (CT-e) ou Manifesto Eletrônico de Documentos Fiscais (MDF-e), você precisa entender perfeitamente a chave de acesso de 44 dígitos que acompanha esses documentos.

A chave de acesso não é um número aleatório. Ela é uma string de 44 caracteres numéricos estruturada de forma lógica para identificar univocamente o documento fiscal perante a Receita Federal:

2. Validando o Dígito Verificador (Módulo 11) Localmente

O 44º dígito da chave de acesso é gerado a partir do cálculo de Módulo 11 sobre os primeiros 43 dígitos. A SEFAZ rejeita imediatamente qualquer XML cujo dígito verificador da chave não bata com o cálculo matemático.

Para economizar tempo e requisições à SEFAZ, sua aplicação deve validar essa chave no front-end ou no início do pipeline do back-end. Veja como funciona o algoritmo:

1. Tome os 43 dígitos iniciais da chave de acesso.
2. Multiplique cada dígito da direita para a esquerda por pesos que variam de 2 a 9 de forma cíclica (ou seja, 2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4...).
3. Some todos os produtos obtidos.
4. Divida a soma por 11 para obter o resto da divisão (resto = soma % 11).
5. Se o resto for 0 ou 1, o dígito verificador (DV) é 0.
6. Caso contrário, o DV será igual a 11 - resto.

Aqui está uma implementação JavaScript eficiente para validar chaves de acesso em suas ferramentas de testes:

function validarChaveAcesso(chave) {
  // Remove qualquer caractere não-numérico
  const chaveLimpa = chave.replace(/\D/g, '');

  // Uma chave de acesso válida possui exatamente 44 dígitos
  if (chaveLimpa.length !== 44) return false;

  // Separa os primeiros 43 dígitos e o dígito verificador final
  const baseChave = chaveLimpa.substring(0, 43);
  const dvInformado = parseInt(chaveLimpa.charAt(43));

  let soma = 0;
  let peso = 2;

  // Multiplica da direita para a esquerda
  for (let i = baseChave.length - 1; i >= 0; i--) {
    soma += parseInt(baseChave.charAt(i)) * peso;
    peso = peso === 9 ? 2 : peso + 1;
  }

  const resto = soma % 11;
  const dvCalculado = (resto === 0 || resto === 1) ? 0 : 11 - resto;

  return dvCalculado === dvInformado;
}

// Exemplo de uso
const chaveNfe = "35260600000000000191550010000123451876543214";
console.log(validarChaveAcesso(chaveNfe)); // true

3. Simulando Rejeições da SEFAZ de Forma Programática

Testar cenários de sucesso (o chamado "caminho feliz") é simples. O verdadeiro desafio é garantir que o sistema trate essas rejeições adequadamente quando a SEFAZ rejeita um lote. Em vez de tentar alterar dados reais cadastrados no portal do contribuinte ou alterar parâmetros tributários complexos para forçar erros reais, você deve simular essas rejeições de forma mockada.

Aqui estão as rejeições mais comuns que sua suite de testes deve validar:

• Rejeição 203: Emissor não habilitado para emissão da NF-e (Simule bloqueando temporariamente as credenciais fiscais no ambiente de sandbox).
• Rejeição 225: Falha no Schema XML (Simule enviando tags obrigatórias vazias ou desordenadas e validando através de um validador local de XSD).
• Rejeição 204: Duplicidade de NF-e (Simule tentando reemitir uma chave de acesso que já foi marcada como "autorizada" em seu banco de dados local mockado).
• Rejeição 610: Código de Município do tomador divergente do cadastrado na UF (Muito comum em CT-e. Simule passando um código IBGE inválido para o destinatário).

4. A Importância de Usar Geradores de Dados Estruturados

Ao realizar testes de integração ou carga, você precisa de centenas ou milhares de documentos fiscais válidos estruturados. Preencher esses dados manualmente no formato XML é inviável.

A solução ideal é utilizar geradores de dados estruturados para criar a massa de testes de forma automatizada. Ferramentas que geram a estrutura completa do documento XML de forma matematicamente válida trazem benefícios gigantescos:

1. Velocidade de Setup: Em vez de gastar minutos criando um cenário fiscal complexo, gere em milissegundos uma estrutura pronta para envio.
2. Evita Falsos Negativos: Erros de digitação em chaves de acesso, CNPJs ou Inscrições Estaduais causam rejeições bobas que atrasam a validação de lógicas de negócio mais complexas.
3. Testes de Carga Realistas: Permite injetar nos seus sistemas XMLs com chaves de acesso reais e pesos válidos para analisar a capacidade de processamento paralelo e persistência em banco.

Se você precisa de uma ferramenta rápida e local para gerar massas de teste de documentos fiscais de forma limpa, o DevThru oferece utilitários gratuitos e processados diretamente no seu navegador, sem envio de dados a servidores terceiros:

• Crie notas fiscais válidas com o Gerador de NF-e do DevThru.
• Gere conhecimentos de transporte consistentes no Gerador de CT-e.
• Estruture manifestos eletrônicos válidos através do Gerador de MDF-e.
• Valide se a estrutura dos seus arquivos XML está em conformidade com as regras gerais com o nosso Validador XML.

Conclusão

Montar uma estratégia de homologação fiscal sem estresse depende de duas ações fundamentais: desacoplar-se da dependência direta de redes externas da SEFAZ por meio de validações e simulações locais (como a validação de chave por Módulo 11) e automatizar a criação de massa de testes com geradores estruturados adequados.

Ao implementar essas práticas, você garante entregas mais rápidas, pipelines de CI/CD estáveis e um fluxo de desenvolvimento muito mais previsível.