FatturaPA - Generazione XML (COGSA3C)¶

Indice¶

Panoramica
Funzionalità principali
Flusso operativo
Struttura XML FatturaPA
Modalità output
File utilizzati
Programmi chiamati
Parametri di configurazione
Validazione e controlli
Gestione DDT/Bolle
Gestione IVA
Note tecniche

Panoramica¶

COGSA3C.cbl è il motore di generazione XML per la Fatturazione Elettronica Italiana (FatturaPA) e documenti B2B per consorzi.

Attributo	Valore
Programma	COGSA3C.cbl
Righe codice	8.564
Autore	Eurosystem
Versione FatturaPA	v1.2.1
Standard	Schema XSD Agenzia Entrate
Libreria XML	C$XML (AcuCOBOL XML library) + ACUXML (traditional mode)

Scopo¶

Trasforma i dati di fatture e DDT (bolle) dal database gestionale in file XML conformi allo standard FatturaPA v1.2.1 per la trasmissione al Sistema di Interscambio (SDI) dell'Agenzia delle Entrate.

Ambito¶

Fatture attive verso Pubblica Amministrazione (PA)
Fatture B2B verso privati e consorzi
Note di credito (TD04)
Documenti integrativi con riferimenti a DDT multipli
Trasporto automatico file generati verso directory output
Invio FTP opzionale verso servizi esterni

Funzionalità principali¶

1. Operazioni supportate¶

Il programma supporta 6 operazioni configurabili via parametro w-dc-cogsa3-ope:

Operazione	Codice	Descrizione
Genera XML	`add`	Genera solo file XML dalla fattura
Genera + Trasporta	`add+trasp`	Genera XML e copia in directory output
Genera + Trasporta + Aggiorna	`add+trasp2`	Come sopra + aggiorna nome file EDI nel database
Invia FTP	`send`	Invia file esistente via FTP
Trasporta	`trasporta`	Sposta file da temp a output
Ciclo completo	`make-all`	Genera, trasporta e invia FTP

2. Tipologie documento gestite¶

Mappatura tipi documento interni → FatturaPA:

Tipo DB	Tipo XML	Descrizione FatturaPA
Fattura normale	TD01	Fattura
Acconto/anticipo	TD02	Acconto/anticipo su fattura
Acconto/anticipo con IVA	TD03	Acconto/anticipo su parcella
Nota credito	TD04	Nota di credito
Nota debito	TD05	Nota di debito
Parcella	TD06	Parcella

Determinato in determina-w-tipo-doc (righe 1467-1519) dalla lettura di COGTABEL con verifica flag segnotiva.

3. Discriminazione PA vs B2B¶

Logica in find-cod-dest-ana-fatturapa (righe 1203-1290):

if (ana-codice-univoco-ufficio not = spaces)
   move "PA" to w-tipo-fattura      * Pubblica Amministrazione
else
   move "B2B" to w-tipo-fattura     * Business-to-Business
end-if

Output directory diversa: - PA → tm-cfg-out-dir (es. C:\FatturePA\PA\) - B2B → tm-cfg-fte-out-b2b (es. C:\FatturePA\B2B\)

Flusso operativo¶

Diagramma flusso principale¶

┌──────────────────────────────────────────────────────────────┐
│ ENTRY POINT: a00 (riga 862)                                  │
│ - Inizializzazione variabili                                 │
│ - Apertura file (open-files)                                 │
│ - Lettura dati azienda (rd-azi)                              │
│ - Caricamento config (x99-src-confi via RNEWCONF)            │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────────────────────┐
│ DISPATCH: a4 (riga 905)                                      │
│ Evaluate w-dc-cogsa3-ope:                                    │
│   when "add" / "add+trasp" / "add+trasp2" / "make-all"       │
│       ──→ perform aggiungi-fatturapa                         │
│   when "send"                                                │
│       ──→ perform send-ftp-file                              │
│   when "trasporta"                                           │
│       ──→ perform trasporta-to-output-dir                    │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    ▼ (caso "add")
┌──────────────────────────────────────────────────────────────┐
│ AGGIUNGI-FATTURAPA (riga 1306)                               │
│                                                               │
│ 1. rd-cogfattu            ← Leggi testata fattura            │
│ 2. determina-w-tipo-doc   ← Mappa tipo documento XML         │
│ 3. apri-file-output       ← Crea file XML temp               │
│    ├─ Mode A: open-fatturapa (ACUXML)                        │
│    └─ Mode X: cxml-f-open (C$XML)                            │
│                                                               │
│ 4. Lettura dati estesi:                                      │
│    ├─ rd-cogfatt2         ← Ordini, omaggi, bolli            │
│    ├─ find-cod-dest-ana-fatturapa ← Determina PA/B2B         │
│    ├─ prepare-dati-spese-bolli ← Calcola spese e bolli       │
│    └─ read-dati-iva-cli-sub-fattu ← Carica dati IVA cliente  │
│                                                               │
│ 5. Generazione struttura XML:                                │
│    ┌─────────────────────────────────────────────────┐       │
│    │ <p:FatturaElettronica versione="FPR12">        │       │
│    │   <FatturaElettronicaHeader>                   │       │
│    │     • DatiTrasmissione                         │       │
│    │     • CedentePrestatore                        │       │
│    │     • CessionarioCommittente                   │       │
│    │   </FatturaElettronicaHeader>                  │       │
│    │   <FatturaElettronicaBody>                     │       │
│    │     • DatiGenerali                             │       │
│    │     • DatiBeniServizi (righe fattura)          │       │
│    │     • DatiPagamento                            │       │
│    │   </FatturaElettronicaBody>                    │       │
│    │ </p:FatturaElettronica>                        │       │
│    └─────────────────────────────────────────────────┘       │
│                                                               │
│ 6. controlli-quadratura-xml-fattura                          │
│    ├─ Confronta totali XML vs DB                             │
│    ├─ Verifica imponibile/IVA da COGARIVA                    │
│    └─ Log errori se discrepanze                              │
│                                                               │
│ 7. Chiusura e trasporto:                                     │
│    ├─ close-fatturapa / cxml-f-close                         │
│    ├─ Copia file via COPIAF a directory output               │
│    ├─ Controllo dimensione (alert se > 5MB)                  │
│    └─ Aggiorna nome file EDI in w-dc-cogsa3-edi-filename     │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────────────────────┐
│ CLEANUP: fine (riga 970)                                     │
│ - Chiusura file (close-files)                                │
│ - Ripristino impostazioni XML (restore-xml-filesystem-...)   │
│ - Exit program con w-dc-cogsa3-esito (Y/N)                   │
└──────────────────────────────────────────────────────────────┘

