Technical Briefing: Cape Verde e-Fatura

This document is the project reference for implementing @akira-io/efatura. It consolidates the supplied official Cape Verde Electronic Invoicing System Technical Manual v11.0.

It is an engineering reference, not a legal substitute for the official DNRE manual, XSD files, middleware documentation, or certificate requirements.

Executive Summary

The Cape Verde e-Fatura project, managed by DNRE under the Ministry of Finance, defines the digital representation, transmission, and validation of fiscal documents. The system replaces paper invoices with structured XML documents that preserve authenticity, integrity, and non-repudiation.

Key implementation points:

Electronic Fiscal Documents must be XML 1.0 files encoded as UTF-8.
XML structure must follow the official XSD schemas.
Digital signatures are mandatory for authenticity and integrity.
Transmission uses secure HTTPS channels.
Every DFE is identified by a 45-character IUD.
IUD verification uses the Luhn formula.
Supported processing modes are Online, Offline, and Off.
Integration can use the Electronic Platform APIs or the DNRE middleware.

Conceptual Pillars

Format

Electronic invoices and equivalent documents are XML text files. The structure is defined by official XSD documents published through the e-Fatura portal.

Communication

Transmission to the Tax Administration uses the internet over HTTPS with TLS.

Security

The system uses digital signatures to guarantee authenticity and integrity.

Taxpayers must use digital certificates from the ICP-CV hierarchy.
Files are hashed with SHA-256.
The hash is encrypted with the emitter private key.
The signature is embedded in the XML under the Signature element.
The target signature profile is XAdES-BES.

Processing

The Electronic Platform validates documents synchronously.

Validation includes:

XML structure and data types.
Digital signature verification.
NIF and code validation.
Mathematical consistency for taxes, totals, and calculations.

For Cabo Verde taxpayers, the official stTaxIdCV XSD pattern is [1-9][0-9]{8}: exactly 9 digits, with the first digit between 1 and 9, and no formatting characters. Existence in the fiscal registry is a PE/DNRE validation, not a local checksum.

Electronic Fiscal Documents

Code	Acronym	Document Type	Description
1	FTE	Fatura Eletronica	Electronic invoice for goods or services.
2	FRE	Fatura Recibo	Invoice receipt when invoice and payment dates coincide.
3	TVE	Talao de Venda	Sales receipt for final consumers.
4	RCE	Recibo Eletronico	Electronic receipt, including rent receipts.
5	NCE	Nota de Credito	Credit note for returns, errors, or adjustments.
6	NDE	Nota de Debito	Debit note referencing an original invoice.
7	DTE	Documento de Transporte	Transport document for goods movement.
8	DVE	Nota de Devolucao	Return note for returned merchandise.
9	NLE	Nota de Lancamento	Launch note for third-party facts, including banking and insurance use cases.

IUD

The IUD is a 45-character identifier for a DFE.

Format:

[Country][Repository][YY][MM][DD][NIF][LED][Type][DocumentNumber][RandomCode][DV]

Field lengths:

Field	Length	Rule
Country	2	Always `CV`.
Repository	1	`1` for production, `2` for homologation, `3` for test.
Year	2	Issue year, for example `26` for 2026.
Month	2	Issue month.
Day	2	Issue day.
NIF	9	Emitter tax identifier.
LED	5	Emission logic code, left-padded with zeros.
Type	2	Document type code, left-padded with zero.
DocumentNumber	9	Sequential document number, left-padded with zeros.
RandomCode	10	Random numeric code generated by the system.
DV	1	Luhn check digit over the numeric payload after `CV`.

Implementation requirements:

IUD length must be exactly 45 characters.
Document numbering must be sequential by NIF, year, LED, and document type.
Numbering restarts at 1 each civil year.
The random code prevents unauthorized IUD generation.
The check digit is calculated with the Luhn formula.

XML Structure

The root element is Dfe.

Root namespace:

urn:cv:efatura:xsd:v1.0

Required root attributes:

Attribute	Rule
`Version`	`1.0`
`Id`	IUD
`DocumentTypeCode`	Numeric document type code from `1` to `9`

Optimization guidance:

Use the default namespace without tag prefixes.
Do not include XML comments.
Do not include unnecessary whitespace.
Do not pretty-print production XML.
Avoid non-significant zeroes.

Data Groups

XML files are organized into these groups:

Identification: unique document data.
Emitter and receiver: NIF, name, address, and contacts.
Items and lines: quantities, unit prices, discounts, and taxes.
Totals: gross, net, tax, withholding, and payable amounts.
Transmission: software identity and emission mode.
Software: Code, Name, and Version.

Emitter email and phone are mandatory for the supported DFE XML output.

Tax Handling

Supported tax categories:

IVA: Value Added Tax.
IS: Stamp Tax.
IR: Income Tax withholding.
NA: Not applicable.

Critical rule:

When TaxTypeCode is NA, TaxExemptionReasonCode is mandatory.

Processing Modes

Supported modes:

Online: standard real-time emission.
Offline: local technical failure with later synchronization.
Off: complete technical failure, including power failure.

Date tolerance:

Online mode allows between plus 1 hour and minus 24 hours relative to the Electronic Platform.
Contingency modes allow up to 7 days of delay.

Middleware

The DNRE middleware can simplify signing, compression, and transmission.

Default local URL:

https://localhost:3443

Required communication header:

cv-ef-mw-core-transmitter-key

Transmission:

Send DFE files with POST /v1/dfe.
The request payload is a ZIP file using Deflate compression.
The ZIP contains XML files.
Each XML filename must use {IUD}.xml.

Platform APIs

The Electronic Platform exposes REST APIs over HTTPS.

Known API categories:

Authentication through OpenID Connect and OAuth Authorization Code Flow with PKCE.
Emission through ZIP upload.
Reading DFEs by IUD.
Searching by date or NIF.
Events such as cancellation, annulment, and document number invalidation.

Events

The official XSD defines Event as a root element alongside Dfe.

Supported event codes:

FDC: fiscal document cancellation or annulment. The event targets one or more IUD values.
UDN: unused document number invalidation. The event targets a document-number interval by year, LED, series, document type, and start/end document numbers.

Event IDs follow the 24-character XSD pattern:

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

Self-Billing

Version 10.0 supports self-billing.

Rules:

The buyer requests an authorization code through the platform.
The code is sent to the seller registered email or mobile phone.
XML must include a SelfBilling block with AuthorizationId and AuthorizationCode.

Auxiliary Fiscal Document

The DFA is the customer-facing fiscal representation used in contingency modes or when requested by the customer.

Requirements:

It must include a QR Code.
The default QR Code URL format is https://pe.efatura.cv/dfe/view/{IUD}. Configure dfaBaseUrl if the PE endpoint changes.
In contingency modes, it must display EMITIDO EM CONTINGENCIA.
The package PDF renderer includes fiscal header data, parties, line summary, totals, QR Code, and the contingency notice.

Implementation Checklist

Map document acronyms to numeric DFE codes.
Generate and validate IUD values.
Generate compact UTF-8 XML with the Dfe root.
Validate fiscal data before XML generation.
Provide official XSD validation through the XsdValidator contract.
Provide XAdES-BES signing through the XmlSigner contract once certificate handling is available.
Package XML files into ZIP using Deflate.
Submit middleware payloads through MiddlewareTransport.
Submit PE payloads through PlatformTransport.
Generate DFA QR Code URLs and PDF output.
Add official golden vectors through GoldenVectorRepository.