fatturapa

README

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

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)
• DatiOrdineAcquisto (data related to purchase orders)
• DatiContratto (data related to contracts)
• DatiConvenzione (data related to conventions)
• DatiRicezione (data related to receipts)
• DatiFattureCollegate (data related to linked invoices)
• 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. Install with:

go install github.com/invopop/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.

Integration Tests

There are some integration and XML generation tests available in the /test path. to generate the FatturaPA XML documents from the GOBL sources, use the digital certificates that are available in the /test/certificates path:

mage -v TestConversion

Sample data sources are contained in the /test/data directory. JSON (for tests) documents are stored in the Git repository, but the XML must be generated using the above commands.

Documentation

Overview

Package fatturapa implements the conversion from GOBL to FatturaPA XML.

Index

• func UnmarshalGOBL(reader io.Reader) (*gobl.Envelope, error)
• type Address
• type Config
• type Contact
• type Converter
  • func NewConverter(opts ...Option) *Converter
  • func (c *Converter) ConvertFromGOBL(env *gobl.Envelope) (*Document, error)
• type Customer
• type Document
  • func (d *Document) Buffer() (*bytes.Buffer, error)
  • func (d *Document) Bytes() ([]byte, error)
  • func (d *Document) String() (string, error)
• type Identity
• type Option
  • func WithCertificate(cert *xmldsig.Certificate) Option
  • func WithCurrentTime(t time.Time) Option
  • func WithTimestamp() Option
  • func WithTransmitterData(transmitter *Transmitter) Option
• type PermanentEstablishment
• type Profile
• type Registration
• type Supplier
• type TaxID
• type Transmitter

Functions

func UnmarshalGOBL

func UnmarshalGOBL(reader io.Reader) (*gobl.Envelope, error)

UnmarshalGOBL converts the given JSON document to a GOBL Envelope

Types

type Address

type Address struct {
	Street   string `xml:"Indirizzo"`              // Street
	Number   string `xml:"NumeroCivico,omitempty"` // Number
	Code     string `xml:"CAP"`                    // Post Code
	Locality string `xml:"Comune"`                 // Locality
	Region   string `xml:"Provincia,omitempty"`    // Region
	Country  string `xml:"Nazione"`                // Country Code
}

Address from IndirizzoType

type Config

type Config struct {
	Certificate     *xmldsig.Certificate
	WithTimestamp   bool
	Transmitter     *Transmitter
	WithCurrentTime time.Time
}

Config contains the configuration for the Converter

type Contact

type Contact struct {
	Telephone string `xml:"Telefono,omitempty"`
	Email     string `xml:"Email,omitempty"`
}

Contact describes how the party can be contacted

type Converter

type Converter struct {
	Config *Config
}

Converter contains information related to the entity using this library to submit invoices to SDI.

func NewConverter

func NewConverter(opts ...Option) *Converter

NewConverter returns a new GOBL to XML Converter with the given options

func (*Converter) ConvertFromGOBL

func (c *Converter) ConvertFromGOBL(env *gobl.Envelope) (*Document, error)

ConvertFromGOBL expects the base envelope and provides a new Document containing the XML version.

type Customer

type Customer struct {
	Identity *Identity `xml:"DatiAnagrafici"`
	Address  *Address  `xml:"Sede"`
}

Customer contains the details about who the invoice is addressed to.

type Document

type Document struct {
	XMLName        xml.Name `xml:"p:FatturaElettronica"`
	FPANamespace   string   `xml:"xmlns:p,attr"`
	DSigNamespace  string   `xml:"xmlns:ds,attr"`
	XSINamespace   string   `xml:"xmlns:xsi,attr"`
	Versione       string   `xml:"versione,attr"`
	SchemaLocation string   `xml:"xsi:schemaLocation,attr"`

	FatturaElettronicaHeader *fatturaElettronicaHeader
	FatturaElettronicaBody   []*fatturaElettronicaBody

	Signature *xmldsig.Signature `xml:"ds:Signature,omitempty"`
	// contains filtered or unexported fields
}

Document is a pseudo-model for containing the XML document being created.

