GOBL to FatturaPA Tools

Convert GOBL into the Italy's FatturaPA format.

Copyright Invopop Ltd. 2023. Released publicly under the Apache License Version 2.0. For commercial licenses please contact the dev team at invopop. In order to accept contributions to this library we will require transferring copyrights to Invopop Ltd.

Introduction

FatturaPA defines two versions of invoices:

• Ordinary invoices, FatturaElettronica types FPA12 and FPR12 defined in the v1.2 schema, usable for all sales.
• Simplified invoices, FatturaElettronicaSemplificata type FSM10 defined in the v1.0 schema, with a reduced set of requirements but can only be used for sales of less then €400, as of writing. Currently not supported!

Unlike other tax regimes, Italy requires simplified invoices to include the customer's tax ID. For "cash register" style receipts locally called "Scontrinos", another format and API is used for this from approved hardware.

Sources

You can find copies of the Italian FatturaPA schema in the schemas folder.

Key websites:

• FatturaPA & SDI service documentation page on on Italy's tax authority's website
• FatturaPA documentation page on FatturaPA's dedicated website

Useful files:

• Ordinary Schema V1.2.1 Spec Table View (EN) - by far the most comprehensible spec doc. Since the difference between 1.2.2 and 1.2.1 is minimal, this is perfectly usable.
• Ordinary Schema V1.2.2 PDF (IT) - most up-to-date but difficult
• XSD V1.2.2
• XSD V1 (FSM10) - simplified invoices
• CIUS-IT (Italian Core Invoice Usage Specification) - EN16931 mappings

Limitations

The FatturaPA XML schema is quite large and complex. This library is not complete and only supports a subset of the schema. The current implementation is focused on the most common use cases.

• Simplified invoices are not currently supported (please get in touch if you need this).
• FatturaPA allows multiple invoices within the document, but this library only supports a single invoice per transmission.
• Only a subset of payment methods (ModalitaPagamento) are supported. See payments.go for the list of supported codes.

Some of the optional elements currently not supported include:

• Allegati (attachments)
• DatiBollo (data related to duty stamps)

Usage

Go

There are a couple of entry points to build a new Fatturapa document. If you already have a GOBL Envelope available in Go, you could convert and output to a data file like this:

converter := fatturapa.NewConverter()

doc, err := converter.ConvertFromGOBL(env)
if err != nil {
    panic(err)
}

data, err := doc.Bytes()
if err != nil {
    panic(err)
}

if err = os.WriteFile("./test.xml", data, 0644); err != nil {
    panic(err)
}

If you're loading from a file, you can use the LoadGOBL convenience method:

doc, err := fatturapa.LoadGOBL(file)
if err != nil {
    panic(err)
}
// do something with doc

See the following example for signing the XML with a certificate:

// import from github.com/invopop/xmldsig
cert, err := xmldsig.LoadCertificate(filename, password)
if err != nil {
    panic(err)
}

converter := fatturapa.NewConverter(
    fatturapa.WithCertificate(cert),
    fatturapa.WithTimestamp(), // if you want to include a timestamp in the digital signature
)

doc, err := converter.ConvertFromGOBL(env)
if err != nil {
    panic(err)
}

If you want to include the fiscal data of the entity integrating with the SDI (Italy's e-invoice system) and ProgressivoInvio (transmission number) in the XML, you can use the WithTransmitterData option. This option must be used if you are integrating diredctly with the SDI, but if you are working with a third party service to send the XML, it would be on their side to include this data.

transmitter := fatturapa.Transmitter{
    CountryCode: countryCode, // ISO 3166-1 alpha-2
    TaxID:       taxID,       // Valid tax ID of transmitter
}

converter := fatturapa.NewConverter(
    fatturapa.WithTransmitterData(transmitter),
    // other options
)

CLI

The command line interface can be useful for situations when you're using a language other than Golang in your application. Download one of the pre-compiled gobl.fatturapa releases or install with:

go install github.com/invopop/gobl.fatturapa/cmd/gobl.fatturapa

Simply provide the input GOBL JSON file and output to a file or another application:

gobl.fatturapa convert input.json output.xml

If you have a digital certificate, run with:

gobl.fatturapa convert -c cert.p12 -p password input.json output.xml

To include the transmitter information, add the -T flag and provide the country code and the tax ID:

gobl.fatturapa convert -T ES12345678 input.json output.xml

The command also supports pipes:

cat input.json > ./gobl.fatturapa output.xml

Notes

• In all cases Go structures have been written using the same naming from the XML style document. This means names are not repeated in tags and generally makes it a bit easier to map the XML output to the internal structures.