Italy Documento Commerciale / Registratore Telematico (RT) System

Research and design document for Italy retail POS fiscalization via the Documento Commerciale and Registratore Telematico system.

Overview

Italy's retail POS fiscalization operates through corrispettivi telematici (electronic daily takings). Merchants must electronically memorize and transmit daily transaction data to the Agenzia delle Entrate (AdE) via certified devices or software.

Three approaches exist:

Approach	Description	Use Case
Physical RT	Certified hardware fiscal register at each POS	Single-location retail
Server RT	Centralized software register for 3+ checkout points	Large retailers, chains
Software Solution (SSW)	Fully software-based, from January 1, 2026	ISV-integrated POS, cloud POS

Zyntem's path is the Software Solution (SSW), introduced by Legislative Decree 1/2024 and Provvedimento of March 7, 2025. This is the modern, ISV-friendly approach that aligns with our embedded engine architecture.

Documento Commerciale (DC) — The Italian Fiscal Receipt

XML Schema

The Documento Commerciale is defined by Allegato-SSW-DocumentoCommerciale.xsd.

Namespace: http://ivaservizi.agenziaentrate.gov.it/docs/xsd/corrispettivi/v1.0 Format version: DSW10 (Software Solution format)

Key Complex Types

Type	Purpose	Key Fields
DatiConfigurazioneDCType	Header/config	Format (DSW10), hash references, PEM matricola
CedentePrestatoreType	Seller info	Partita IVA (11 digits), Codice Fiscale (11-16 chars), legal name, address
DocumentoCommercialeType	Transaction body	Progressive number, VAT summaries, line items, payment breakdown
ElementiContabiliType	Line items	Description, quantity, unit price, discounts, VAT/exemption
VenditaType	Sale totals	Cash paid, electronic paid, discounts, ticket amounts
ResoAnnulloType	Return/cancel	Original device matricola, original date, original progressive number
RiepilogoType	VAT summary per rate	Taxable amount, VAT rate or Natura code
DatiLotteriaType	Lottery integration	2D barcode data, lottery code

Required Fields

Per Decree of December 7, 2016:

• Issue date and time (ISO 8601 dateTime)
• Sequential number (format: NNNN-NNNN, NumeroProgressivoType)
• Issuer information: company name, legal name, full name, business location
• Partita IVA (VAT number, 11 digits)
• Description of goods or services per line item
• Quantity and unit price per line item
• Transaction totals
• IVA breakdown by rate (Riepilogo block)
• Payment method (cash, electronic, ticket)
• PEM matricola (emission point serial number, 11 chars, pattern ^[A-Z0-9]{4}-[A-Z0-9]{6}$)
• Customer Codice Fiscale — only if requested by customer

IVA/VAT Rates

Rate	Application
22%	Standard rate (most goods/services)
10%	Reduced (tourism, some food, renovations)
5%	Reduced (certain food items, social services)
4%	Super-reduced (basic necessities: bread, milk)

For non-IVA operations, Natura codes replace AliquotaIVA:

Code	Meaning
N1	Excluded per Art. 15, D.P.R. 633/1972
N2	Non-subject to VAT
N3	Non-taxable
N4	Exempt
N5	Margin scheme (regime del margine)
N6	Other non-IVA operations

Payment Types

The totals block breaks payments into:

• PagatoContanti — Cash payments
• PagatoElettronico — Electronic payments (cards, bank transfers, prepaid)
• ScontoApagare — Discount amounts and multi-use voucher payments (gross of VAT)
• Ticket — Ticket/voucher payments (amount + count)

Vendita (Sale) vs Reso (Return)

Vendita (sale): Standard transaction. VenditaType contains total payment, discounts, cash/electronic breakdown.

Reso/Annullo (return/cancellation): Uses ResoAnnulloType:

• TipologiaRAType: "R" (return/reso) or "A" (cancellation/annullo)
• Mandatory reference to original: original device matricola, original date, original progressive number
• Each line must show the applicable IVA rate
• Return descriptors: "POS", "VR" (vuoto a rendere), or "ND"

BeneServizioType distinguishes "B" (goods) vs "S" (services).

Daily Closure (Chiusura Giornaliera)

• End-of-day "azzeramento" (zeroing/closure)
• Generates an XML file containing daily data subdivided by closures and VAT rates
• XML is electronically sealed with the merchant's certificate
• Transmission window: random time within 00:00-22:00
• Maximum deadline: 12 days from transaction date
• File size limit: 1 MB maximum

Lottery Integration

Deferred lottery:

