​
Introduction

GOBL was built by the Invopop team to specifically address the problem of international invoicing. We see a world of different business documents that can benefit from GOBL, but invoicing will always be our starting point.

In this page we cover some of the basics of invoices and describe how GOBL can make life easier for developers.

​
What is an invoice?

An invoice is a kind of legal contract sent from a supplier to a customer that informs them of the sale of goods or services for which they must now pay. The concept is often confused with sale receipts, especially in the United States, as they’re very similar in content. In jurisdictions that apply “Value Added Tax” or “General Sales Tax” to sales, an invoice is a legally binding document that must either be adhered to or annulled with another document, like a credit note. A sales receipt by contrast simply represents a transaction that has already taken place and doesn’t normally imply a contractual agreement.

Traditionally invoices were, and indeed still are, issued on paper. In the last few decades companies have started switching to sending PDF invoices via email with significant bookkeeping time savings. They’re not perfect however, they’re still effectively paper-like so its not normally possible to automatically extract data without OCR and the inherent risk of mistakes.

AI has made impressive leaps of late to extract and interpret data from a PDF or image, but you they can not guarantee 100% accuracy and its still quite a resource intensive process for information that was created on someone else’s computer.

​
What is an electronic invoice?

While a PDF is an electronic format, it is not considered an electronic invoice. The key difference is in the structured contents. A true electronic invoice can be read by a machine that can automatically extract the data with 100% accuracy.

The main benefit of electronic structured formats is automation. Incalculable hours are spent by company administrators and book keeping teams manually receiving, forwarding, reading, validating, and extracting data from invoices and introducing the key details by hand into their accounting software. Its a tremendous waste of time.

In an ideal world we’d be able to send an e-invoice to our customers and the only thing they need to do is approve and pay automatically.

The promise of electronic business documents for companies is just that, to dramatically reduce the time wasted paper-pushing, or perhaps more accurately, PDF-pushing.

Increasingly governments around the world are starting to see the benefits of e-invoicing as a means to prevent tax fraud and have much greater visibility over business transactions.

Pioneering tax agencies like the SAT in Mexico launched their CFDI format back in 2004, and since 2012 have required all B2B transactions to be backed by e-invoices sent in real-time to be approved and “sealed” by the tax authorities.

​
Anatomy of an Invoice

In GOBL, an Invoice is represented by bill.Invoice.

There are some basic universal sections you’ll need to be aware about for any invoice:

  • Type - is this is standard invoice, proforma, credit note, etc.
  • Issue Date - an issue date shows when the invoice was sent, and there may also be “value” and “operation” dates.
  • Code - a single unique code that identifies the invoice, possibly also with an associated series to help group documents together. Most countries require codes to be generated consecutively.
  • Supplier - the party responsible for issuing the invoice, supplying the services, and requesting payment. Essential data would include the name, address, contact details, and most importantly, a country specific Tax Identity.
  • Customer - similar to the supplier, this is the party responsible for receiving the invoice, goods or services, and subsequently paying. A customer may not be required if issuing a simplified invoice.
  • Lines & Item - descriptions of what exactly is being sold, including their price, discounts, and any taxes that need to be applied.
  • Payment - not strictly necessary, but often included, these are instructions that help customers know how they need to send payment, or perhaps indications of what was already paid.
  • Totals - summary of the line item totals and taxes.

Of course, there are many more fields that can be added to an invoice document, but these are the basics.

​
Party & Tax Identity

An org.Party represents a company or a person. Aside from the contact details like addresses, telephone numbers, emails, websites, etc., a party also defines a tax_id property represented by a tax.Identity object.

The Tax Identity contains a single primary code defined by the local tax agency and has validation rules with check digits that ensure they are valid. Depending on the local tax system, a tax identity code is almost always required for the supplier and usually also for the customer.

GOBL contains tax identity code normalization and validation rules that help you ensure all tax IDs are stored correctly and can be easily indexed. For example, take a Spanish tax ID that you might receive via an email or note like "ES-B-986.026.42". GOBL will try to normalize the code so that it is presented as:

{
  "country": "ES",
  "code": "B98602642"
}

One of the first tasks we do when adding a new tax regime to GOBL is figuring out the local tax code validation rules and checksum calculations with the aim of creating a central and global source reference.

​
Invoice Types

GOBL defines a specific set of common types assigned to an invoice via the type property. Other standards define many more, but these are the ones we think are key for most use cases:

  • standard - a regular commercial invoice between a supplier and customer.
  • proforma - used to send a “preview” of the final invoice to a customer for their approval. If a customer approves a proforma invoice, they’re effectively entering into a contract with the supplier for the services or goods to be supplied, so while tax agencies don’t consider this an essential type for tax collection, they can have legal consequences.
  • corrective - indicates that this invoice performs corrections to a previous invoice identified in the preceding property defined as a bill.Preceding.
  • credit-note - traditional and most frequently used type when a supplier needs to issue a refund or cancel part of a preceding invoice.
  • debit-note - indicates that the preceding invoice was incomplete and there are now some additional costs. Most companies will just issue a new invoice to complement the previous one as opposed to issuing a specific debit note.

Not every country will have support for all these types. Spain for example doesn’t have support for credit-notes, and instead requires corrective invoices, more details below.

​
Invoice Scenarios

Some times the type of invoice alone is not enough to be able to classify a document, so each tax regime definition in GOBL has the option of defining “tax scenarios”. A scenario implies a combination of different key fields within an invoice, including a special field known in GOBL as “tax tags”.

For example, to define a “simplified invoice” in Spain, essentially an invoice without customer data, you’d include a tax tag called "simplified":

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "type": "standard",
  "tax": {
    "tags": ["simplified"]
  }
  // ....
}

In this example the validation rules for checking for the presence of the customer will be skipped.

Another common scenario deals with “reverse charge” invoices, a special VAT situation whereby the supplier is indicating that the taxes will be dealt with by the customer instead the supplier, and thus does not include any VAT. This is represented in GOBL using the "reverse-charge" tax tag, and will automatically include a special note.

The Italian FatturaPA format for example defines some 22 different invoice type codes that cover multiple different scenarios, including self billing. To support these we’ve defined a set of scenarios with different tags defined in the Italian tax regime. Here’s an example for an “Advance or down payment on a freelance invoice” type:

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "type": "standard",
  "tax": {
    "tags": ["partial", "freelance"]
  }
  // ....
}

Using that combination would result in a FatturaPA invoice with the type code: TD03. For more details, see the GOBL FatturaPA project.

​
Taxes and Rates

Coming soon…

​
Extensions

Coming soon…

​
Corrections, Credit and Debit Notes

Coming soon…

GOBL InsideBuilder