fatturapa

package module
v0.65.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

README

GOBL - FatturaPA Tools

Convert GOBL documents to and from 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.

Lint Test Go Go Report Card GoDoc Latest Tag Ask DeepWiki

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.

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.

Sources

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

Key websites:

Useful files:

Limitations

To FatturaPA

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)
From FatturaPA

Converting from FatturaPA to GOBL has some limitations:

  • Currently, only one invoice per XML file is supported. FatturaPA allows multiple invoices in a single transmission, but this library only processes the first one.
  • Digital signature validation is not fully implemented. While the library can parse signed documents, it does not currently validate all aspects of the signature.

Usage

Go
To FatturaPA

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)
}

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
)
From FatturaPA

Converting from FatturaPA XML to GOBL is also straightforward. You can use the ConvertToGOBL method to transform a FatturaPA XML document into a GOBL Envelope:

// Import the XML data from a file or other source
xmlData, err := os.ReadFile("./invoice.xml")
if err != nil {
    panic(err)
}

// Create a converter
converter := fatturapa.NewConverter()

// Convert the XML to a GOBL Envelope
env, err := converter.ConvertToGOBL(xmlData)
if err != nil {
    panic(err)
}

// The envelope now contains a GOBL invoice
invoice, ok := env.Extract().(*bill.Invoice)
if !ok {
    panic("expected an invoice")
}

// You can now work with the GOBL invoice
// For example, validate it
if err = env.Validate(); err != nil {
    panic(err)
}

// Or convert it to JSON
jsonData, err := json.MarshalIndent(env, "", "  ")
if err != nil {
    panic(err)
}

if err = os.WriteFile("./invoice.json", jsonData, 0644); err != nil {
    panic(err)
}

Note that when converting from FatturaPA to GOBL:

  1. The XML document must contain a valid digital signature. The library will check for the presence of a signature but does not currently perform full signature validation.
  2. Only the first invoice in the XML file will be processed if the document contains multiple invoices.
  3. The resulting GOBL invoice will include the Italian SDI addon (sdi.V1) to maintain compatibility with FatturaPA-specific fields.
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
Converting GOBL to FatturaPA

To convert from GOBL JSON to FatturaPA XML:

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
Converting FatturaPA to GOBL

To convert from FatturaPA XML to GOBL JSON:

gobl.fatturapa convert input.xml output.json

By default, the JSON output is pretty-printed. To disable this, use the --pretty=false flag:

gobl.fatturapa convert --pretty=false input.xml output.json

Documentation

Overview

Package fatturapa implements the conversion from GOBL to FatturaPA XML.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Parse added in v0.47.0 

func Parse(doc []byte) (*gobl.Envelope, error)

Parse expects the XML document bytes and provides a new GOBL envelope containing the invoice.

Types

type Address added in v0.33.0 

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 Body added in v0.47.0 

type Body struct {
	GeneralData   *GeneralData   `xml:"DatiGenerali,omitempty"`
	GoodsServices *GoodsServices `xml:"DatiBeniServizi,omitempty"`
	PaymentsData  []*PaymentData `xml:"DatiPagamento,omitempty"`
}

Body contains all invoice data apart from the parties involved, which are contained in Header.

type Contact added in v0.33.0 

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

Contact describes how the party can be contacted

type Customer added in v0.33.0 

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

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

type Despatch added in v0.51.0 

type Despatch struct {
	Code      string `xml:"NumeroDDT"`                        // document number
	IssueDate string `xml:"DataDDT"`                          // document date (expressed according to the ISO
	Lines     []int  `xml:"RiferimentoNumeroLinea,omitempty"` // detail row of the invoice referred to (if the reference is to the entire invoice, this is not filled in)
}