• Customer provides lottery code (0-16 chars) obtained from government portal
• Recorded in DatiLotteriaType.CodiceLotteriaType

Instant lottery (from January 2023):

• No customer code needed
• QR code (CodiceBidimensionaleLIType, 0-64 chars) printed on receipt
• For transactions >= 1 EUR paid entirely electronically
• Customer scans QR with government app to check prizes

Software Solution (SSW) Architecture

The SSW approach is Zyntem's target implementation path. Introduced for January 1, 2026.

Three-Actor Model

Actor	Role	Identifier
Produttore (Producer)	Develops the software, must be VAT-liable	Accredited with AdE
Erogatore (Provider)	Distributes software, provides support	CAU code (4 chars, ^[A-Z0-9]{4})
Operatore (Merchant)	Uses the software for transactions	Partita IVA

Zyntem is both Produttore and Erogatore — we develop and distribute through ISV partners.

PEM (Punto di Emissione / Emission Point)

Each POS instance is a PEM:

• Matricola pattern: ^[A-Z0-9]{4}-[A-Z0-9]{6}$ (11 characters)
• Must be censused (registered) and activated via API before use
• Each PEM maps to a fiscal location in our system

Certification Process

1. Producer accreditation with AdE
2. Software built conforming to AdE Specifiche Tecniche v1.3
3. SBOM (Software Bill of Materials) per Allegato-SSW-LineeGuidaSBOM
4. Archive compliance per LineeGuida_Archivio for data retention
5. Audit APIs exposed per Allegato-SSW-Api Rest Audit Esposti Erogatore
6. Independent Certifier produces digitally signed compliance certification
7. Submit certification to AdE
8. Commission for Fiscal Measuring Devices evaluates and approves
9. Only after approval can distribution begin

Security — Advanced Electronic Seals

Based on eIDAS regulation:

• X.509 certificates from accredited QTSP (Qualified Trust Service Provider)
• Merchant's Partita IVA embedded in certificate Subject field
• Replaces physical RT's hardware-based sealing
• Provides origin verification, tamper detection, legal validity

Dual-Module Architecture

• MF1: Emission and payment processing
• MF2: Data memorization and transmission to tax authorities

AdE REST API — Software Solution Endpoints

All SSW APIs use REST with OpenAPI 3.0.3 specifications.

Corrispettivi Transmission

Method	Path	Content-Type	Purpose
POST	/corrispettivi	application/octet-stream	Submit daily corrispettivi (binary)
GET	/corrispettivi/{idPresaInCarico}/stato	—	Check processing status
GET	/corrispettivi/{idPresaInCarico}/esito	—	Retrieve acquisition results (binary)

PEM Census & Activation

Method	Path	Content-Type	Purpose
POST	/censimenti/pem/richieste	application/octet-stream	Register new PEM
GET	/censimenti/pem/richieste/{id}/stato	—	Check registration status
GET	/censimenti/pem/richieste/{id}/esito	—	Retrieve activation outcome

PEM State Communication

Method	Path	Content-Type	Purpose
POST	/pel/{cau}/pem/{matricola}/stato	application/json	Report PEM state change

Audit APIs

Method	Path	Purpose
POST	/audit/dc	Request audit by hash values
GET	/audit/dc/{id}/stato	Check audit processing status
GET	/audit/dc/{id}	List document filenames
GET	/audit/dc/{id}/files/{nomeFile}	Download specific document

Asynchronous Processing Pattern

All submission APIs use async polling:

1. POST submission → returns idPresaInCarico (UUID)
2. Poll GET /{id}/stato → states: PRONTA | IN_ELABORAZIONE | NON_DISPONIBILE
3. When PRONTA → GET /{id}/esito for results

Response Codes

Code	Meaning
200	Success
201	Certificate generation complete (device API)
202	Generation in progress
403	Not authorized
404	Not found
406	Invalid input parameters
409	Conflict (already registered, invalid state)
413	Payload too large
429	Rate limit exceeded
500	Internal server error (retry recommended)

Error responses contain codes arrays with ErrorCodeResponse objects (code + description).

AdE REST API — RT Device Endpoints (Reference)

For physical RT / Server RT devices (not our primary path, but relevant for understanding the ecosystem):

Method	Path	Purpose
POST	/dispositivi/	Request device certificate + registration
PUT	/dispositivi/	Device activation
POST	/dispositivi/corrispettivi/	Submit daily corrispettivi
POST	/dispositivi/scontrini/	Submit receipt documents
PUT	/dispositivi/evento/	Submit device status events
GET	/gestori/me/dispositivi/	List registered devices

