TL;DR — Resumo Rápido

Erro de validação de addenda CFDI: corrija erros de XML, namespace incorreto, esquema XSD e rejeição do PAC ao gerar faturas com addenda no Aspel SAE.

Ao enviar uma fatura eletrônica para o Walmart, Liverpool ou Volkswagen do México, o sistema retorna “Error de validación en la addenda” (erro de validação na addenda) ou o portal do fornecedor rejeita o CFDI indicando que a addenda não corresponde ao esquema esperado. Esse erro é frequente ao configurar pela primeira vez a addenda de um novo cliente ou quando o cliente atualiza seus requisitos. Neste artigo explicamos o que são addendas, por que falham e como resolver o problema passo a passo no Aspel SAE e em outros sistemas de faturação.

O Erro

As mensagens de erro relacionadas com addendas aparecem em diferentes momentos do processo de faturação:

  • “Error de validación en la addenda” — mensagem genérica no Aspel SAE ao tentar gerar o CFDI
  • “Namespace não declarado” ou “Prefix not bound” — o XML da addenda referencia um namespace não definido no cabeçalho do CFDI
  • “O elemento ‘Addenda’ não é válido de acordo com o seu DTD/Esquema” — a estrutura XML não corresponde ao XSD esperado pelo cliente
  • “CFDI rejeitado pelo portal — addenda não reconhecida” — o CFDI é carimbado corretamente pelo PAC, mas o portal do cliente o rejeita na sua própria validação
  • “Campo obrigatório ausente na addenda” — falta um elemento obrigatório definido no XSD do cliente (por exemplo, o número de ordem de compra na addenda do Walmart)
  • “Versão de addenda não suportada” — o cliente atualizou seu XSD e o sistema ainda gera a versão anterior

Esses erros aparecem ao gerar faturas em Faturação > Faturas quando o cliente tem addenda configurada, ou ao carregar o XML no portal de fornecedores do cliente após o carimbo.

Causa do Problema

As addendas são extensões XML opcionais que grandes compradores corporativos exigem de seus fornecedores para incluir informações adicionais não cobertas pelo padrão do SAT: número de ordem de compra, número de fornecedor, departamento de compras, informações logísticas, entre outros. O SAT permite sua inclusão dentro do elemento <cfdi:Addenda>, mas não as valida; a responsabilidade pela estrutura correta recai sobre o fornecedor.

Namespace incorreto ou não declarado. Cada addenda corporativa tem seu próprio namespace XML (uma URI que identifica o esquema). Se o namespace no seu XML não corresponder exatamente ao definido no XSD do cliente, a validação falha. Até mesmo uma barra no final ou um número de versão diferente na URL o invalida.

XSD desatualizado. Os clientes atualizam periodicamente seus requisitos de addenda. Se o modelo no Aspel SAE ou no seu sistema foi configurado com a versão anterior do XSD, os novos campos obrigatórios não estarão presentes e a validação falhará.

Campos obrigatórios ausentes ou com formato incorreto. Cada cliente define seus próprios campos obrigatórios. O Walmart México exige um número de fornecedor com 10 dígitos e um número de pedido com 10 caracteres alfanuméricos. A Liverpool exige o número do departamento. A Volkswagen exige o código de material Audi/VW em formato específico. Se algum campo estiver ausente ou tiver um formato diferente do esperado, o XSD o rejeita.

Posição incorreta da addenda no XML. A addenda deve ser o último elemento dentro de <cfdi:Comprobante>, depois de todos os complementos. Alguns sistemas de faturação a inserem na posição incorreta, o que invalida o XML completo.

Incompatibilidade de versão de addenda com a versão do CFDI. Quando se migrou do CFDI 3.3 para o CFDI 4.0, alguns XSD de addenda precisaram ser atualizados para compatibilidade. Se o cliente não atualizou o XSD ou você não atualizou o modelo, haverá conflitos de versão.

Solução Passo a Passo

1. Obter o XSD e a documentação vigente do cliente

Antes de qualquer configuração, acesse o portal de fornecedores do seu cliente e baixe:

  • O XSD oficial da addenda (pode haver um por tipo de documento: fatura, nota de crédito, etc.)
  • A documentação de campos obrigatórios e seus formatos
  • Um exemplo de CFDI com addenda corretamente formada

Se você não tiver acesso ao portal, entre em contato com a equipe de contas a pagar do cliente para que forneça os materiais atualizados. Nunca configure uma addenda com base em documentos de terceiros não oficiais.

2. Configurar a addenda no Aspel SAE

No Aspel SAE, vá a Configuração > Faturação Eletrônica > Addendas:

  1. Verifique se o seu cliente aparece na lista de addendas predefinidas
  2. Se aparecer, selecione-a e preencha os campos solicitados
  3. Se não aparecer, use Addenda personalizada e importe o modelo XML do cliente
  4. Certifique-se de que os campos mapeados correspondam aos dados corretos dos seus documentos

Para addendas não suportadas nativamente pelo Aspel SAE, muitos provedores do cliente (ou o próprio cliente) oferecem modelos pré-configurados ou complementos que podem ser instalados no SAE.

3. Validar o XML gerado contra o XSD

Gere uma fatura de teste e localize o arquivo XML gerado (normalmente na pasta de comprovantes do SAE). Valide-o com estas ferramentas:

Usando xmllint (linha de comando):

xmllint --schema addenda_cliente.xsd meu_cfdi_com_addenda.xml --noout

Usando Notepad++ com XML Tools:

  1. Abra o XML no Notepad++
  2. Vá a Plugins > XML Tools > Validate Now
  3. Selecione o XSD do cliente quando solicitado

