Mapping Italy's E-Invoicing Requirements to GOBL

[lucanioi]

Italy is a great example of a tax regime that demands painfully specific classifications of data related to electronic invoicing, such as document type, "nature" of the invoice, payment method, tax scheme, and more (see the end of this document). Each category comes with a set of permitted alphanumeric codes, and they are validated when the invoice is submitted to the authorities. There are a total of 112 valid codes across 6 different categories.

Not of all of those fields are mandatory, but some are: TipoDocumento, RegimeFiscale (not to be confused with GOBL's use of Regime), and ModalitaPagamento. Some optional fields, such as Natura, contain definitions of commonly used schemes like reverse charge. In order to build a valid Italian invoice, we'd have to include these codes and categories somewhere and validate them.

One idea suggested in a discussion with @samlown was to make use of the Meta field in an invoice to contain Italy-specific codes like:

"Meta": {
  "fatturapa-tipo-documento": "TD28",
  "fatturapa-natura": "N1.6"
}

Another option was to extend existing GOBL constructs like

var InvoiceTypeSelfBilledSplaphoning = bill.InvoiceTypeSelfBilled.With("splaphoning")

(fun detail: "splaphoning" is not a word, but it does appear in the official documentation)

This seems like a test of GOBL's flexibility. We could move specific validations to the providers (this case gobl.fatturapa), but my understanding is that we don't want well-formatted GOBL documents to be considered invalid at the provider level.

Any ideas?

[samlown]

So, having thought about this one for a while, and after the recent changes proposed in #101, I'm starting to reach the conclusion that perhaps GOBL should avoid using meta fields internally. In #101 the preceding correction types and method keys were moved to the Spanish regime where they can be used and validated in context, while GOBL provides fields for this data.

I also have the impression that we should try as hard as possible to avoid using local codes in GOBL unless there is absolutely no alternative, in meta or otherwise. They're hard to use and could potentially provide conflicting meaning if for example we define a regular invoice but use the Italian invoice type code TD16 but fail to include reverse-charge in the schemes.

I do also feel that we shouldn't "overload" important fields like type in bill.Invoice with local exceptions as this might break the universality of GOBL.

Let's double down on Italian case specifically for TipoDocumento (document type). The current list of types are available here in the README.md for reference: https://github.com/invopop/gobl/tree/italy/regimes/it (in #103 I've made some suggestions).

I think for most of the cases we can leverage the "schemes" to support advanced combinations, for example:

• TD01 - just a regular invoice.
• TD03 - uses partial invoice type alongside freelancer scheme.
• TD04 - uses credit-note invoice type
• TD06 - uses default invoice type and adds freelancer scheme
• TD08 - uses credit-note type, but simply doesn't include the customer details, implying its a simplified invoice.
• TD21 - uses self-billed type, with ceiling-exceeded scheme to imply the strange "splafonamento" stuff.
• TD28 - adds san-merino-paper scheme

The trend here is to add the complexity to the Schemes. An invoice can contain multiple schemes, so this is okay.

Another example is the "ModalitaPagamento". This is harder to put into a scheme as they're very closely related to payments. For these I'd suggest adding a new SubKey field to the pay.Instructions struct. In SubKey we can set the type to simply cbc.Key and define regime specific exceptions, for example:

• MP01 - Key: cash
• MP10 - Key: direct-debit SubKey: utilities
• MP23 - Key: online SubKey: pagopa

What do you think?

[cavalle]

Very interesting topic! And one that will probably come up again as we support more countries. As @lucanioi said, Italy is a remarkable example of how pointlessly complex taxonomies can become. My understanding is too superficial for me to give feedback about each specific Italian category. However, here's a general thought I get from reading this thread: do we really need (or want) to provide exhaustive support for every single category of every single classification? I'd be very surprised if the Pareto rule (80% of the cases can be covered by 20% of the spec) wouldn't apply here in an even more extreme way.

Now, I get where Sam's coming from with his objections to using meta fields and country specific codes in GOBL. We should definitely strive for that as a general rule. However, I can't help but think that there will always be cases where doing so will involve an excessive amount of complexity (both for us and for those producing the GOBL files). And this ties in with my previous point: would it make sense to avoid meta fields and country codes (as in Sam examples) for the most common categories, and leave the option of using meta tags as a fallback for the less common cases that cannot be easily mapped from the standard GOBL fields?

[samlown]

I've made a proposal that also adds support for a "tag" on individual invoice lines: #105. In this implementation the "schemes" and "tags" can be safely ignored by most consumers. They only add meaning when converting to local formats and specific types need to be assigned.