Production base URL (RT): https://api.corrispettivi.agenziaentrate.gov.it/v1

Technical Protocols

XML Digital Signature

All XML submissions must be signed:

• Canonicalization: http://www.w3.org/TR/2001/REC-xml-c14n-20010315
• Signature Algorithm: RSA-SHA256
• Hash Algorithm: SHA256
• Transform: Enveloped signature (http://www.w3.org/2000/09/xmldsig#enveloped-signature)
• KeyInfo: Contains signing certificate only

Certificate Types

Certificate	Purpose	Issuer
Advanced Electronic Seal	Sealing commercial documents (SSW)	Accredited QTSP
AdE CA Certificate	TLS trust for API connections	AdE (CAAgenziadelleEntrate.cer)
Device Certificate	RT device signing (not SSW)	AdE (via CSR)
Entratel Certificate	Portal access (not API)	AdE (3-year validity)

TLS Requirements

• Mandatory TLS 1.2 (only permitted version since July 1, 2017)
• AdE CA certificates (CAAgenziadelleEntrate.cer + legacy CAEntrate.cer) must be in truststore

Transmission Timing

• Transactions memorized on same day as occurrence
• Telematic transmission within 12 days of transaction date
• Transmission at random time within 00:00-22:00 window

XSD Schema Index (Software Solution)

XSD File	Purpose
Allegato-SSW-Corrispettivi.xsd	Daily aggregated corrispettivi
Allegato-SSW-Corrispettivi-EM.xsd	Corrispettivi electronic memorization
Allegato-SSW-Corrispettivi-Esito.xsd	Submission result/outcome
Allegato-SSW-DocumentoCommerciale.xsd	Individual commercial document
Allegato-SSW-Journal.xsd	Audit journal
Allegato-SSW-CensimentoPEM.xsd	PEM registration
Allegato-SSW-AttivazionePEM-Esito.xsd	PEM activation result
Allegato-SSW-Catalogo.xsd	Software catalog
Allegato-SSW-Metadati.xsd	Metadata
Allegato-SSW-RichiestaAudit.xsd	Audit request
Allegato-SSW-Segnalazioni.xsd	Anomaly reports
Allegato-SSW-Segnalazioni-Esito.xsd	Anomaly report results

API YAML Specs (Software Solution)

YAML File	Purpose
ssw-Trasmissione dei Corrispettivi Giornalieri.yml	Daily corrispettivi submission
ssw-Censimento ed attivazione PEM.yml	PEM registration & activation
ssw-Comunica Stato PEM.yml	PEM state change notification
ssw-Audit DocumentoCommerciale.yml	Document audit retrieval
ssw-Audit Journal.yml	Journal audit retrieval

Submission Flow — Software Solution

POS Transaction
  → PEM records in software (MF1 emission)
  → MF2 memorizes transaction data
  → Daily closure (chiusura giornaliera / azzeramento)
  → Software generates corrispettivi XML (DSW10 format)
  → Software seals with advanced electronic seal (eIDAS QTSP certificate)
  → POST /corrispettivi (binary octet-stream)
  → Returns idPresaInCarico UUID
  → Poll GET /corrispettivi/{id}/stato
  → When PRONTA, GET /corrispettivi/{id}/esito for results

Implementation Design — Italy DC Adapter

Package Structure

apps/core-api/internal/adapters/italy/
├── adapter.go           # Existing: CountryAdapter (currently FatturaPA/SDI only)
├── config.go            # Existing: Config validation
├── authstore.go         # Existing: Credential loading
├── dc/                  # NEW: Documento Commerciale package
│   ├── xml.go           # DC XML generation (DSW10 format)
│   ├── corrispettivi.go # Daily aggregated corrispettivi XML
│   ├── closure.go       # Daily closure (azzeramento) logic
│   ├── seal.go          # Advanced electronic seal (eIDAS)
│   ├── lottery.go       # Lottery code and QR code integration
│   └── submit.go        # SSW REST API client
├── pem/                 # NEW: PEM lifecycle management
│   ├── census.go        # PEM registration via API
│   ├── activation.go    # PEM activation flow
│   └── state.go         # PEM state changes
└── testdata/
    └── conformance/
        └── dc/          # DC XML test fixtures

Sub-Adapter Pattern

Following the Spain adapter pattern, extend Italy's adapter to route between SDI (invoices) and DC (retail POS):

type Config struct {
    System           string `json:"system"`           // "sdi" or "dc"
    PartitaIVA       string `json:"partita_iva"`
    CodiceFiscale    string `json:"codice_fiscale"`
    LegalName        string `json:"legal_name"`

    // DC-specific
    CAUCode          string `json:"cau_code,omitempty"`        // Erogatore code (4 chars)
    PEMMatricola     string `json:"pem_matricola,omitempty"`   // Emission point ID
    SealCertID       string `json:"seal_certificate_id,omitempty"` // QTSP certificate ref

    // SDI-specific (existing)
    FormatoTrasmissione string `json:"formato_trasmissione,omitempty"`
    RegimeFiscale       string `json:"regime_fiscale,omitempty"`
}

Transaction Metadata Mapping

DC-specific metadata fields in Transaction.Metadata:

type DCMetadata struct {
    // Line items (from Transaction.Items)
    // Each item maps to ElementiContabiliType

    // Payment breakdown
    CashAmount       decimal.Decimal `json:"cash_amount"`
    ElectronicAmount decimal.Decimal `json:"electronic_amount"`
    TicketAmount     decimal.Decimal `json:"ticket_amount,omitempty"`
    TicketCount      int             `json:"ticket_count,omitempty"`

    // Return/cancellation
    IsReturn         bool   `json:"is_return,omitempty"`
    IsCancellation   bool   `json:"is_cancellation,omitempty"`
    OriginalMatricola string `json:"original_matricola,omitempty"`
    OriginalDate     string `json:"original_date,omitempty"`
    OriginalNumber   string `json:"original_number,omitempty"`

    // Lottery
    LotteryCode      string `json:"lottery_code,omitempty"`      // 0-16 chars
    InstantLotteryQR string `json:"instant_lottery_qr,omitempty"` // 0-64 chars

    // Customer (optional)
    CustomerCF       string `json:"customer_codice_fiscale,omitempty"`
}

Sealing Strategy

The SSW requires advanced electronic seals (sigilli elettronici avanzati):

1. Obtain X.509 certificate from accredited QTSP with merchant's Partita IVA in Subject
2. Store certificate reference in location config (seal_certificate_id)
3. Load certificate via existing CertStore infrastructure
4. Apply RSA-SHA256 enveloped XML signature using standard xmldsig logic
5. Reuse signing infrastructure from Spain adapter (XAdES signing is a superset)

PEM Lifecycle

PEM registration and activation must happen before any DC submission:

1. Census: POST /censimenti/pem/richieste with PEM data
2. Poll: GET /censimenti/pem/richieste/{id}/stato until PRONTA
3. Activate: GET /censimenti/pem/richieste/{id}/esito
4. Store PEM matricola in location config

This is a one-time setup per POS location, similar to RT device registration.

POS-RT Pairing (March 2026)

From Law 207/2024: all electronic payment instruments must be logically paired with RT devices or software solutions. Pairing is done via the "Fatture e Corrispettivi" portal — purely logical association (no physical cabling).

For SSW: POS is paired with the PEM emission point.

Differences from Existing Italy SDI Adapter

Aspect	SDI (FatturaPA)	DC (Documento Commerciale)
Document type	Invoice (fattura)	Receipt (scontrino)
Submission	Per-invoice, real-time	Daily aggregated (corrispettivi)
API	SDI REST endpoints	SSW REST endpoints (different base)
Signing	SDI credentials	eIDAS QTSP electronic seal
Schema	FatturaPA XSD	SSW-DocumentoCommerciale XSD
Identity	SDI channel codes	CAU code + PEM matricola
Processing	Synchronous-ish	Async with polling

Key Reference URLs

Official AdE portals:

• SSW specs & XSDs: https://www.agenziaentrate.gov.it/portale/specifiche-tecniche-allegati-invio-corrispettivi-soluzione-software
• RT device submission: https://www.agenziaentrate.gov.it/portale/schede/comunicazioni/fatture-e-corrispettivi
• Experimentation/sandbox docs: https://www.agenziaentrate.gov.it/portale/documentazione-per-sperimentazione
• XML Data Types v7.0: https://www.agenziaentrate.gov.it/portale/documents/20143/288260/Allegato-TipiDatiCorrispettivi-V7.0-marzo2020.pdf
• RT Technical Specs v10: https://www.agenziaentrate.gov.it/portale/documents/20143/2571432/Specifiche-tecniche-RT+V10.pdf

Community/third-party:

• OpenAPI sample: https://github.com/teamdigitale/api-openapi-samples/blob/master/external-apis/fatture-e-corrispettivi.yaml

---

Change Log

Date	Version	Description	Author
2026-03-14	1.0	Initial research document — DC format, RT/SSW system, AdE API, implementation design	furiosa (Polecat)