XML v11

The XML builder follows the Cape Verde e-Fatura Technical Manual v11.0 for the DFE envelope shape.

Envelope

Every generated DFE XML uses a compact UTF-8 XML 1.0 document with the root element below:

<Dfe xmlns="urn:cv:efatura:xsd:v1.0" Version="1.0" Id="{IUD}" DocumentTypeCode="{code}">

The package does not add namespace prefixes, comments, or formatting whitespace.

Document Element

Manual v11.0 requires the first child of Dfe to be the document-specific element. The current mapping is:

buildDfeXml() and efatura.buildDfeXml() use this mapping through dfeDocumentElementName().

Common Blocks

The document element contains the package-supported common blocks:

• Header fields: LedCode, Serie, DocumentNumber, IssueDate, and IssueTime.
• Transmission: numeric IssueMode, transmitter tax id, software identity, and optional contingency.
• Software: registered software code, name, and version.
• EmitterParty, ReceiverParty, optional PaymentParty, and TransportServiceProviderParty.
• Lines, including tax details.
• Totals.
• References, for credit, debit, receipt, return, and transport references.
• Contingency, when IssueMode is 2 or 3.
• ExtraFields, serialized from the typed ExtraFieldData schema as explicit XML blocks.

Event XML

The official enveloped-signature schema also defines an Event root. The package supports:

• FDC: fiscal document cancellation or annulment, targeting one or more IUD values.
• UDN: unused document number invalidation, targeting Year, LedCode, Serie, DocumentTypeCode, DocumentNumberStart, and DocumentNumberEnd.

Event IDs use the official 24-character pattern:

CV{repository}{YY}{MM}{DD}{HH}{mm}{ss}{transmitterNif}

const xml = efatura.buildEventXml({
  type: 'FDC',
  issueDateTime: '2026-02-08T11:30:00',
  issueReasonDescription: 'Documento emitido com dados incorretos.',
  iuds: [iud],
});

await efatura.validateEventXml(xml);

Official Validation

The manual states that systems must validate generated XML against the official XSDs published by the tax administration before submission. The official XSD package supplied to the project is bundled under resources/xsd/efatura/2024-05-27.

const efatura = createEfatura(config);

await efatura.validateDfeXml(xml, DocumentType.ElectronicInvoice);

The default XmllintXsdValidator validates against EnvelopedSignature.xsd. The test suite validates generated XML for all 9 DFE document types against the bundled official schema. Inject another XsdValidator when the application needs a different validation runner.