Struttura XML FatturaPA¶

Schema ad albero v1.2.1¶

Il programma genera XML secondo questa struttura (righe 1352-1390):

<p:FatturaElettronica versione="FPR12"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:p="http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <FatturaElettronicaHeader>
        <DatiTrasmissione>
            <IdTrasmittente>
                <IdPaese>IT</IdPaese>
                <IdCodice>01234567890</IdCodice> <!-- P.IVA cedente -->
            </IdTrasmittente>
            <ProgressivoInvio>00001</ProgressivoInvio>
            <FormatoTrasmissione>FPR12</FormatoTrasmissione> <!-- PA o FPR12 per B2B -->
            <CodiceDestinatario>XXXXXXX</CodiceDestinatario> <!-- 7 char per PA, 0000000 per B2B -->
            <ContattiTrasmittente>
                <Telefono>...</Telefono>
                <Email>...</Email>
            </ContattiTrasmittente>
            <PECDestinatario>[email protected]</PECDestinatario> <!-- Solo per B2B -->
        </DatiTrasmissione>

        <CedentePrestatore>
            <DatiAnagrafici>
                <IdFiscaleIVA>
                    <IdPaese>IT</IdPaese>
                    <IdCodice>01234567890</IdCodice>
                </IdFiscaleIVA>
                <CodiceFiscale>RSSMRA80A01H501U</CodiceFiscale> <!-- Se persona fisica -->
                <Anagrafica>
                    <Denominazione>ACME S.r.l.</Denominazione>
                </Anagrafica>
                <RegimeFiscale>RF01</RegimeFiscale> <!-- Da config: RF01-RF19 -->
            </DatiAnagrafici>
            <Sede>
                <Indirizzo>Via Roma 1</Indirizzo>
                <CAP>00100</CAP>
                <Comune>Roma</Comune>
                <Provincia>RM</Provincia>
                <Nazione>IT</Nazione>
            </Sede>
            <IscrizioneREA>
                <Ufficio>RM</Ufficio>
                <NumeroREA>123456</NumeroREA>
                <CapitaleSociale>10000.00</CapitaleSociale>
                <SocioUnico>SU</SocioUnico>
                <StatoLiquidazione>LN</StatoLiquidazione>
            </IscrizioneREA>
            <Contatti>
                <Telefono>06123456</Telefono>
                <Email>[email protected]</Email>
            </Contatti>
        </CedentePrestatore>

        <CessionarioCommittente>
            <!-- Struttura analoga a CedentePrestatore -->
            <DatiAnagrafici>...</DatiAnagrafici>
            <Sede>...</Sede>
        </CessionarioCommittente>
    </FatturaElettronicaHeader>

    <FatturaElettronicaBody>
        <DatiGenerali>
            <DatiGeneraliDocumento>
                <TipoDocumento>TD01</TipoDocumento>
                <Divisa>EUR</Divisa>
                <Data>2026-03-04</Data>
                <Numero>FAT/2026/00123</Numero>
                <ImportoTotaleDocumento>12200.00</ImportoTotaleDocumento>
                <Causale>Vendita merce come da vs. ordine 456</Causale>
                <!-- Bollo virtuale se presente -->
                <DatiBollo>
                    <BolloVirtuale>SI</BolloVirtuale>
                    <ImportoBollo>2.00</ImportoBollo>
                </DatiBollo>
            </DatiGeneraliDocumento>

            <!-- DDT collegati (max 9) -->
            <DatiDDT>
                <NumeroDDT>DDT/001</NumeroDDT>
                <DataDDT>2026-03-01</DataDDT>
                <RiferimentoNumeroLinea>1</RiferimentoNumeroLinea>
                <RiferimentoNumeroLinea>2</RiferimentoNumeroLinea>
            </DatiDDT>

            <!-- Riferimenti amministrativi (se PA) -->
            <DatiOrdineAcquisto>
                <RiferimentoNumeroLinea>1</RiferimentoNumeroLinea>
                <IdDocumento>ODA123</IdDocumento>
                <Data>2026-02-15</Data>
                <CodiceCUP>F81H92000230001</CodiceCUP>
                <CodiceCIG>9876543210</CodiceCIG>
            </DatiOrdineAcquisto>
        </DatiGenerali>

        <DatiBeniServizi>
            <DettaglioLinee>
                <NumeroLinea>1</NumeroLinea>
                <CodiceArticolo>
                    <CodiceTipo>INTERNO</CodiceTipo>
                    <CodiceValore>ART001</CodiceValore>
                </CodiceArticolo>
                <Descrizione>Prodotto esempio descrizione lunga...</Descrizione>
                <Quantita>10.00</Quantita>
                <UnitaMisura>NR</UnitaMisura>
                <PrezzoUnitario>100.000000</PrezzoUnitario>
                <ScontoMaggiorazione>
                    <Tipo>SC</Tipo> <!-- SC=Sconto, MG=Maggiorazione -->
                    <Percentuale>10.00</Percentuale>
                </ScontoMaggiorazione>
                <PrezzoTotale>900.00</PrezzoTotale>
                <AliquotaIVA>22.00</AliquotaIVA>
            </DettaglioLinee>
            <!-- ... altre righe ... -->

            <DatiRiepilogo>
                <AliquotaIVA>22.00</AliquotaIVA>
                <ImponibileImporto>10000.00</ImponibileImporto>
                <Imposta>2200.00</Imposta>
                <EsigibilitaIVA>I</EsigibilitaIVA> <!-- I=immediata, D=differita, S=scissione -->
            </DatiRiepilogo>
            <DatiRiepilogo>
                <AliquotaIVA>0.00</AliquotaIVA>
                <Natura>N4</Natura> <!-- Esente/Non imponibile -->
                <ImponibileImporto>500.00</ImponibileImporto>
                <Imposta>0.00</Imposta>
            </DatiRiepilogo>
        </DatiBeniServizi>

        <DatiPagamento>
            <CondizioniPagamento>TP02</CondizioniPagamento> <!-- TP01=pagamento a rate, TP02=completo, TP03=anticipo -->
            <DettaglioPagamento>
                <ModalitaPagamento>MP05</ModalitaPagamento> <!-- MP05=bonifico, MP01=contanti, ... -->
                <DataScadenzaPagamento>2026-04-04</DataScadenzaPagamento>
                <ImportoPagamento>12200.00</ImportoPagamento>
                <IBAN>IT60X0542811101000000123456</IBAN>
                <IstitutoFinanziario>Banca Esempio</IstitutoFinanziario>
            </DettaglioPagamento>
        </DatiPagamento>
    </FatturaElettronicaBody>