Online:

  • FreeFormatter.com > XML Validator — permite carregar o XML e o XSD para validação imediata

Corrija cada erro reportado: elementos ausentes, tipos de dados inválidos, atributos obrigatórios ausentes ou namespace mal definido.

4. Verificar a declaração do namespace

Abra o XML do CFDI com qualquer editor de texto e localize o elemento <cfdi:Addenda>. A addenda deve declarar seu namespace no elemento raiz do CFDI (<cfdi:Comprobante) ou no próprio elemento da addenda:

<cfdi:Addenda>
  <wmm:WalmartMexico xmlns:wmm="http://www.walmart.com.mx/esquemas/..." version="1.0">
    <wmm:NumProveedor>1234567890</wmm:NumProveedor>
    <wmm:NumOrden>OC-2026-001</wmm:NumOrden>
  </wmm:WalmartMexico>
</cfdi:Addenda>

Compare a URI do namespace (http://www.walmart.com.mx/esquemas/...) com a que consta no XSD baixado do cliente. Elas devem ser idênticas, caractere por caractere.

5. Testar no sandbox do PAC

Antes de emitir o CFDI em produção, faça o upload para o ambiente de testes do seu PAC:

  • Finkok: portal de testes em sandbox.finkok.com
  • SW Sapien: ambiente demo disponível no portal de desenvolvedores
  • Edicom: sandbox disponível com suas credenciais de produção em modo de teste

O PAC validará o CFDI completo. Se a addenda causar XML malformado, o PAC o rejeitará com erro 301 (XML malformado). Se o PAC o aceitar mas o cliente o rejeitar, o problema está na validação interna do portal do cliente (regras de negócio, não de estrutura XML).

Solução Alternativa

Se não for possível modificar a configuração do Aspel SAE diretamente, uma alternativa é gerar o CFDI sem addenda pelo SAE e depois adicionar a addenda programaticamente antes do carimbo, usando um script ou uma ferramenta de transformação XML (XSLT). Alguns integradores e escritórios contábeis usam esse fluxo quando a addenda do cliente é muito complexa ou o SAE não a suporta nativamente.

Outra alternativa é trabalhar diretamente com o provedor de tecnologia autorizado do cliente. Por exemplo, o Walmart México trabalha com provedores de EDI como GS1 México, Soltec e TCI Commerce, que oferecem soluções de addenda pré-validadas e atualizadas com os últimos requisitos.

Prevenção

  • Baixe o XSD atualizado sempre que o cliente notificar mudanças. Grandes compradores enviam comunicados a seus fornecedores quando atualizam requisitos; assine os boletins de fornecedores.
  • Valide o XML de cada nova addenda antes de ir para produção. Nunca presuma que a configuração anterior funciona com uma nova versão do XSD.
  • Guarde uma cópia do XSD com que a addenda foi configurada. Assim você pode comparar versões quando o cliente reportar rejeições.
  • Sempre teste no sandbox do PAC antes da produção. Um CFDI com addenda malformada rejeitado em produção pode atrasar o pagamento da fatura.
  • Mantenha o Aspel SAE atualizado. A Aspel publica atualizações que incluem novas versões de addendas de clientes frequentes como Walmart, Liverpool e OEMs automotivos.
  • Documente os mapeamentos de campo. Registre qual campo do SAE corresponde a cada elemento da addenda do cliente para facilitar atualizações futuras.

Problemas Relacionados

O CFDI é carimbado mas o portal do cliente o rejeita. Isso ocorre quando a addenda é XML válido segundo o XSD, mas os valores dos campos não passam pelas regras de negócio do cliente (por exemplo, um número de pedido que não existe no ERP deles). Solução: peça à equipe de contas a pagar do cliente o erro específico exibido no sistema deles.

O Aspel SAE não gera a addenda mesmo estando configurado. Verifique se o campo “Addenda” ou “Cliente com addenda” está marcado no documento (fatura). Alguns clientes precisam ser configurados individualmente no catálogo de clientes do SAE para que a addenda seja gerada automaticamente.

O PAC rejeita com erro “301 - XML malformado” apenas quando há addenda. Isso indica que a addenda introduz caracteres inválidos em XML (como &, <, > sem escape) ou que o namespace não está corretamente declarado. Exporte o XML, abra-o em um editor e verifique se o bloco <cfdi:Addenda> é XML bem formado.

A addenda da VW ou de um OEM automotivo tem campos desconhecidos. Os OEMs automotivos (Volkswagen, General Motors, Stellantis) geralmente exigem addendas com dados de ordem de produção, materiais e plantas. A documentação técnica é extensa; contate diretamente o departamento de contas a pagar do OEM ou seu provedor de EDI autorizado para obter a especificação completa e exemplos.

Resumo

  • Addendas são extensões XML que grandes clientes exigem no CFDI para dados adicionais não cobertos pelo SAT
  • Os erros mais comuns são: namespace incorreto, campos obrigatórios ausentes, XSD desatualizado e posição incorreta no XML
  • Sempre baixe o XSD oficial do portal de fornecedores do cliente antes de configurar a addenda
  • Valide o XML gerado contra o XSD com xmllint, Notepad++ ou um validador online antes de carimbar
  • Teste no sandbox do PAC antes de emitir em produção para evitar rejeições que atrasem o pagamento
  • Se o Aspel SAE não suportar a addenda do seu cliente, considere o fluxo de addenda externa ou contate o provedor de EDI do cliente

Artigos Relacionados