search

invopop / gobl

Go Business Language
Apache License 2.0
92 stars 8 forks source link
gobl

readme

GOBL

GOBL Logo

Go Business Language. Core library and Schemas.

Released under the Apache 2.0 LICENSE, Copyright 2021-2024 Invopop S.L..

Lint Test Go Go Report Card codecov GoDoc Latest Tag

Official GOBL documentation site.

Introduction

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

For examples on what GOBL document data looks like, please see the examples directory.

Community

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

Companion Projects

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

Conversion to local formats

Usage

GOBL is primarily 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 many different ways to get data into GOBL, but for the following example, we're going to try to 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: "billing@provideone.com",
            },
        },
        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@sample.com",
            },
        },
    },
    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)
}

CLI

This repo contains a gobl CLI tool which can be used to manipulate GOBL documents from the command line or shell scripts.

Build with:

mage -v build

Install with:

mage -v install

Build

Build expects a partial GOBL Envelope or Document, in either YAML or JSON as input. It'll automatically run the Calculate and Validate methods and output JSON data as either an envelope or document, according to the input source.

Example uses:

# Calculate and validate a YAML invoice
gobl build ./examples/es/invoice-es-es.yaml

# Output using indented formatting
gobl build -i ./examples/es/party.yaml

# Set the supplier from an external file
gobl build -i ./examples/es/invoice-es-es.yaml \
    --set-file customer=./examples/es/party.yaml

# Set arbitrary values from the command line. Inputs are parsed as YAML.
gobl build -i ./examples/es/invoice-es-es.yaml \
    --set meta.bar="a long string" \
    --set series="TESTING"

# Set the top-level object:
gobl build -i ./examples/es/invoice-es-es.yaml \
    --set-file .=./examples/es/invoice-es-es.env.yaml

# Insert a document into an envelope
gobl build -i --envelop ./examples/es/invoice-es-es.yaml

Correct

The GOBL CLI makes it easy to use the library and tax regime specific functionality that create a corrective document that reverts or amends a previous document. This is most useful for invoices and issuing refunds for example.

# Correct an invoice with a credit note (this will error for ES invoice!)
gobl correct -i ./examples/es/invoice-es-es.yaml --credit

# Specify tax regime specific details
gobl correct -i -d '{"credit":true,"changes":["line"],"method":"complete"}' \
    ./examples/es/invoice-es-es.yaml

Sign

GOBL encourages users to sign data embedded into envelopes using digital signatures. To get started, you'll need to have a JSON Web Key. Use the following commands to generate one:

# Generate a JSON Web Key and store in ~/.gobl/id_es256.jwk
gobl keygen

# Generate and output a JWK into a new file
gobl keygen ./examples/key.jwk

Use the key to sign documents:

# Add a signature to the envelope using our personal key
gobl sign -i ./examples/es/invoice-es-es.env.yaml

# Add a signature using a specific key
gobl sign -i --key ./examples/key.jwk ./examples/es/invoice-es-es.env.yaml

It is only possible to sign non-draft envelopes, so the CLI will automatically remove this flag during the signing process. This implies that the document must be completely valid before signing.

Development

GOBL uses the go generate command to automatically generate JSON schemas, definitions, and some Go code output. After any changes, be sure to run:

go generate .