</p:FatturaElettronica>

Procedure di generazione¶

Procedura	Righe	Genera sezione XML
`fatturapa-FatturaElettronicaHeader`	1668-1682	Root header
`fatturapa-h-DatiTrasmissione`	1707-1767	Dati trasmissione SDI
`fatturapa-h-CedentePrestatore`	1829-1905	Dati fornitore/cedente
`fatturapa-h-CessionarioCommittente`	1971-2083	Dati cliente/cessionario
`fatturapa-FatturaElettronicaBody`	1683-1696	Root body
`fatturapa-b-DatiGenerali`	2401-2433	Dati generali documento
`fatturapa-b-DatiGeneraliDocumento`	2434-2697	Dettagli documento (numero, data, importo)
`fatturapa-b-DatiDDT`	3284-3323	Riferimenti DDT (loop max 9)
`fatturapa-b-DatiBeniServizi`	2698-3467	Righe dettaglio merci/servizi
`loop-su-righe-fattura`	4906-5577	Loop su righe CAPMOMAG
`fill-dettaglio-linea`	5651-5783	Singola riga XML DettaglioLinee
`loop-su-tab-iva`	5578-5650	Riepilogo IVA (DatiRiepilogo)
`fatturapa-b-DatiPagamento`	3471-3520	Condizioni e modalità pagamento

Modalità output¶

Modalità A: ACUXML (tradizionale)¶

Configurazione: tm-cfg-out-type = "A"

File I/O COBOL classico:

* Apertura (riga 6948)
open-fatturapa.
    open output fatturapa.

* Scrittura (riga 6955)
wr-fatturapa.
    write fatturapa-rec from FatturaElettronica.

* Chiusura (riga 6960)
close-fatturapa.
    close fatturapa.

Caratteristiche: - File XML generato direttamente da copybook fatturapa_v1.2.1.fd - Output in ext-tmp-dir/#$csa3c1.[operatore] - Naming config-driven via nf-name-output

Modalità X: C$XML (libreria dinamica)¶

Configurazione: tm-cfg-out-type = "X"

API C$XML per costruzione DOM:

* Apertura (riga 6964)
cxml-f-open.
    move nf-name-output-tmp to xml-f-file
    move "utf-8"            to xml-f-encoding
    call "C$XML" using xml-create-file, xml-parm-file
    if xml-status = xml-ok
       ... gestione apertura OK
    else
       ... gestione errore
    end-if.

* Aggiunta elemento figlio (riga 6971)
cxml-f-add-child.
    move xml-t-tag to xml-e-tag
    call "C$XML" using xml-add-child, xml-parm-element.

* Aggiunta attributo (non mostrato esplicitamente)
cxml-f-add-attribute.
    call "C$XML" using xml-add-attribute, xml-parm-attribute.

* Aggiunta sibling (riga 6974)
cxml-f-add-sibling.
    call "C$XML" using xml-add-sibling, xml-parm-element.

* Chiusura elemento (riga 6977)
cxml-f-close-child.
    call "C$XML" using xml-close-child.

* Finalizzazione file (esteso)
cxml-f-close.
    call "C$XML" using xml-close-file.

Caratteristiche: - Costruzione dinamica albero DOM - Encoding UTF-8 - Output in ext-tmp-dir/$#csa3c2.[operatore] - Naming schema: IT[COFI/PIVA]_[numero-fattura].xml

Naming file output¶

Modalità A:

[nome-configurazione]-xml-fatturapa.xml
Esempio: ACME-xml-fatturapa.xml

Modalità X:

IT[P.IVA cedente]_[numero fattura univoco].xml
Esempio: IT01234567890_00001.xml

Configurazione in apri-file-output (righe 6839-6938).

File utilizzati¶

File input (lettura dati)¶

Tabelle master¶

