fatturapa

README

gobl.fatturapa

GOBL Conversion into FatturaPA in Italy

GOBL to FatturaPA Toolkit

Convert GOBL documents into the Italy's FatturaPA format.

TODO: copyright, license, build statuses

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.

cd cmd/gobl.fatturapa
go build

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 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.

Current Conversion 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.

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

Documentation

Overview

Package fatturapa implements the conversion from GOBL to FatturaPA XML.

Index

• func UnmarshalGOBL(reader io.Reader) (*gobl.Envelope, error)
• type Config
• type Converter
  • func NewConverter(opts ...Option) *Converter
  • func (c *Converter) ConvertFromGOBL(env *gobl.Envelope) (*Document, error)
• type Document
  • func (d *Document) Buffer() (*bytes.Buffer, error)
  • func (d *Document) Bytes() ([]byte, error)
  • func (d *Document) String() (string, error)
• type Option
  • func WithCertificate(cert *xmldsig.Certificate) Option
  • func WithTimestamp() Option
  • func WithTransmitterData(transmitter *Transmitter) Option
• 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 Config

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

Config contains the configuration for the Converter

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 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 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 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 Transmitter

type Transmitter struct {
	CountryCode string
	TaxID       string
}

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