func (*Document) Buffer

func (d *Document) Buffer() (*bytes.Buffer, error)

Buffer returns a byte buffer representation of the complete XML document.

func (*Document) Bytes

func (d *Document) Bytes() ([]byte, error)

Bytes returns the XML document bytes

func (*Document) String

func (d *Document) String() (string, error)

String converts a struct representation to its string representation

type Identity

type Identity struct {
	TaxID      *TaxID   `xml:"IdFiscaleIVA,omitempty"` // nolint:revive
	FiscalCode string   `xml:"CodiceFiscale,omitempty"`
	Profile    *Profile `xml:"Anagrafica"`
	// FiscaleRegime identifies the tax system to be applied
	// Has the form RFXX where XX is numeric; required only for the supplier
	FiscalRegime string `xml:"RegimeFiscale,omitempty"`
}

Identity (DatiAnagrafici) contains information related to an individual or company

type Option

type Option func(*Converter)

Option is a function that can be passed to NewConverter to configure it

func WithCertificate

func WithCertificate(cert *xmldsig.Certificate) Option

WithCertificate will ensure the XML document is signed with the given certificate

func WithCurrentTime

func WithCurrentTime(t time.Time) Option

WithCurrentTime will ensure the XML document is signed with the given current time

func WithTimestamp

func WithTimestamp() Option

WithTimestamp will ensure the XML document is timestamped

func WithTransmitterData

func WithTransmitterData(transmitter *Transmitter) Option

WithTransmitterData will ensure the XML document contains the given transmitter data

type PermanentEstablishment

type PermanentEstablishment struct {
	Street   string `xml:"Indirizzo"`
	Number   string `xml:"NumeroCivico,omitempty"`
	PostCode string `xml:"CAP"`
	Locality string `xml:"Comune"`
	Region   string `xml:"Provincia,omitempty"` // Province initials (2 characters) for IT country
	Country  string `xml:"Nazione"`             // Country code ISO alpha-2
}

PermanentEstablishment (StabileOrganizzazione) to be filled in if the seller/provider is not resident, but has a permanent establishment in Italy

type Profile

type Profile struct {
	// Name of the organization
	Name string `xml:"Denominazione,omitempty"`
	// Natural person's first or given name if no "Denominazione" is provided
	Given string `xml:"Nome,omitempty"`
	// Surname of the person
	Surname string `xml:"Cognome,omitempty"`
	// Title of the person
	Title string `xml:"Titolo,omitempty"`
	// EORI (Economic Operator Registration and Identification) code
	EORI string `xml:"CodEORI,omitempty"`
}

Profile contains identity data of the seller/provider

type Registration

type Registration struct {
	// Initials of the province where the company's Registry Office is located
	Office string `xml:"Ufficio,omitempty"`
	// Company's REA registration number
	Entry string `xml:"NumeroREA,omitempty"`
	// Company's share capital
	Capital string `xml:"CapitaleSociale,omitempty"`
	// Indication of whether the Company is in liquidation or not.
	// Possible values: LS (in liquidation), LN (not in liquidation)
	LiquidationState string `xml:"StatoLiquidazione,omitempty"`
}

Registration contains information related to the company registration details (REA)

type Supplier

type Supplier struct {
	Identity               *Identity               `xml:"DatiAnagrafici"`
	Address                *Address                `xml:"Sede"`
	PermanentEstablishment *PermanentEstablishment `xml:"StabileOrganizzazione,omitempty"`
	Registration           *Registration           `xml:"IscrizioneREA,omitempty"`
	Contact                *Contact                `xml:"Contatti,omitempty"`
}

Supplier describes the seller/provider of the invoice.

type TaxID

type TaxID struct {
	Country string `xml:"IdPaese"` // ISO 3166-1 alpha-2 country code
	Code    string `xml:"IdCodice"`
}

TaxID is the VAT identification number consisting of a country code and the actual VAT number.

type Transmitter

type Transmitter struct {
	CountryCode string
	TaxID       string
}

Transmitter contains information about the entity integrating directly with the SDI to submit and receive invoices