Despatch contains data about a Delivery Document.

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"`

	Header *Header `xml:"FatturaElettronicaHeader"`
	Body   []*Body `xml:"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 Convert added in v0.47.0 

func Convert(env *gobl.Envelope, opts ...Option) (*Document, error)

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

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 DocumentRef added in v0.39.0 

type DocumentRef struct {
	Lines     []int  `xml:"RiferimentoNumeroLinea"`              // detail row of the invoice referred to (if the reference is to the entire invoice, this is not filled in)
	Code      string `xml:"IdDocumento"`                         // document number
	IssueDate string `xml:"Data,omitempty"`                      // document date (expressed according to the ISO 8601:2004 format)
	LineCode  string `xml:"NumItem,omitempty"`                   // identification of the single item on the document (e.g. in the case of a purchase order, this is the number of the row of the purchase order, or, in the case of a contract, it is the number of the row of the contract, etc. )
	OrderCode string `xml:"CodiceCommessaConvenzione,omitempty"` // order or agreement code
	CUPCode   string `xml:"CodiceCUP,omitempty"`                 // code managed by the CIPE (Interministerial Committee for Economic Planning) which characterises every public investment project (Individual Project Code).
	CIGCode   string `xml:"CodiceCIG,omitempty"`                 // Tender procedure identification code
}

DocumentRef contains data about a previous document.

type FundContribution added in v0.58.0 

type FundContribution struct {
	Type      string `xml:"TipoCassa"`
	Rate      string `xml:"AlCassa"`
	Amount    string `xml:"ImportoContributoCassa"`
	TaxBase   string `xml:"ImponibileCassa,omitempty"`
	TaxRate   string `xml:"AliquotaIVA"`
	Retained  string `xml:"Ritenuta,omitempty"`
	TaxNature string `xml:"Natura,omitempty"`
	AdminRef  string `xml:"RiferimentoAmministrazione,omitempty"`
}

FundContribution contains data about a professional fund contribution (DatiCassaPrevidenziale)

type GeneralData added in v0.39.0 

type GeneralData struct {
	Document  *GeneralDocumentData `xml:"DatiGeneraliDocumento"`
	Purchases []*DocumentRef       `xml:"DatiOrdineAcquisto,omitempty"`
	Contracts []*DocumentRef       `xml:"DatiContratto,omitempty"`
	Tender    []*DocumentRef       `xml:"DatiConvenzione,omitempty"`
	Receiving []*DocumentRef       `xml:"DatiRicezione,omitempty"`
	Preceding []*DocumentRef       `xml:"DatiFattureCollegate,omitempty"`
	Despatch  []*Despatch          `xml:"DatiDDT,omitempty"`
}

GeneralData contains general data about the invoice such as retained taxes, invoice number, invoice date, document type, etc.

type GeneralDocumentData added in v0.47.0 

type GeneralDocumentData struct {
	DocumentType      string              `xml:"TipoDocumento"`
	Currency          string              `xml:"Divisa"`
	IssueDate         string              `xml:"Data"`
	Number            string              `xml:"Numero"`
	RetainedTaxes     []*RetainedTax      `xml:"DatiRitenuta,omitempty"`
	StampDuty         *StampDuty          `xml:"DatiBollo,omitempty"`
	FundContributions []*FundContribution `xml:"DatiCassaPrevidenziale,omitempty"`
	PriceAdjustments  []*PriceAdjustment  `xml:"ScontoMaggiorazione,omitempty"`
	TotalAmount       string              `xml:"ImportoTotaleDocumento,omitempty"`
	Rounding          string              `xml:"Arrotondamento,omitempty"`
	Reasons           []string            `xml:"Causale,omitempty"`
}

GeneralDocumentData contains data about the general document

type GoodsServices added in v0.47.0 

type GoodsServices struct {
	LineDetails []*LineDetail `xml:"DettaglioLinee"`
	TaxSummary  []*TaxSummary `xml:"DatiRiepilogo"`
}

GoodsServices contains all data related to the goods and services sold. 

type Header struct {
	TransmissionData *TransmissionData `xml:"DatiTrasmissione,omitempty"`
	Supplier         *Supplier         `xml:"CedentePrestatore,omitempty"`
	Customer         *Customer         `xml:"CessionarioCommittente,omitempty"`
}

Header contains all data related to the parties involved in the document.

type Identity added in v0.33.0 

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 LineDetail added in v0.47.0 

type LineDetail struct {
	LineNumber       string             `xml:"NumeroLinea"`
	Description      string             `xml:"Descrizione"`
	Quantity         string             `xml:"Quantita"`
	Unit             string             `xml:"UnitaMisura,omitempty"`
	PeriodStart      string             `xml:"DataInizioPeriodo,omitempty"`
	PeriodEnd        string             `xml:"DataFinePeriodo,omitempty"`
	UnitPrice        string             `xml:"PrezzoUnitario"`
	PriceAdjustments []*PriceAdjustment `xml:"ScontoMaggiorazione,omitempty"`
	TotalPrice       string             `xml:"PrezzoTotale"`
	TaxRate          string             `xml:"AliquotaIVA"`
	Retained         string             `xml:"Ritenuta,omitempty"`
	TaxNature        string             `xml:"Natura,omitempty"`
	OtherData        []*OtherData       `xml:"AltriDatiGestionali,omitempty"`
}

LineDetail contains line data such as description, quantity, price, etc.

type Option 

type Option func(*config)

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 added in v0.35.0 

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 OtherData added in v0.60.0 

type OtherData struct {
	DataType      string `xml:"TipoDato"`
	TextReference string `xml:"RiferimentoTesto,omitempty"`
	NumReference  string `xml:"RiferimentoNumero,omitempty"`
	DateReference string `xml:"RiferimentoData,omitempty"`
}

OtherData contains additional management data for a line item.

type PaymentData added in v0.47.0 

type PaymentData struct {
	Conditions string              `xml:"CondizioniPagamento"`
	Payments   []*PaymentDetailRow `xml:"DettaglioPagamento,omitempty"`
}

PaymentData contains all data related to the payment of the document.

type PaymentDetailRow added in v0.47.0 

type PaymentDetailRow struct {
	Beneficiary          string `xml:"Beneficiario,omitempty"`
	Method               string `xml:"ModalitaPagamento"`
	Date                 string `xml:"DataRiferimentoTerminiPagamento,omitempty"`
	Days                 int64  `xml:"GiorniTerminiPagamento,omitempty"`
	DueDate              string `xml:"DataScadenzaPagamento,omitempty"`
	Amount               string `xml:"ImportoPagamento"`
	FinancialInstitution string `xml:"IstitutoFinanziario,omitempty"`
	IBAN                 string `xml:"IBAN,omitempty"`
	ABI                  string `xml:"ABI,omitempty"`
	CAB                  string `xml:"CAB,omitempty"`
	BIC                  string `xml:"BIC,omitempty"`
	Code                 string `xml:"CodicePagamento,omitempty"`
}

PaymentDetailRow contains data related to a single payment.

type PermanentEstablishment added in v0.33.0 

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 PriceAdjustment added in v0.47.0 

type PriceAdjustment struct {
	Type    string `xml:"Tipo"`
	Percent string `xml:"Percentuale,omitempty"`
	Amount  string `xml:"Importo,omitempty"`
}

PriceAdjustment contains data about price adjustments like discounts and charges.

type Profile added in v0.33.0 

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 added in v0.33.0 

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 RetainedTax added in v0.47.0 

type RetainedTax struct {
	Type   string `xml:"TipoRitenuta"`
	Amount string `xml:"ImportoRitenuta"`
	Rate   string `xml:"AliquotaRitenuta"`
	Reason string `xml:"CausalePagamento"`
}

RetainedTax represents a retained tax.

type StampDuty added in v0.47.0 

type StampDuty struct {
	VirtualStamp string `xml:"BolloVirtuale"`
	Amount       string `xml:"ImportoBollo,omitempty"`
}

StampDuty contains data about the stamp duty

type Supplier added in v0.33.0 

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 added in v0.33.0 

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 TaxSummary added in v0.47.0 

type TaxSummary struct {
	TaxRate        string `xml:"AliquotaIVA"`
	TaxNature      string `xml:"Natura,omitempty"`
	TaxableAmount  string `xml:"ImponibileImporto"`
	TaxAmount      string `xml:"Imposta"`
	TaxLiability   string `xml:"EsigibilitaIVA,omitempty"`
	LegalReference string `xml:"RiferimentoNormativo,omitempty"`
}

TaxSummary contains tax summary data such as tax rate, tax amount, etc.

type TransmissionData added in v0.47.0 

type TransmissionData struct {
	TransmitterID      *TaxID `xml:"IdTrasmittente,omitempty"` // nolint:revive
	ProgressiveNumber  string `xml:"ProgressivoInvio,omitempty"`
	TransmissionFormat string `xml:"FormatoTrasmissione,omitempty"`
	RecipientCode      string `xml:"CodiceDestinatario"`
	RecipientPEC       string `xml:"PECDestinatario,omitempty"`
}

TransmissionData contains data related to the transmission of the invoice

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
gobl.fatturapa command
Package main implements the CLI as well as mage commands (toplevel mage.go)
 Package main implements the CLI as well as mage commands (toplevel mage.go)
Package test provides tools for testing the library both manually as well as helpers for writing test code.
 Package test provides tools for testing the library both manually as well as helpers for writing test code.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.