{"id":31377495,"url":"https://github.com/invopop/gobl","last_synced_at":"2026-05-13T10:01:03.233Z","repository":{"id":37078844,"uuid":"292311963","full_name":"invopop/gobl","owner":"invopop","description":"Go Business Language","archived":false,"fork":false,"pushed_at":"2026-05-11T14:07:46.000Z","size":10047,"stargazers_count":276,"open_issues_count":43,"forks_count":52,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-11T15:15:59.503Z","etag":null,"topics":["gobl"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/invopop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-09-02T14:50:03.000Z","updated_at":"2026-05-08T16:13:41.000Z","dependencies_parsed_at":"2026-03-13T18:04:37.414Z","dependency_job_id":null,"html_url":"https://github.com/invopop/gobl","commit_stats":{"total_commits":974,"total_committers":12,"mean_commits":81.16666666666667,"dds":"0.30903490759753593","last_synced_commit":"1d8b0c35e549e621a7fca9e57cc64b77d35a3beb"},"previous_names":[],"tags_count":239,"template":false,"template_full_name":null,"purl":"pkg:github/invopop/gobl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invopop%2Fgobl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invopop%2Fgobl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invopop%2Fgobl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invopop%2Fgobl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/invopop","download_url":"https://codeload.github.com/invopop/gobl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/invopop%2Fgobl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32977273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T06:31:55.726Z","status":"ssl_error","status_checked_at":"2026-05-13T06:31:51.336Z","response_time":115,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gobl"],"created_at":"2025-09-28T05:00:45.266Z","updated_at":"2026-05-13T10:01:03.176Z","avatar_url":"https://github.com/invopop.png","language":"Go","funding_links":[],"categories":["金融","Financial","Invoice","Facturación Electrónica"],"sub_categories":["检索及分析资料库","Search and Analytic Databases","Electronic invoices","SII y Modelos AEAT"],"readme":"# GOBL\n\n\u003cimg src=\"https://github.com/invopop/gobl/blob/main/gobl_logo_black_rgb.svg#gh-light-mode-only\" width=\"181\" height=\"219\" alt=\"GOBL Logo\"\u003e\n\u003cimg src=\"https://github.com/invopop/gobl/blob/main/gobl_logo_white_rgb.svg#gh-dark-mode-only\" width=\"181\" height=\"219\" alt=\"GOBL Logo\"\u003e\n\nGo Business Language. Core library, schemas, and CLI.\n\nReleased under the Apache 2.0 [LICENSE](https://github.com/invopop/gobl/blob/main/LICENSE), Copyright 2021-2026 [Invopop S.L.](https://invopop.com).\n\n[![Lint](https://github.com/invopop/gobl/actions/workflows/lint.yaml/badge.svg)](https://github.com/invopop/gobl/actions/workflows/lint.yaml)\n[![Test Go](https://github.com/invopop/gobl/actions/workflows/test.yaml/badge.svg)](https://github.com/invopop/gobl/actions/workflows/test.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/invopop/gobl)](https://goreportcard.com/report/github.com/invopop/gobl)\n[![codecov](https://codecov.io/gh/invopop/gobl/graph/badge.svg?token=490W2CZVIT)](https://codecov.io/gh/invopop/gobl)\n[![GoDoc](https://godoc.org/github.com/invopop/gobl?status.svg)](https://godoc.org/github.com/invopop/gobl)\n![Latest Tag](https://img.shields.io/github/v/tag/invopop/gobl)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/invopop/gobl)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n[Official GOBL documentation site](https://docs.gobl.org).\n\n## Introduction\n\nGOBL, the Go Business Language library and tools, aim to:\n\n- Help developers build electronic business documents, especially invoices, anywhere in the world.\n- Define a set of open [JSON Schema](https://json-schema.org/).\n- Build a global database of local tax categories and, whenever practical to do so, provide current and historical tax rates in code.\n- Validate business documents according to local requirements, including tax ID validation.\n- Define the algorithms used to make tax calculations while avoiding rounding errors.\n- Provide built-in support for signing documents using [JSON Web Signatures](https://en.wikipedia.org/wiki/JSON_Web_Signature).\n- 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).\n- Be flexible enough to support extreme local complexity but produce output that is easily legible in other countries.\n- Build a global community of contributors tired of the complexity of current standards based on XML or EDI.\n\nFor examples on what GOBL document data looks like, please see the [examples directory](https://github.com/invopop/gobl/tree/main/examples).\n\n## Community\n\nThe complexity around invoicing, particularly electronic invoicing, can quickly become overwhelming. Check out the following resources and get in touch:\n\n- [Documentation](https://docs.gobl.org) contains details on how to use GOBL, and the schema.\n- [Builder](https://build.gobl.org) helps try out GOBL and quickly figure out what is possible, all from your browser.\n- [Issues](https://github.com/invopop/gobl/issues) if you have a specific problem with GOBL related to code or usage.\n- [Discussions](https://github.com/invopop/gobl/discussions) for open discussions about the future of GOBL, complications with a specific country, or any open-ended issues.\n- [Pull Requests](https://github.com/invopop/gobl/pulls) are very welcome, especially if you'd like to see a new local country or features.\n- [Slack](https://join.slack.com/t/goblschema/shared_invite/zt-20qu1s0cm-AUE8oYbGly681EsYdDiqxw) for real-time chat about something specific or urgent. We always encourage you to use one of the other options, which are indexed and searchable, but if you'd like to bring something to attention quickly, this is a great resource.\n\n## Companion Projects\n\nGOBL 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:\n\n- [Builder](https://github.com/invopop/gobl.builder) - Available to try at [build.gobl.org](https://build.gobl.org), this tool makes it easy to build, test, and discover the features of GOBL using the [wasm](https://webassembly.org/) binary in the browser.\n- [Generator](https://github.com/invopop/gobl.generator) - Ruby project to convert GOBL JSON Schema into libraries for other languages or documentation.\n- [Docs](https://github.com/invopop/gobl.docs) - Content of the official GOBL Documentation Site [docs.gobl.org](https://docs.gobl.org).\n- [GOBL for Ruby](https://github.com/invopop/gobl.ruby) - Easily build or read GOBL documents in Ruby.\n\nConversion to local and international formats:\n\n- [GOBL to HTML](https://github.com/invopop/gobl.html) - generate printable versions of GOBL documents ready to be converted to PDF.\n- [GOBL to FacturaE (Spain)](https://github.com/invopop/gobl.facturae) - convert into the [Spanish FacturaE](https://www.facturae.gob.es/Paginas/Index.aspx) format.\n- [GOBL to CFDI (Mexico)](https://github.com/invopop/gobl.cfdi) - convert into the Mexican CFDI format.\n- [GOBL to FatturaPA (Italy)](https://github.com/invopop/gobl.fatturapa) - convert into the [Italian FatturaPA](https://www.fatturapa.gov.it/it/index.html) format.\n- [GOBL to FA_VAT / KSeF (Poland)](https://github.com/invopop/gobl.ksef) - convert to the Polish FA_VAT format and send to [KSeF](https://www.podatki.gov.pl/ksef/)\n- [GOBL to TicketBAI (Spain/Euskadi)](https://github.com/invopop/gobl.ticketbai) - convert into [TicketBAI](https://www.batuz.eus/fitxategiak/batuz/ticketbai/ticketBaiV1-2.xsd) documents, required in the Euskadi (northern region of Spain)\n- [GOBL to VERI\\*FACTU (Spain)](https://github.com/invopop/gobl.verifactu) - convert and send to the Spanish tax authorities.\n- [GOBL UBL](https://github.com/invopop/gobl.ubl) - convert to and from the OASIS Universal Business Language, including support for local and global profiles such as for Peppol and XRechnung (Germany)\n- [GOBL CII](https://github.com/invopop/gobl.cii) - convert to and from the Cross Industry Invoice (CII) XML format, including regional variants including Factur-X (France), ZUGFeRD and XRechnung (Germany).\n- [GOBL to Stripe](https://github.com/invopop/gobl.stripe) - support for creating GOBL invoices from stripe API data.\n\n## Usage\n\nGOBL 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.\n\n### Installation\n\nRun the following command to install the package:\n\n```\ngo get github.com/invopop/gobl\n```\n\n### Building an Invoice\n\nThere 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.\n\nFirst define a minimal or \"partial\" GOBL Invoice Document:\n\n```go\ninv := \u0026bill.Invoice{\n\tSeries:    \"F23\",\n\tCode:      \"00010\",\n\tIssueDate: cal.MakeDate(2023, time.May, 11),\n\tSupplier: \u0026org.Party{\n\t\tTaxID: \u0026tax.Identity{\n\t\t\tCountry: l10n.US,\n\t\t},\n\t\tName:  \"Provider One Inc.\",\n\t\tAlias: \"Provider One\",\n\t\tEmails: []*org.Email{\n\t\t\t{\n\t\t\t\tAddress: \"billing@provideone.com\",\n\t\t\t},\n\t\t},\n\t\tAddresses: []*org.Address{\n\t\t\t{\n\t\t\t\tNumber:   \"16\",\n\t\t\t\tStreet:   \"Jessie Street\",\n\t\t\t\tLocality: \"San Francisco\",\n\t\t\t\tRegion:   \"CA\",\n\t\t\t\tCode:     \"94105\",\n\t\t\t\tCountry:  l10n.US,\n\t\t\t},\n\t\t},\n\t},\n\tCustomer: \u0026org.Party{\n\t\tName: \"Sample Customer\",\n\t\tEmails: []*org.Email{\n\t\t\t{\n\t\t\t\tAddress: \"email@sample.com\",\n\t\t\t},\n\t\t},\n\t},\n\tLines: []*bill.Line{\n\t\t{\n\t\t\tQuantity: num.MakeAmount(20, 0),\n\t\t\tItem: \u0026org.Item{\n\t\t\t\tName:  \"A stylish mug\",\n\t\t\t\tPrice: num.MakeAmount(2000, 2),\n\t\t\t\tUnit:  org.UnitHour,\n\t\t\t},\n\t\t\tTaxes: []*tax.Combo{\n\t\t\t\t{\n\t\t\t\t\tCategory: common.TaxCategoryST,\n\t\t\t\t\tPercent:  num.NewPercentage(85, 3),\n\t\t\t\t},\n\t\t\t},\n\t\t},\n\t},\n}\n```\n\nNotice 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.\n\nInsert our previous Invoice into an envelope as follows:\n\n```go\n// Prepare an \"Envelope\"\nenv := gobl.NewEnvelope()\nif err := env.Insert(inv); err != nil {\n\tpanic(err)\n}\n```\n\n## CLI\n\nThis repo contains a `gobl` CLI tool which can be used to manipulate GOBL documents from the command line or shell scripts.\n\nBuild with:\n\n```sh\nmage -v build\n```\n\nInstall with:\n\n```sh\nmage -v install\n```\n\n### Build\n\nBuild 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.\n\nExample uses:\n\n```sh\n# Calculate and validate a YAML invoice\ngobl build ./examples/es/invoice-es-es.yaml\n\n# Output using indented formatting\ngobl build -i ./examples/es/party.yaml\n\n# Set the supplier from an external file\ngobl build -i ./examples/es/invoice-es-es.yaml \\\n    --set-file customer=./examples/es/party.yaml\n\n# Set arbitrary values from the command line. Inputs are parsed as YAML.\ngobl build -i ./examples/es/invoice-es-es.yaml \\\n    --set meta.bar=\"a long string\" \\\n    --set series=\"TESTING\"\n\n# Set the top-level object:\ngobl build -i ./examples/es/invoice-es-es.yaml \\\n    --set-file .=./examples/es/invoice-es-es.env.yaml\n\n# Insert a document into an envelope\ngobl build -i --envelop ./examples/es/invoice-es-es.yaml\n```\n\n### Correct\n\nThe 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.\n\n```sh\n# Correct an invoice with a credit note (this will error for ES invoice!)\ngobl correct -i ./examples/es/invoice-es-es.yaml --credit\n\n# Specify tax regime specific details\ngobl correct -i -d '{\"credit\":true,\"changes\":[\"line\"],\"method\":\"complete\"}' \\\n    ./examples/es/invoice-es-es.yaml\n```\n\n### Sign\n\nGOBL 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:\n\n```sh\n# Generate a JSON Web Key and store in ~/.gobl/id_es256.jwk\ngobl keygen\n\n# Generate and output a JWK into a new file\ngobl keygen ./examples/key.jwk\n```\n\nUse the key to sign documents:\n\n```sh\n# Add a signature to the envelope using our personal key\ngobl sign -i ./examples/es/invoice-es-es.env.yaml\n\n# Add a signature using a specific key\ngobl sign -i --key ./examples/key.jwk ./examples/es/invoice-es-es.env.yaml\n```\n\nIt 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.\n\n### Validate\n\nValidate checks a GOBL document for errors without modifying it:\n\n```sh\n# Validate an existing envelope\ngobl validate ./examples/es/invoice-es-es.env.yaml\n```\n\n### Verify\n\nVerify checks the digital signature and digest of a signed GOBL envelope:\n\n```sh\n# Verify a signed envelope using a specific public key\ngobl verify --key ./examples/id_es256.pub.jwk ./examples/es/invoice-es-es.env.yaml\n```\n\n### Replicate\n\nReplicate creates a copy of a document with a new UUID and issue date, useful for generating a new document based on an existing one:\n\n```sh\n# Create a replica of an invoice\ngobl replicate ./examples/es/invoice-es-es.env.yaml\n```\n\n### Serve\n\nLaunch the GOBL HTTP API server, which exposes endpoints for building, validating, correcting, and signing documents, as well as reference data for regimes, addons, and schemas:\n\n```sh\n# Start the server on the default port (80)\ngobl serve\n\n# Start the server on a custom port\ngobl serve -p 8080\n```\n\nThe server includes a built-in web editor UI at the root path, an OpenAPI spec at `/v0/openapi.json`, and an MCP endpoint at `/v0/mcp`.\n\n### MCP\n\nLaunch a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio, allowing AI tools and editors to interact with GOBL:\n\n```sh\n# Start the MCP server\ngobl mcp\n```\n\n## Development\n\nGOBL uses the `go generate` command to automatically generate JSON schemas, definitions, and some Go code output. After any changes, be sure to run:\n\n```bash\ngo generate .\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvopop%2Fgobl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finvopop%2Fgobl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finvopop%2Fgobl/lists"}