File	Copybook	Scopo
COGFATTU	cogfattu.cpy	Testata fatture (chiave primaria)
COGFATT2	cogfatt2.cpy	Dati estesi fatture (ordini, omaggi, bolli)
COGGEANA	coggeana.cpy	Anagrafica clienti/fornitori
COGAPPOG	cogappog.cpy	Contatti clienti (telefono, email)
COGANAPP	coganapp.cpy	Dati supplementari anagrafica
COGCNDCF	cogcndcf.cpy	Condizioni cliente (PEC, cod. univoco ufficio)
COGTABEL	cogtabel.cpy	Tabelle codifiche (tipi doc, IVA, valute)
COGMERCI	cogmerci.cpy	Anagrafica merci
COGARIVA	cogariva.cpy	Partite IVA (per controllo quadratura)
COGRITAC	cogritac.cpy	Ritenute d'acconto

DDT/Bolle¶

File	Copybook	Scopo
CAPRACCO	capracco.cpy	Raccordo fatture ↔ bolle (varying 44-143 byte)
CAPTESBO	captesbo.cpy	Testata bolle DDT
CAPMOMAG	capmomag.cpy	Movimenti magazzino (righe bolle/fatture)
CAPDESAG	capdesag.cpy	Descrizioni aggiuntive righe
CAPAGGBO	capaggbo.cpy	Aggregazioni bolle
CAPFATTU	capfattu.cpy	Testata fatture (accesso indicizzato)

File temporanei descrizioni¶

File	Copybook	Scopo
LODTMDES	lodtmdes.cpy	Descrizioni temporanee testata (varying 50-2050)
LODTRDES	lodtrdes.cpy	Descrizioni temporanee righe (varying 50-2050)

Nota: I file LOD* sono file di transito riempiti dal programma con descrizioni estese estratte da COGDESCR e usati per costruire campo Causale in XML.

File output (scrittura)¶

