Skip to content

invopop/gobl

Folders and files

NameName
Last commit message
Last commit date

Latest commit

7f1dcbd · Nov 8, 2023
Sep 21, 2023
Oct 9, 2023
Oct 9, 2023
Mar 1, 2023
Sep 5, 2023
Oct 9, 2023
Jul 19, 2023
Oct 9, 2023
Mar 2, 2023
May 17, 2023
Sep 6, 2023
Sep 20, 2023
Oct 9, 2023
May 5, 2023
Jul 24, 2023
Sep 18, 2023
Aug 25, 2023
Sep 21, 2023
Sep 5, 2023
Nov 8, 2023
Sep 28, 2023
Oct 9, 2023
Jun 29, 2023
Mar 27, 2023
Aug 30, 2023
Sep 2, 2020
Jan 13, 2022
Sep 11, 2023
Sep 20, 2023
Sep 11, 2023
Sep 6, 2023
Sep 28, 2023
Oct 9, 2023
Oct 9, 2023
Sep 5, 2023
Nov 4, 2021
Oct 9, 2023
Jun 20, 2022
Jun 20, 2022
Oct 9, 2023
Feb 10, 2022

Repository files navigation

GOBL

GOBL Logo

Go Business Language. Core library and Schemas.

Released under the Apache 2.0 LICENSE, Copyright 2021,2022 Invopop Ltd..

Lint Test Go Go Report Card GoDoc Latest Tag

Official GOBL documentation site.

Introduction

GOBL, the Go Business Language library and tools, aim to:

  • Help developers build electronic business documents, especially invoices, anywhere in the world.
  • Define a a set of open JSON Schema.
  • Build a global database of local tax categories and, whenever practical to do so, provide current and historical tax rates in code.
  • Validate business documents according to local requirements, including tax ID validation.
  • Define the algorithms used to make tax calculations while avoiding rounding errors.
  • Provide built-in support for signing documents using JSON Web Signatures.
  • Output simple and easy to read JSON documents that emphasize the use of keys instead of abstract codes, like credit-transfer instead of 30 (UNTDID4461 code for sender initiated bank or wire transfer).
  • Be flexible enough to support extreme local complexity but produce output that is easily legible in other countries.
  • Build a global community of contributors tired of the complexity of current standards based on XML or EDI.

Community

The complexity around invoicing and in particular electronic invoicing can quickly become overwhelming. Check out the following resources and get in touch:

  • Documentation contains details on how to use GOBL, and the schema.
  • Builder helps try out GOBL and quickly figure out what is possible, all from your browser.
  • Issues if you have a specific problem with GOBL related to code or usage.
  • Discussions for open discussions about the future of GOBL, complications with a specific country, or any open ended issues.
  • Pull Requests are very welcome, especially if you'd like to see a new local country or features.
  • Slack for real-time chat about something specific or urgent. We always encourage you to use one of the others options which are indexed and searchable, but if you'd like to bring something to attentional quickly, this is a great resource.

Companion Projects

GOBL makes it easy to create business documents, like invoices, but checkout some of the companion projects that help create, use, and convert into other formats:

Usage

GOBL is a Go library, so the following instructions assume you'd like to build documents from your own Go applications. See some of the links above if you'd like to develop in another language or use a CLI.

Installation

Run the following command to install the package:

go get github.com/invopop/gobl

Building an Invoice

There are lots of different ways to get data into GOBL but for the following example we're going to try and build an invoice in several steps.

First define a minimal or "partial" GOBL Invoice Document:

inv := &bill.Invoice{
	Series:    "F23",
	Code:      "00010",
	IssueDate: cal.MakeDate(2023, time.May, 11),
	Supplier: &org.Party{
		TaxID: &tax.Identity{
			Country: l10n.US,
		},
		Name:  "Provider One Inc.",
		Alias: "Provider One",
		Emails: []*org.Email{
			{
				Address: "[email protected]",
			},
		},
		Addresses: []*org.Address{
			{
				Number:   "16",
				Street:   "Jessie Street",
				Locality: "San Francisco",
				Region:   "CA",
				Code:     "94105",
				Country:  l10n.US,
			},
		},
	},
	Customer: &org.Party{
		Name: "Sample Customer",
		Emails: []*org.Email{
			{
				Address: "[email protected]",
			},
		},
	},
	Lines: []*bill.Line{
		{
			Quantity: num.MakeAmount(20, 0),
			Item: &org.Item{
				Name:  "A stylish mug",
				Price: num.MakeAmount(2000, 2),
				Unit:  org.UnitHour,
			},
			Taxes: []*tax.Combo{
				{
					Category: common.TaxCategoryST,
					Percent:  num.NewPercentage(85, 3),
				},
			},
		},
	},
}

Notice that the are no sums or calculations yet. The next step involves "inserting" the invoice document into an "envelope". In GOBL, we use the concept of an envelope to hold data and provide functionality to guarantee that no modifications have been made to the payload.

Insert our previous Invoice into an envelope as follows:

// Prepare an "Envelope"
env := gobl.NewEnvelope()
if err := env.Insert(inv); err != nil {
	panic(err)
}