TL;DR — Quick Summary

CFDI addenda validation error: fix XML structure, incorrect namespace and PAC rejection when generating electronic invoices with addenda in Aspel SAE.

When submitting an electronic invoice to Walmart, Liverpool, or Volkswagen de México, the system returns “Error de validación en la addenda” (addenda validation error), or the supplier portal rejects the CFDI stating that the addenda does not match the expected schema. This error is common when configuring a new client’s addenda for the first time, or when the client updates their requirements. This article explains what addendas are, why they fail, and how to resolve the issue step by step in Aspel SAE and other invoicing systems.

The Error

Addenda-related error messages appear at different stages of the invoicing process:

  • “Error de validación en la addenda” — generic message in Aspel SAE when trying to generate the CFDI
  • “Namespace not declared” or “Prefix not bound” — the addenda XML references a namespace not defined in the CFDI header
  • “The element ‘Addenda’ is not valid according to its DTD/Schema” — the XML structure does not match the XSD expected by the client
  • “CFDI rejected by portal — addenda not recognized” — the CFDI stamps correctly with the PAC but the client portal rejects it during its own validation
  • “Required field missing in addenda” — a mandatory element defined in the client’s XSD is absent (for example, the purchase order number in Walmart’s addenda)
  • “Addenda version not supported” — the client updated their XSD and your system is still generating the previous version

These errors appear when generating invoices from Invoicing > Invoices when the client has an addenda configured, or when uploading the XML to the client’s supplier portal after stamping.

Root Cause

Addendas are optional XML extensions that large corporate buyers require their suppliers to include in order to carry additional information not covered by the SAT standard: purchase order number, supplier number, purchasing department, logistics information, and more. The SAT allows their inclusion within the <cfdi:Addenda> element but does not validate them; the responsibility for correct structure falls on the supplier.

Incorrect or undeclared namespace. Every corporate addenda has its own XML namespace (a URI that identifies the schema). If the namespace in your XML does not match the one defined in the client’s XSD exactly, validation fails. Even a trailing slash or a different version number in the URL will invalidate it.

Outdated XSD. Clients periodically update their addenda requirements. If your Aspel SAE template or system was configured with the previous version of the XSD, newly required mandatory fields will be absent and validation will fail.

Missing required fields or incorrect formats. Each client defines its own mandatory fields. Walmart México requires a 10-digit supplier number and a 10-character alphanumeric order number. Liverpool requires a department number. Volkswagen requires the Audi/VW material number in a specific format. If any field is missing or has a different format than expected, the XSD rejects it.

Incorrect addenda position in the XML. The addenda must be the last element inside <cfdi:Comprobante>, after all complements. Some invoicing systems insert it in the wrong position, which invalidates the entire XML.

Addenda version incompatibility with the CFDI version. When migrating from CFDI 3.3 to CFDI 4.0, some addenda XSD files needed to be updated for compatibility. If the client did not update their XSD, or you did not update the template, version conflicts will arise.

Step-by-Step Solution

1. Obtain the client’s current XSD and documentation

Before any configuration, log in to your client’s supplier portal and download:

  • The official addenda XSD (there may be one per document type: invoice, credit note, etc.)
  • Required-fields documentation with their formats
  • A sample CFDI with a correctly formed addenda

If you do not have portal access, contact your client’s accounts payable team to provide you with the updated materials. Never configure an addenda based on unofficial third-party documents.

2. Configure the addenda in Aspel SAE

In Aspel SAE, go to Configuration > Electronic Invoicing > Addendas:

  1. Check whether your client appears in the predefined addenda list
  2. If it does, select it and fill in the requested fields
  3. If it does not, use Custom addenda and import the client’s XML template
  4. Make sure the mapped fields correspond to the correct data from your documents

For addendas not natively supported by Aspel SAE, many client providers (or the client itself) offer preconfigured templates or plug-ins that can be installed in SAE.

3. Validate the generated XML against the XSD

Generate a test invoice and locate the XML file generated (usually in the SAE receipts folder). Validate it with these tools:

Using xmllint (command line):

xmllint --schema client_addenda.xsd my_cfdi_with_addenda.xml --noout