File	Percorso	Formato
FatturaPA XML	`[tm-cfg-out-dir]` o `[tm-cfg-fte-out-b2b]`	XML v1.2.1
XML temporaneo	`ext-tmp-dir/#$csa3c1.[oper]` (mode A) o `$#csa3c2.[oper]` (mode X)	XML
Log FTP	`logftpsend[aaaammgg][hhmmss].txt`	TXT
XML errori	`[output-dir]\errori\`	XML (se validazione fallisce)

Copybook principali¶

Copybook	Tipo	Descrizione
`fatturapa_v1.2.1.fd`	FD	Definizioni record FatturaPA
`fatturapa_v1.2.1.sl`	SELECT	Select clause per file XML
`cogsa3c.select`	SELECT	File control section
`cogsa3c.fd`	FD	File descriptor specifici
`cogsa3c.wrk`	WS	Working storage (auto-gen Screen Designer)
`cogsa3c.decla`	DECLARATIVES	Gestione errori file
`cxml-wrk.cpy`	WS	Variabili C$XML
`l-base64.cpy`	LINKAGE	Encoding Base64 allegati
`l-copiaf.cpy`	LINKAGE	Utility copia file COPIAF
`utilcogsa3.cpy`	WS	Utility condivise programmi cogsa3*

Programmi chiamati¶

Programma	Scopo	Righe chiamata
COGS90	Lettura configurazione aziendale e parametri	Multipli
RNEWCONF	Caricamento parametri configurazione da tabelle conf	7027-7145
COPIAF	Utility copia file (client↔server, delete, shell commands)	6684-6838
COGU10	Recupero dati entità (cliente, fornitore, magazzino)	Vari
COGU02	Dati conversione valute/unità misura	Vari
C$JUSTIFY	Giustificazione stringhe (left/right/center)	Vari
base64	Encoding Base64 per allegati	6642-6683
C$XML	Libreria XML AcuCOBOL per generazione DOM	6964-6977

Programmi di I/O interni (paragraphs)¶

Procedure di lettura file database:

Paragraph	File	Operazione
`rd-cogfattu`	COGFATTU	Read invoice header
`rd-cogfatt2`	COGFATT2	Read extended invoice data
`rd-coggeana`	COGGEANA	Read customer/supplier
`rd-cogappog`	COGAPPOG	Read customer contacts
`rd-coganapp`	COGANAPP	Read customer supplementary
`rd-cogtabel`	COGTABEL	Read code tables
`rd-cogariva`	COGARIVA	Read VAT journal
`rd-cogcndcf`	COGCNDCF	Read customer conditions
`rd-capfattu`	CAPFATTU	Read invoice header (indexed)
`st-capracco-notmin`	CAPRACCO	Start read: Invoice-DDT relationships
`rdnxt-capracco`	CAPRACCO	Read next: Invoice-DDT relationships
`st-captesbo-notmin`	CAPTESBO	Start read: DDT headers
`rdnxt-captesbo`	CAPTESBO	Read next: DDT headers
`st-capmomag-notmin`	CAPMOMAG	Start read: Line items
`rdnxt-capmomag`	CAPMOMAG	Read next: Line items

Parametri di configurazione¶

Caricati da RNEWCONF¶

Procedura x99-src-confi (righe 7027-7145):

Gruppo config	Chiave	Campo destinazione	Descrizione
fatturaz	edi-cod-dest	`tm-cfg-cod-dest-ana`	Codice destinatario SDI (7 char)
fatturaz	edi-tribunale	`tm-cfg-tribunale`	Nome tribunale per PEC
fatturaz	edi-capsociale	`tm-cfg-capitale-sociale`	Capitale sociale azienda
fatturaz	edi-output-dir	`tm-cfg-out-dir`	Directory output fatture PA
fatturaz	edi-output-type	`tm-cfg-out-type`	Tipo output: A (ACUXML) o X (C$XML)
fatturaz	edi-azi-rea	`tm-cfg-azi-rea`	Codice REA azienda
fatturaz	edi-output-b2b	`tm-cfg-fte-out-b2b`	Directory output fatture B2B
partite	tipo-pag-fatture-pagate	`tm-cfg-tipo-pag-pagate`	Tipo pagamento per fatture pagate
fatturepa	regime-fiscale	`tm-cfg-pa-regime-fiscale`	Regime fiscale (RF01-RF19)
fatturepa	numero-documento	`tm-cfg-numero-doc-pa`	Numerazione PA (Y/N)
fatturepa	split-payment-abilita	`tm-cfg-split-payment`	Split payment abilitato (Y/N)
fatturepa	rif-paz	`tm-cfg-rif-paz`	Riferimento paziente (Y/N)
fatturepa	rif-med	`tm-cfg-rif-med`	Riferimento medico (Y/N)
stampafat	stampa-dag-merce	`tm-cfg-sta-dag-merce`	Stampa dettagli merce (Y/N)
stampafat	ordine-dag-merce	`tm-cfg-ord-dag-merce`	Ordine stampa merce

Struttura tm-config (working storage)¶

01  tm-config.
    02 tm-cfg-azi-rea               pic x(16).
    02 tm-cfg-cod-dest-ana          pic x(35).
    02 tm-cfg-out-dir               pic x(70).
    02 tm-cfg-fte-out-b2b           pic x(70).
    02 tm-cfg-out-type              pic x(01).  * A o X
    02 tm-cfg-pa-regime-fiscale     pic x(04).  * RF01-RF19
    02 tm-cfg-numero-doc-pa         pic x(01).  * Y/N
    02 tm-cfg-split-payment         pic x(01).  * Y/N
    02 tm-cfg-rif-paz               pic x(01).  * Y/N
    02 tm-cfg-rif-med               pic x(01).  * Y/N
    02 tm-cfg-tribunale             pic x(30).
    02 tm-cfg-capitale-sociale      pic 9(12)v99.
    02 tm-cfg-tipo-pag-pagate       pic x(02).
    02 tm-cfg-sta-dag-merce         pic x(01).
    02 tm-cfg-ord-dag-merce         pic x(01).

Codici regime fiscale (RF)¶

Conformi a specifiche FatturaPA v1.2.1:

Codice	Descrizione
RF01	Ordinario
RF02	Contribuenti minimi (art.1 c.96-117 L.244/07)
RF04	Agricoltura e attività connesse (art.34 c.6 DPR 633/72)
RF05	Vendita sali e tabacchi (art.74 c.1 DPR 633/72)
RF06	Commercio fiammiferi (art.74 c.1 DPR 633/72)
RF07	Editoria (art.74 c.1 DPR 633/72)
RF08	Gestione servizi telefonia pubblica (art.74 c.1 DPR 633/72)
RF09	Rivendita documenti di trasporto (art.74 c.1 DPR 633/72)
RF10	Intrattenimenti, giochi (art.74 c.6 DPR 633/72)
RF11	Agenzie viaggi (art.74-ter DPR 633/72)
RF12	Agriturismo (art.5 c.2 L.413/91)
RF13	Vendite porta a porta (art.25-bis c.6 DPR 600/73)
RF14	Rivendita beni usati (art.36 DL 41/95)
RF15	Agenzie vendite all'asta di oggetti d'arte (art.40-bis DL 41/95)
RF16	IVA per cassa PA (art.6 c.5 DPR 633/72)
RF17	IVA per cassa (art.32-bis DL 83/2012)
RF18	Altro
RF19	Regime forfettario (L.190/2014)

Validazione e controlli¶

Controllo quadratura XML-Database¶

Procedura controlli-quadratura-xml-fattura (righe 5335-5473):

Logica verifica¶

* Inizializzazione contatori
initialize w-chk-riv-impo w-chk-riv-iva      * Da COGARIVA (database)
           w-chk-fat-impo w-chk-fat-iva      * Da COGFATTU (testata)
           w-chk-xml-impo w-chk-xml-iva      * Da XML generato

* Lettura partite IVA da database
start cogariva key >= ...
perform until end-of-file
   add ari-imponib to w-chk-riv-impo
   add ari-iva     to w-chk-riv-iva
   read next cogariva
end-perform

* Lettura totali da testata fattura
move fat-imponib to w-chk-fat-impo
move fat-iva     to w-chk-fat-iva

* Calcolo totali da XML (loop su DatiRiepilogo)
perform varying i from 1 by 1 until i > ctr-tab-iva
   add iva-imponibile(i) to w-chk-xml-impo
   add iva-imposta(i)    to w-chk-xml-iva
end-perform

* Confronto e segnalazione discrepanze
compute w-chk-diff-impo = w-chk-xml-impo - w-chk-riv-impo
compute w-chk-diff-iva  = w-chk-xml-iva  - w-chk-riv-iva

if abs(w-chk-diff-impo) > 0,01 or
   abs(w-chk-diff-iva)  > 0,01
   * Genera messaggio di warning
   string "ATTENZIONE: Quadratura XML/DB non corretta!" into wb-msg
   string "Diff.Imponibile: " w-chk-diff-impo
          " Diff.IVA: "       w-chk-diff-iva
          into wb-msg
   perform vbx-msg-error
   * Opzionale: blocca generazione XML
   move "N" to w-fl-esito-aggiungi
end-if

Tolleranze¶

Imponibile: ±0,01€
IVA: ±0,01€

Discrepanze oltre tolleranza generano warning ma non bloccano XML (configurabile).

Controlli pre-generazione¶

Procedura controlli-generazione (non esplicitata, chiamata in aggiungi-fatturapa):

Controllo	Campo	Errore se
P.IVA cedente	`ana-piva`	Vuoto o non numerico
P.IVA cessionario	`ana-piva-cli`	Vuoto (se B2B)
Codice destinatario	`ana-codice-univoco-ufficio`	Vuoto (se PA) o <> 7 char
Regime fiscale	`tm-cfg-pa-regime-fiscale`	Non in range RF01-RF19
Tipo documento	`w-tipo-doc-xml`	Non in range TD01-TD06
Data fattura	`fat-data`	Formato errato o futura
Numero fattura	`fat-numero`	Vuoto
Totale documento	`fat-importo`	Zero o negativo (tranne TD04)

Validazione XSD post-generazione¶

Non implementata nel programma. Validazione XSD contro schema Agenzia Entrate demandata a: - Software SDI esterno - Servizio FTP/PEC di trasmissione - Validatore online Agenzia Entrate

Gestione DDT/Bolle¶

Raccordo Fattura ↔ DDT¶

File CAPRACCO (varying 44-143 byte):

01  rac-rec.
    02 rac-chia1.
       03 rac-dv         pic x(01).  * Divisione
       03 rac-tip        pic x(01).  * Tipo (F=Fattura, B=Bolla)
       03 rac-numero     pic 9(07).  * Numero fattura
       03 rac-rigo       pic 9(04).  * Riga fattura
    02 rac-dv-coll       pic x(01).  * Divisione collegata
    02 rac-numero-coll   pic 9(07).  * Numero DDT collegato
    02 rac-rigo-coll     pic 9(04).  * Riga DDT collegata
    02 rac-qta           pic s9(07)v999. * Quantità

Loop su bolle collegate¶

Procedura loop-su-bolle (righe 3324-3467, chiamata da fatturapa-b-DatiGenerali):

┌─────────────────────────────────────────────────────────────┐
│ 1. Start CAPRACCO by invoice number                         │
│    move fat-numero to rac-numero                            │
│    start capracco key >= rac-chia1                          │
│                                                              │
│ 2. Loop su righe CAPRACCO (max 9 DDT)                       │
│    perform until end-of-file or ctr-ddt > k-max-DatiDDT     │
│       if rac-dv-coll not = current-ddt-numero               │
│          * Nuova bolla trovata                              │
│          add 1 to ctr-ddt                                   │
│          save rac-numero-coll to current-ddt-numero         │
│                                                              │
│          * Leggi testata bolla                              │
│          perform rd-captesbo                                │
│                                                              │
│          * Genera elemento XML DatiDDT                      │
│          move tbo-numero to NumeroDDT(ctr-ddt)              │
│          move tbo-data   to DataDDT(ctr-ddt)                │
│                                                              │
│       end-if                                                │
│                                                              │
│       * Aggiungi riga al riferimento                        │
│       add 1 to ctr-rif-linea(ctr-ddt)                       │
│       move rac-rigo to RiferimentoNumeroLinea(              │
│                            ctr-ddt, ctr-rif-linea(ctr-ddt)) │
│                                                              │
│       read next capracco                                    │
│    end-perform                                              │
│                                                              │
│ 3. Output XML per ogni DDT                                  │
│    perform varying i-ddt from 1 by 1 until i-ddt > ctr-ddt │
│       <DatiDDT>                                             │
│          <NumeroDDT>...</NumeroDDT>                         │
│          <DataDDT>...</DataDDT>                             │
│          <RiferimentoNumeroLinea>1</...>                    │
│          <RiferimentoNumeroLinea>2</...>                    │
│          ...                                                │
│       </DatiDDT>                                            │
│    end-perform                                              │
└─────────────────────────────────────────────────────────────┘

Limiti standard FatturaPA: - Max 9 DDT per fattura (costante k-max-DatiDDT) - Max 200 riferimenti numero linea per DDT (costante k-max-RiferimentoNumeroLinea)

Gestione resi "affogati"¶

Reso affogato: Merce resa (reso) inclusa nella stessa fattura senza DDT separato.

Logica in loop-su-righe-fattura (righe 4906-5577):

if mam-segno = "-"                  * Riga negativa = reso
   if tm-cfg-resi-affogati = "Y"    * Config abilita resi affogati
      * Non generare DettaglioLinee separato
      * Sottrai importo da riga positiva precedente
      compute w-prezzo-tot-linea-prec =
              w-prezzo-tot-linea-prec - abs(mam-prezzo-tot)
   else
      * Genera DettaglioLinee con importo negativo
      perform fill-dettaglio-linea
   end-if
end-if

Alternativa: Se tm-cfg-resi-affogati = "N", i resi generano righe negative in XML con PrezzoTotale negativo.

Gestione IVA¶

Tabella IVA interna¶

Struttura tab-iva (working storage):

01  tab-iva.
    02 ctr-tab-iva          pic 9(03) comp-4 value zero.
    02 tab-iva-ele occurs 99.
       03 iva-aliquota      pic 9(02)v99.
       03 iva-natura        pic x(04).      * N1-N7 (esente/non imp.)
       03 iva-imponibile    pic s9(12)v9(06).
       03 iva-imposta       pic s9(12)v9(06).
       03 iva-esigibilita   pic x(01).      * I/D/S
       03 iva-rif-norm      pic x(100).     * Riferimento normativo

Popolamento tabella IVA¶

Procedura carica-tab-iva (chiamata durante loop righe):

* Per ogni riga fattura
perform varying i-riga from 1 by 1 until i-riga > num-righe-fattura

   * Leggi dati IVA da COGTABEL
   perform get-aliquota-iva          * → w-aliquota
   perform get-natura-iva            * → w-natura (se esente)
   perform get-esigibilita-iva       * → w-esigibilita

   * Cerca aliquota in tab-iva
   perform varying i from 1 by 1 until i > ctr-tab-iva
      if iva-aliquota(i) = w-aliquota and
         iva-natura(i)   = w-natura
         * Trovata → somma importi
         add mam-imponibile to iva-imponibile(i)
         compute iva-imposta(i) = iva-imposta(i) +
                 (mam-imponibile * w-aliquota / 100)
         exit perform
      end-if
   end-perform

   * Non trovata → aggiungi nuova entry
   if i > ctr-tab-iva
      add 1 to ctr-tab-iva
      move w-aliquota    to iva-aliquota(ctr-tab-iva)
      move w-natura      to iva-natura(ctr-tab-iva)
      move mam-imponibile to iva-imponibile(ctr-tab-iva)
      compute iva-imposta(ctr-tab-iva) =
              mam-imponibile * w-aliquota / 100
      move w-esigibilita to iva-esigibilita(ctr-tab-iva)
   end-if

end-perform

Generazione DatiRiepilogo XML¶

Procedura loop-su-tab-iva (righe 5578-5650):

perform varying i from 1 by 1 until i > ctr-tab-iva

   * Elemento DatiRiepilogo
   move "DatiRiepilogo" to xml-t-tag
   perform cxml-f-add-child  * o wr-fatturapa in mode A

   * AliquotaIVA
   move iva-aliquota(i) to AliquotaIVA
   perform cxml-f-add-child-value

   * Natura (solo se aliquota = 0)
   if iva-aliquota(i) = zero
      move iva-natura(i) to Natura
      perform cxml-f-add-child-value
   end-if

   * ImponibileImporto
   move iva-imponibile(i) to ImponibileImporto
   perform cxml-f-add-child-value

   * Imposta
   move iva-imposta(i) to Imposta
   perform cxml-f-add-child-value

   * EsigibilitaIVA
   move iva-esigibilita(i) to EsigibilitaIVA
   perform cxml-f-add-child-value

   * RiferimentoNormativo (opzionale)
   if iva-rif-norm(i) not = spaces
      move iva-rif-norm(i) to RiferimentoNormativo
      perform cxml-f-add-child-value
   end-if

   perform cxml-f-close-child  * Chiude DatiRiepilogo

end-perform

Output XML:

<DatiRiepilogo>
    <AliquotaIVA>22.00</AliquotaIVA>
    <ImponibileImporto>10000.00</ImponibileImporto>
    <Imposta>2200.00</Imposta>
    <EsigibilitaIVA>I</EsigibilitaIVA>
</DatiRiepilogo>
<DatiRiepilogo>
    <AliquotaIVA>0.00</AliquotaIVA>
    <Natura>N4</Natura>
    <ImponibileImporto>500.00</ImponibileImporto>
    <Imposta>0.00</Imposta>
    <EsigibilitaIVA>I</EsigibilitaIVA>
    <RiferimentoNormativo>Esente art. 10 DPR 633/72</RiferimentoNormativo>
</DatiRiepilogo>

Codici Natura IVA¶

Conformi a specifiche FatturaPA v1.2.1:

Codice	Descrizione
N1	Escluse ex art. 15 DPR 633/72
N2	Non soggette (es. extra UE, reverse charge)
N3	Non imponibili (es. esportazioni art. 8-9 DPR 633/72)
N4	Esenti (art. 10 DPR 633/72)
N5	Regime del margine / IVA non esposta in fattura
N6	Inversione contabile (reverse charge)
N7	IVA assolta in altro stato UE (vendite a distanza)

Split Payment¶

Scissione dei pagamenti (PA): IVA incassata direttamente da Agenzia Entrate, non dal fornitore.

Configurazione: tm-cfg-split-payment = "Y"

Effetti in XML:

<DatiRiepilogo>
    <AliquotaIVA>22.00</AliquotaIVA>
    <ImponibileImporto>10000.00</ImponibileImporto>
    <Imposta>2200.00</Imposta>
    <EsigibilitaIVA>S</EsigibilitaIVA>  <!-- S = Scissione pagamenti -->
</DatiRiepilogo>

Logica in fill-riepilogo-iva-sub-esigibilita (non dettagliata):

if tm-cfg-split-payment = "Y" and w-tipo-fattura = "PA"
   move "S" to EsigibilitaIVA
else
   if iva-differita = "Y"
      move "D" to EsigibilitaIVA  * Differita
   else
      move "I" to EsigibilitaIVA  * Immediata
   end-if
end-if

Data intervento nella Causale (COGSA3B)¶

Il programma COGSA3B (Creazione FatturaPA C$XML per bolle/fatture) include nella Causale del nodo DatiGeneraliDocumento un riferimento al numero e alla data dell'intervento collegato al DDT, quando presente.

La configurazione data-intervento-da-stampare (gruppo prntstfatt) governa quale data viene utilizzata:

Valore	Descrizione	Campo sorgente
`A`	Data assegnazione intervento	`acit-ass-data` (ASNINTES)
`E`	Data esecuzione intervento (default)	`acit-int-data` (ASNINTES)

Il testo generato nella Causale segue il formato:

Intervento n.XXXXXXXXXXXX del GG-MM-AAAA

Se la data non e' disponibile (campo a zero), viene stampato solo il numero intervento senza la data:

Intervento n.XXXXXXXXXXXX

La stessa configurazione e' utilizzata anche da COGP41L (Stampa fattura PCL-5): quando il valore e' "A", il programma usa la data di assegnazione (acit-ass-data) al posto della data di esecuzione per la stampa del riferimento intervento sulla fattura.

Note tecniche¶

Character set encoding¶

Problema: AcuCOBOL di default usa charset locale (Windows-1252), ma FatturaPA richiede UTF-8 o ISO-8859-1.

Soluzione (righe 8447-8460):

set-cobol-character-set.
    initialize w-cobol-character-set
    accept w-cobol-character-set from environment "COBOL_CHARACTER_SET"
    if (w-cobol-character-set <> "ISO-8859-1")
       set environment "COBOL_CHARACTER_SET" to "ISO-8859-1"
    end-if.

* ... generazione XML ...

reset-cobol-character-set.
    if (w-cobol-character-set <> "ISO-8859-1")
       set environment "COBOL_CHARACTER_SET" to w-cobol-character-set
    end-if.

Encoding output: - Mode A (ACUXML): ISO-8859-1 - Mode X (C$XML): UTF-8 (configurato in cxml-f-open)

Gestione descrizioni estese (LODTMDES/LODTRDES)¶

Problema: Campo Causale in FatturaPA max 200 caratteri, ma note fattura possono essere più lunghe.

Soluzione (righe 8412-8443):

carica-lodtmdes.
    * Copia descrizioni da COGDESCR (tipo "FT") a LODTMDES
    move "FT"       to cde-tip
    move fat-chia1  to cde-cod
    perform st-cogdescr-notmin
    perform until w-fine-file
       move cde-rec to ltd-rec
       perform wr-lodtmdes
       perform rdnxt-cogdescr
    end-perform.

* Spezzettamento in chunk da 200 char
perform st-lodtrdes-notmin
perform until w-fine-file
   move 1    to w-ini
   move 200  to w-fin
   perform until w-ini > ltr-len
      compute w-fin = min(200, ltr-len - w-ini + 1)
      move ltr-des(w-ini:w-fin) to Causale
      perform xadd-causale-to-dati  * Aggiunge a XML
      add w-fin to w-ini
   end-perform
   perform rdnxt-lodtrdes
end-perform

Risultato XML:

<Causale>Vendita merce varia come da vs. ordine 123/2026 del 15/02/2026. Consegna presso cantiere ...</Causale>
<Causale>... sede di Via Roma 1, Roma. Termini di pagamento: 60gg DFFM salvo buon fine. Si prega di r...</Causale>

Dimensione file XML¶

Limite soft: 5 MB (configurabile)

Controllo in aggiungi-fatturapa (dopo chiusura file):

* Verifica dimensione file
accept w-file-size from file-info using nf-name-output-tmp
if w-file-size > 5000000  * 5 MB
   initialize wb-msg
   string "ATTENZIONE: File XML > 5MB (" w-file-size " byte)"
          into wb-msg
   perform vbx-msg-warning
end-if

Limite SDI: 5 MB per singolo file XML (limite Agenzia Entrate).

Workaround se superato: - Spezzare fattura in più lotti - Ridurre descrizioni righe - Rimuovere allegati Base64

Gestione allegati Base64¶

Procedura aggiungi-allegato (non dettagliata esplicitamente, richiamata in fatturapa-b-Allegati):

* Leggi file da disco
move allegato-path to file-input
perform read-file-binary  * → w-file-binary-content

* Encoding Base64
move w-file-binary-content to base64-input
move length(w-file-binary-content) to base64-input-len
call "base64" using base64-parms
if base64-ok
   * Inserisci in XML
   move "Allegati" to xml-t-tag
   perform cxml-f-add-child
      move allegato-nome to NomeAttachment
      move "base64"      to FormatoAttachment
      move base64-output to Attachment
   perform cxml-f-close-child
end-if

Supporto: Configurabile via parametro (non standard, implementazione specifica cliente).

Gestione errori file¶

Declaratives section (non mostrate, ma referenziate in cogsa3c.decla):

declaratives.
errore-fatturapa section.
    use after error procedure on fatturapa.

    display "ERRORE FILE FATTURAPA: " stato
    display "Operazione: " operation
    move "N" to w-fl-esito-aggiungi
    exit section.

end declaratives.

Gestione stati: - stato = "00" → OK - stato = "35" → File non trovato - stato = "37" → Permessi insufficienti - stato = "30" → Disco pieno

Esempio chiamata da programma esterno¶

identification division.
program-id. chiamante.

working-storage section.
01  dati-chiamata.
    02 dc-util-cogsa3         pic x(01) value spaces.
    02 dc-cogsa3-fat          pic x(30).
    02 dc-cogsa3-ope          pic x(10).
    02 dc-cogsa3-called       pic x(08) value "COGSA3C".
    02 dc-cogsa3-caller       pic x(08) value "COGFAT".
    02 dc-cogsa3-edi-filename pic x(70) value spaces.
    02 dc-cogsa3-esito        pic x(01) value spaces.

procedure division.
main.
    * Imposta fattura da elaborare
    move "FT/2026/00123" to dc-cogsa3-fat

    * Operazione: genera e trasporta
    move "add+trasp" to dc-cogsa3-ope

    * Chiama COGSA3C
    call "COGSA3C" using dati-chiamata

    * Verifica esito
    if dc-cogsa3-esito = "Y"
       display "XML generato: " dc-cogsa3-edi-filename
    else
       display "ERRORE generazione XML"
    end-if

    stop run.

Riferimenti¶

Schema XSD FatturaPA v1.2.1: http://www.fatturapa.gov.it/export/documenti/fatturapa/v1.2.1/Schema_del_file_xml_FatturaPA_v1.2.1.xsd
Specifiche tecniche FatturaPA: http://www.fatturapa.gov.it/export/documenti/fatturapa/v1.2.1/Specifiche_tecniche_del_formato_FatturaPA_v1.2.1.pdf
Codici IVA e natura: Provvedimento Agenzia Entrate 89757/2018
C$XML AcuCOBOL: https://www.microfocus.com/documentation/acucobol-gt/1031/extend-interoperability-suite/xml-extensions.html

Autore documentazione: Claude Code Data: 2026-03-04 (aggiornato 2026-03-20) Versione programmi analizzati: COGSA3C.cbl (8.564 righe), COGSA3B.cbl (sezione data-intervento)