Using Notepad++ with XML Tools:

  1. Open the XML in Notepad++
  2. Go to Plugins > XML Tools > Validate Now
  3. Select the client’s XSD when prompted

Online:

  • FreeFormatter.com > XML Validator — allows you to upload both the XML and the XSD for immediate validation

Fix every reported error: missing elements, invalid data types (a numeric field containing letters, a date in the wrong format), missing required attributes, or a malformed namespace.

4. Verify the namespace declaration

Open the CFDI XML with any text editor and locate the <cfdi:Addenda> element. The addenda must declare its namespace either in the CFDI root element (<cfdi:Comprobante) or in the addenda element itself:

<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 the namespace URI (http://www.walmart.com.mx/esquemas/...) with the one in the XSD downloaded from the client. They must be character-for-character identical.

5. Test in the PAC sandbox

Before issuing the CFDI in production, upload it to your PAC’s test environment:

  • Finkok: test portal at sandbox.finkok.com
  • SW Sapien: demo environment available on their developer portal
  • Edicom: sandbox available with your production credentials in test mode

The PAC will validate the complete CFDI. If the addenda causes the XML to be malformed, the PAC will reject it with error 301 (malformed XML). If the PAC accepts it but the client rejects it, the problem lies in the client portal’s internal validation (business rules, not XML structure).

Alternative Solution

If you cannot modify the Aspel SAE configuration directly, an alternative is to generate the CFDI without the addenda from SAE and then add the addenda programmatically before stamping using a script or an XML transformation tool (XSLT). Some integrators and accounting firms use this flow when the client’s addenda is too complex or is not natively supported by SAE.

Another option is to work directly with the client’s authorized technology provider. For example, Walmart México works with EDI providers such as GS1 México, Soltec, and TCI Commerce, which offer pre-validated addenda solutions that are already updated to the latest requirements.

Prevention

  • Download the updated XSD every time the client notifies you of changes. Large buyers send notices to their suppliers when they update requirements; subscribe to their supplier bulletins.
  • Validate the XML of every new addenda before going to production. Never assume the previous configuration works with a new XSD version.
  • Keep a copy of the XSD used when the addenda was configured. This lets you compare versions when the client reports rejections.
  • Always test in the PAC sandbox before going to production. A CFDI with a malformed addenda rejected in production can delay invoice payment.
  • Keep Aspel SAE updated. Aspel publishes updates that include new versions of addendas for frequent clients such as Walmart, Liverpool, and automotive OEMs.
  • Document field mappings. Record which SAE field corresponds to each addenda element for the client, to make future updates easier.

The CFDI stamps but the client portal rejects it. This happens when the addenda is valid XML according to the XSD but the field values do not pass the client’s business rules (for example, a purchase order number that does not exist in their ERP). Solution: ask the client’s accounts payable team for the specific error shown in their system.

Aspel SAE does not generate the addenda even though it is configured. Verify that the “Addenda” or “Client with addenda” field is checked in the document (invoice). Some clients must be configured individually in the SAE customer catalog for the addenda to be generated automatically.

The PAC rejects with error “301 - Malformed XML” only when there is an addenda. This indicates that the addenda introduces characters that are invalid in XML (such as unescaped &, <, >) or that the namespace is not correctly declared. Export the XML, open it in an editor, and verify that the <cfdi:Addenda> block is well-formed XML.

The VW or automotive OEM addenda has unknown fields. Automotive OEMs (Volkswagen, General Motors, Stellantis) typically require addendas with production order data, materials, and plant codes. Their technical documentation is extensive; contact the OEM’s accounts payable department or their authorized EDI provider directly to obtain the complete specification and examples.

Summary

  • Addendas are XML extensions that large clients require in the CFDI for additional data not covered by the SAT
  • The most common errors are: incorrect namespace, missing required fields, outdated XSD, and incorrect position in the XML
  • Always download the official XSD from the client’s supplier portal before configuring the addenda
  • Validate the generated XML against the XSD using xmllint, Notepad++, or an online validator before stamping
  • Test in the PAC sandbox before issuing in production to avoid rejections that delay payment
  • If Aspel SAE does not support your client’s addenda, consider an external addenda workflow or contact the client’s EDI provider