ubl

package module
v0.52.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 23, 2026 License: Apache-2.0 Imports: 35 Imported by: 3

README

GOBL.UBL

GOBL conversion into UBL XML format and vice versa.

codecov Ask DeepWiki

Copyright Invopop Ltd. 2025. Released publicly under the Apache License Version 2.0. For commercial licenses, please contact the dev team at invopop. To accept contributions to this library, we require transferring copyrights to Invopop Ltd.

Usage

Go Package

Usage of the GOBL to UBL conversion library is straightforward and supports bidirectional conversion:

  1. Convert GOBL to UBL XML: You must first have a GOBL Envelope, including an invoice, ready to convert. There are some samples in the test/data directory.

  2. Parse UBL XML into GOBL: You need to have a valid UBL XML document that you want to convert to GOBL format.

Both conversion directions are supported, allowing you to seamlessly transform between GOBL and UBL XML formats as needed.

Convert GOBL to UBL
package main

import (
    "os"

    "github.com/invopop/gobl"
    ubl "github.com/invopop/gobl.ubl"
)

func main() {
    data, _ := os.ReadFile("./test/data/invoice-sample.json")

    env := new(gobl.Envelope)
    if err := json.Unmarshal(data, env); err != nil {
        panic(err)
    }

    // Prepare the UBL Invoice document
    doc, err := ubl.ConvertInvoice(env)
    if err != nil {
        panic(err)
    }

    // Create the XML output
    out, err := doc.Bytes()
    if err != nil {
        panic(err)
    }

}

The ubl package also supports using specific of custom contexts that can be used to generate documents with specific customization and profile identifiers. To use something other than the default, add the options during conversion. For example:

doc, err := ubl.ConvertInvoice(env, ubl.WithContext(ubl.ContextPeppol))
UBL to GOBL
package main

import (
    "encoding/json"
    "os"

    ubl "github.com/invopop/gobl.ubl"
)

func main() {
    // Read the UBL XML file
    inData, err := os.ReadFile("path/to/ubl_invoice.xml")
    if err != nil {
        panic(err)
    }

    // Parse the UBL document
    doc, err := ubl.Parse(inData)
    if err != nil {
        panic(err)
    }

    // Type assert to the appropriate document type
    inv, ok := doc.(*ubl.Invoice)
    if !ok {
        panic("expected an invoice document")
    }

    // Convert to GOBL envelope
    env, err := inv.Convert()
    if err != nil {
        panic(err)
    }

    // Extract binary attachments if needed
    attachments := inv.ExtractBinaryAttachments()

    // Marshal to JSON
    outputData, err := json.MarshalIndent(env, "", "  ")
    if err != nil {
        panic(err)
    }
}

Command Line

The GOBL to UBL tool includes a command-line helper. You can install it manually in your Go environment with:

go install ./cmd/gobl.ubl

Once installed, usage is straightforward. The tool automatically detects the input file type and performs the appropriate conversion:

  • If the input is a JSON file (GOBL format), it will convert it to UBL XML.
  • If the input is an XML file (UBL format), it will convert it to GOBL JSON.

For example:

gobl.ubl convert ./test/data/invoice-sample.json

Testing

testify

The library uses testify for testing. To run the tests, you can use the following command:

go test ./...

Considerations

There are certain assumptions and lost information in the conversion from UBL to GOBL that should be considered:

  1. GOBL does not currently support additional embedded documents, so the AdditionalReferencedDocument field (BG-24 in EN 16931) is not supported and lost in the conversion.
  2. GOBL only supports a single period in the ordering, so only the first InvoicePeriod (BG-14) in the UBL is taken.
  3. Fields ProfileID (BT-23) and CustomizationID (BT-24) in UBL are not supported and lost in the conversion.
  4. The AccountingCost (BT-19, BT-133) fields are added as notes.
  5. Payment advances do not include their own tax rate, they use the global tax rate of the invoice.

Development

The main source of information for this project comes from the EN 16931 standard, developed by the EU for electronic invoicing. Part 1 of the standard defines the semantic data model that forms an invoice, but does not provide a concrete implementation. Part 3.2 defines the mappings from the semantic data model to the UBL 2.1 XML format covered in this repository.

Useful links:

Documentation

Overview

Package ubl helps convert GOBL into UBL documents and vice versa.

Index

Constants

View Source 
const (
	NamespaceCBC  = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
	NamespaceCAC  = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
	NamespaceQDT  = "urn:oasis:names:specification:ubl:schema:xsd:QualifiedDataTypes-2"
	NamespaceUDT  = "urn:oasis:names:specification:ubl:schema:xsd:UnqualifiedDataTypes-2"
	NamespaceEXT  = "urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2"
	NamespaceCCTS = "urn:un:unece:uncefact:documentation:2"
	NamespaceSIG  = "urn:oasis:names:specification:ubl:schema:xsd:CommonSignatureComponents-2"
	NamespaceSAC  = "urn:oasis:names:specification:ubl:schema:xsd:SignatureAggregateComponents-2"
	NamespaceSBC  = "urn:oasis:names:specification:ubl:schema:xsd:SignatureBasicComponents-2"
	NamespaceXSI  = "http://www.w3.org/2001/XMLSchema-instance"
)

UBL schema constants

View Source 
const (
	PeppolFranceProcessIDRegulated    = "urn:peppol:france:billing:regulated"
	PeppolFranceProcessIDNonRegulated = "urn:peppol:france:billing:non-regulated"
)

Peppol France Process IDs

View Source 
const (
	NamespaceUBLInvoice    = "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
	NamespaceUBLCreditNote = "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
)

Main UBL Invoice Namespace

View Source 
const (
	SchemaLocationInvoice     = "" /* 128-byte string literal not displayed */
	SchemaLocationCrediteNote = "" /* 135-byte string literal not displayed */
)

Schema locationa and customization constants

View Source 
const (
	SignatureInformationID = "urn:oasis:names:specification:ubl:signature:1"
	ReferenceSignatureID   = "urn:oasis:names:specification:ubl:signature:Invoice"
	SignatureMethod        = "urn:oasis:names:specification:ubl:dsig:enveloped:xades"
)

UBL signature constants.

View Source 
const (
	PeppolBillingProfileIDDefault = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
)

Peppol Billing Profile IDs

View Source 
const SchemeIDEmail = "EM"

SchemeIDEmail is the EAS codelist value for email

View Source 
const TaxSchemeVAT = "VAT"

TaxSchemeVAT is the tax scheme code for VAT

View Source 
const Version = "2.1"

Version is the version of UBL documents that will be generated by this package.

Variables

View Source 
var (
	// ErrUnknownDocumentType is returned when the document type
	// is not recognized during parsing.
	ErrUnknownDocumentType = fmt.Errorf("unknown document type")

	// ErrUnsupportedDocumentType is returned when the document type
	// is not supported for conversion.
	ErrUnsupportedDocumentType = fmt.Errorf("unsupported document type")
)
View Source 
var ContextEN16931 = Context{
	CustomizationID: "urn:cen.eu:en16931:2017",
	Addons:          []cbc.Key{en16931.V2017},
	VESIDs: VESIDMapping{
		Invoice:    "eu.cen.en16931:ubl:1.3.14-2",
		CreditNote: "eu.cen.en16931:ubl-creditnote:1.3.15",
	},
}

ContextEN16931 is the default context for basic UBL documents.

View Source 
var ContextPeppol = Context{
	CustomizationID: "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",
	ProfileID:       PeppolBillingProfileIDDefault,
	Addons:          []cbc.Key{en16931.V2017},
	VESIDs: VESIDMapping{
		Invoice:    "eu.peppol.bis3:invoice:2025.5",
		CreditNote: "eu.peppol.bis3:creditnote:2025.5",
	},
}

ContextPeppol defines the default Peppol context.

View Source 
var ContextPeppolFranceCIUS = Context{
	CustomizationID:       "urn:cen.eu:en16931:2017#compliant#urn:peppol:france:billing:cius:1.0",
	ProfileID:             PeppolFranceProcessIDRegulated,
	OutputCustomizationID: "urn:cen.eu:en16931:2017",
	Addons:                []cbc.Key{flow2.V1},
	VESIDs: VESIDMapping{
		Invoice:    "fr.ctc:ubl-invoice:1.3.1",
		CreditNote: "fr.ctc:ubl-creditnote:1.3.1",
	},
}

ContextPeppolFranceCIUS defines the context for France UBL Invoice CIUS.

View Source 
var ContextPeppolFranceExtended = Context{
	CustomizationID:       "urn:cen.eu:en16931:2017#conformant#urn:peppol:france:billing:extended:1.0",
	ProfileID:             PeppolFranceProcessIDRegulated,
	OutputCustomizationID: "urn:cen.eu:en16931:2017#conformant#urn.cpro.gouv.fr:1p0:extended-ctc-fr",
	Addons:                []cbc.Key{facturx.V1},
	VESIDs: VESIDMapping{
		Invoice:    "fr.ctc:extended-ubl-invoice:1.3.1",
		CreditNote: "fr.ctc:extended-ubl-creditnote:1.3.1",
	},
}

ContextPeppolFranceExtended defines the context for France UBL Invoice Extended.

View Source 
var ContextPeppolSelfBilled = Context{
	CustomizationID: "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0",
	ProfileID:       "urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0",
	Addons:          []cbc.Key{en16931.V2017},

	VESIDs: VESIDMapping{
		Invoice:    "eu.peppol.bis3:invoice-self-billing:2026.3",
		CreditNote: "eu.peppol.bis3:creditnote-self-billing:2026.3",
	},
}

ContextPeppolSelfBilled defines the Peppol self-billed context.

View Source 
var ContextXRechnung = Context{
	CustomizationID: "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
	ProfileID:       PeppolBillingProfileIDDefault,
	Addons:          []cbc.Key{xrechnung.V3},
	VESIDs: VESIDMapping{
		Invoice:    "de.xrechnung:ubl-invoice:3.0.2",
		CreditNote: "de.xrechnung:ubl-creditnote:3.0.2",
	},
}

ContextXRechnung defines the main context to use for XRechnung UBL documents.

View Source 
var ContextZATCA = Context{
	CustomizationID: "urn:cen.eu:en16931:2017#compliant#urn:zatca.gov.sa:e-invoicing:1.0",
	ProfileID:       "reporting:1.0",
	Addons:          []cbc.Key{zatca.V1},
	VESIDs: VESIDMapping{
		Invoice:    "sa.zatca:ubl-invoice:2.3.8",
		CreditNote: "sa.zatca:ubl-invoice:2.3.8",
	},
}

ContextZATCA defines the context for Saudi Arabia ZATCA Phase 2 e-invoicing.

View Source 
var InvoiceTagMap = map[string][]cbc.Key{
	"389": {tax.TagSelfBilled},
	"326": {tax.TagPartial},
	"261": {tax.TagSelfBilled},
}

InvoiceTagMap maps UBL invoice type codes to GOBL tax tags.

Functions

func Bytes added in v0.18.0 

func Bytes(in any) ([]byte, error)

Bytes returns the raw XML of the UBL document including the XML Header.

func BytesCompact added in v0.48.0 

func BytesCompact(in any) ([]byte, error)

BytesCompact returns the raw XML of the UBL document without indentation, including the XML Header.

func Convert added in v0.7.0 

func Convert(env *gobl.Envelope, opts ...Option) (any, error)

Convert takes a GOBL envelope and converts to a UBL document of one of the supported types.

Add a WithContext option to specify the desired UBL Guideline and Profile ID. If none is provided, EN16931 will be used by default.

func Parse added in v0.7.0 

func Parse(data []byte) (any, error)

Parse parses a raw UBL document and returns the underlying Go struct. The returned value should be type asserted to the appropriate type.

Supported types:

  • *Invoice (for both Invoice and CreditNote documents)

Example usage: 

doc, err := ubl.Parse(xmlData)
if err != nil {
    // handle error
}
if inv, ok := doc.(*ubl.Invoice); ok {
    env, err := inv.Convert()
    attachments := inv.ExtractBinaryAttachments()
    // ...
}

Types

type AdditionalItemProperty added in v0.5.0 

type AdditionalItemProperty struct {
	Name  string `xml:"cbc:Name"`
	Value string `xml:"cbc:Value"`
}

AdditionalItemProperty represents an additional property of an item

type AddressLine added in v0.5.0 

type AddressLine struct {
	Line string `xml:"cbc:Line"`
}

AddressLine represents a line in an address

type AllowanceCharge added in v0.5.0 

type AllowanceCharge struct {
	ChargeIndicator           bool           `xml:"cbc:ChargeIndicator"`
	AllowanceChargeReasonCode *string        `xml:"cbc:AllowanceChargeReasonCode"`
	AllowanceChargeReason     *string        `xml:"cbc:AllowanceChargeReason"`
	MultiplierFactorNumeric   *string        `xml:"cbc:MultiplierFactorNumeric"`
	Amount                    Amount         `xml:"cbc:Amount"`
	BaseAmount                *Amount        `xml:"cbc:BaseAmount"`
	TaxCategory               []*TaxCategory `xml:"cac:TaxCategory"`
}

AllowanceCharge represents an allowance or charge

type Amount added in v0.5.0 

type Amount struct {
	CurrencyID *string `xml:"currencyID,attr"`
	Value      string  `xml:",chardata"`
}

Amount represents a monetary amount

type Attachment added in v0.5.0 

type Attachment struct {
	ExternalReference            *ExternalReference `xml:"cac:ExternalReference,omitempty"`
	EmbeddedDocumentBinaryObject *BinaryObject      `xml:"cbc:EmbeddedDocumentBinaryObject,omitempty"`
}

Attachment represents an attached document

type BillingReference added in v0.5.0 

type BillingReference struct {
	InvoiceDocumentReference           *Reference `xml:"cac:InvoiceDocumentReference,omitempty"`
	SelfBilledInvoiceDocumentReference *Reference `xml:"cac:SelfBilledInvoiceDocumentReference,omitempty"`
	CreditNoteDocumentReference        *Reference `xml:"cac:CreditNoteDocumentReference,omitempty"`
	AdditionalDocumentReference        *Reference `xml:"cac:AdditionalDocumentReference,omitempty"`
}

BillingReference represents a reference to a billing document

type BinaryAttachment added in v0.18.0 

type BinaryAttachment struct {
	// ID is the identifier for this attachment reference
	ID string
	// Description provides a human-readable description of the attachment
	Description string
	// Data contains the raw binary data (automatically base64-encoded/decoded as needed)
	Data []byte
	// MimeCode specifies the MIME type (e.g., "application/pdf")
	MimeCode string
	// Filename is the name of the file
	Filename string
	// CharacterSetCode specifies the character set if applicable
	CharacterSetCode string
	// URI can optionally reference where the document is located
	URI string
}

BinaryAttachment represents a binary attachment that can be extracted from or added to a UBL invoice.

type BinaryObject added in v0.5.0 

type BinaryObject struct {
	MimeCode         *string `xml:"mimeCode,attr"`
	Filename         *string `xml:"filename,attr"`
	EncodingCode     *string `xml:"encodingCode,attr"`
	CharacterSetCode *string `xml:"characterSetCode,attr"`
	URI              *string `xml:"uri,attr"`
	Value            string  `xml:",chardata"`
}

BinaryObject represents binary data with associated metadata

type Branch added in v0.5.0 

type Branch struct {
	ID   *string `xml:"cbc:ID"`
	Name *string `xml:"cbc:Name"`
}

Branch represents a branch of a financial institution

type CardAccount added in v0.5.0 

type CardAccount struct {
	PrimaryAccountNumberID *string `xml:"cbc:PrimaryAccountNumberID"`
	NetworkID              *string `xml:"cbc:NetworkID"`
	HolderName             *string `xml:"cbc:HolderName"`
}

CardAccount represents a card account

type ClassifiedTaxCategory added in v0.5.0 

type ClassifiedTaxCategory struct {
	ID        *string    `xml:"cbc:ID,omitempty"`
	Percent   *string    `xml:"cbc:Percent,omitempty"`
	TaxScheme *TaxScheme `xml:"cac:TaxScheme,omitempty"`
}

ClassifiedTaxCategory represents a classified tax category

type CommodityClassification added in v0.5.0 

type CommodityClassification struct {
	ItemClassificationCode *IDType `xml:"cbc:ItemClassificationCode"`
}

CommodityClassification represents a commodity classification

type Contact added in v0.5.0 

type Contact struct {
	Name           *string `xml:"cbc:Name"`
	Telephone      *string `xml:"cbc:Telephone"`
	ElectronicMail *string `xml:"cbc:ElectronicMail"`
}

Contact represents contact information

type Context added in v0.5.0 

type Context struct {
	// CustomizationID identifies specific characteristics in the
	// document which need to be present for local differences.
	CustomizationID string
	// ProfileID determines the business process context or scenario
	// for the exchange of the document. For contexts like French CIUS/Extended,
	// this is the Peppol process ID used in the SBDH, while the UBL XML ProfileID
	// is overridden by the billing mode from the GOBL invoice.
	ProfileID string
	// OutputCustomizationID optionally specifies a different CustomizationID
	// to use in the actual generated UBL XML document. If empty, CustomizationID
	// is used. This allows the context to be identified by one ID externally while
	// generating different values in the XML output.
	OutputCustomizationID string
	// Addons contains the list of Addons required for this CustomizationID
	// and ProfileID.
	Addons []cbc.Key
	// VESIDs contains the VESID (Validation Exchange Specification ID) mappings
	// for different document types and scenarios within this context.
	VESIDs VESIDMapping
}

Context is used to ensure that the generated UBL document uses a specific CustomizationID and ProfileID when generating the output document.

func FindContext added in v0.11.0 

func FindContext(customizationID string, profileID string) *Context

FindContext looks up a context by CustomizationID and optionally ProfileID. Returns nil if no matching context is found.

The lookup logic works as follows:

  1. If the ProfileID is a French billing mode code, checks for a context whose OutputCustomizationID matches (France CIUS documents use EN16931's CustomizationID in the XML but can be identified by their billing mode ProfileID)
  2. Tries to match on the full CustomizationID (for external identification)
  3. If not found, tries to match on OutputCustomizationID (for parsing incoming documents)

func (*Context) GetVESID added in v0.22.0 

func (c *Context) GetVESID(inv *bill.Invoice) string

GetVESID returns the appropriate VESID based on the invoice type.

func (*Context) Is added in v0.12.0 

func (c *Context) Is(c2 Context) bool

Is checks if two contexts are the same.

type Country added in v0.5.0 

type Country struct {
	IdentificationCode string `xml:"cbc:IdentificationCode"`
}

Country represents a country

type CustomerParty added in v0.5.0 

type CustomerParty struct {
	Party *Party `xml:"cac:Party"`
}

CustomerParty represents the customer party in a transaction

type Delivery added in v0.5.0 

type Delivery struct {
	ActualDeliveryDate      *string   `xml:"cbc:ActualDeliveryDate"`
	LatestDeliveryDate      *string   `xml:"cbc:LatestDeliveryDate"`
	DeliveryLocation        *Location `xml:"cac:DeliveryLocation"`
	EstimatedDeliveryPeriod *Period   `xml:"cac:EstimatedDeliveryPeriod"`
	DeliveryParty           *Party    `xml:"cac:DeliveryParty"`
}

Delivery represents delivery information

type DeliveryTerms added in v0.5.0 

type DeliveryTerms struct {
	ID string `xml:"cbc:ID"`
}

DeliveryTerms represents the terms of delivery

type DocumentSignatures added in v0.48.0 

type DocumentSignatures struct {
	SIGNamespace         string                `xml:"xmlns:sig,attr"`
	SACNamespace         string                `xml:"xmlns:sac,attr"`
	SBCNamespace         string                `xml:"xmlns:sbc,attr"`
	SignatureInformation *SignatureInformation `xml:"sac:SignatureInformation"`
}

DocumentSignatures contains the signature information block.

type EndpointID added in v0.5.0 

type EndpointID struct {
	SchemeID string `xml:"schemeID,attr"`
	Value    string `xml:",chardata"`
}

EndpointID represents an endpoint identifier

type ExchangeRate added in v0.5.0 

type ExchangeRate struct {
	SourceCurrencyCode *string `xml:"cbc:SourceCurrencyCode"`
	TargetCurrencyCode *string `xml:"cbc:TargetCurrencyCode"`
	CalculationRate    *string `xml:"cbc:CalculationRate"`
	Date               *string `xml:"cbc:Date"`
}

ExchangeRate represents an exchange rate

type Extension added in v0.5.0 

type Extension struct {
	ExtensionURI     *string           `xml:"ext:ExtensionURI"`
	ExtensionContent *ExtensionContent `xml:"ext:ExtensionContent"`
}

Extension represents a single UBL extension.

func NewExtension added in v0.48.0 

func NewExtension() *Extension

NewExtension creates a new extension

type ExtensionContent added in v0.48.0 

type ExtensionContent struct {
	UBLDocumentSignatures *DocumentSignatures `xml:"sig:UBLDocumentSignatures"`
}

ExtensionContent wraps the content of a UBL extension.

type Extensions added in v0.5.0 

type Extensions struct {
	Extension []Extension `xml:"ext:UBLExtension"`
}

Extensions wraps a list of UBL extensions.

type ExternalReference added in v0.18.0 

type ExternalReference struct {
	URI                 string `xml:"cbc:URI,omitempty"`
	DocumentHash        string `xml:"cbc:DocumentHash,omitempty"`
	HashAlgorithmMethod string `xml:"cbc:HashAlgorithmMethod,omitempty"`
	ExpiryDate          string `xml:"cbc:ExpiryDate,omitempty"`
	ExpiryTime          string `xml:"cbc:ExpiryTime,omitempty"`
	MimeCode            string `xml:"cbc:MimeCode,omitempty"`
	FormatCode          string `xml:"cbc:FormatCode,omitempty"`
	EncodingCode        string `xml:"cbc:EncodingCode,omitempty"`
	CharacterSetCode    string `xml:"cbc:CharacterSetCode,omitempty"`
	FileName            string `xml:"cbc:FileName,omitempty"`
	Description         string `xml:"cbc:Description,omitempty"`
}

ExternalReference represents a reference to an external resource

type FinancialAccount added in v0.5.0 

type FinancialAccount struct {
	ID                         *string `xml:"cbc:ID"`
	Name                       *string `xml:"cbc:Name"`
	FinancialInstitutionBranch *Branch `xml:"cac:FinancialInstitutionBranch"`
	AccountTypeCode            *string `xml:"cbc:AccountTypeCode"`
}

FinancialAccount represents a financial account

type IDType added in v0.5.0 

type IDType struct {
	ListID        *string `xml:"listID,attr"`
	ListVersionID *string `xml:"listVersionID,attr"`
	SchemeID      *string `xml:"schemeID,attr"`
	SchemeName    *string `xml:"schemeName,attr"`
	Name          *string `xml:"name,attr"`
	Value         string  `xml:",chardata"`
}

IDType represents an ID with optional scheme attributes

type Identification added in v0.5.0 

type Identification struct {
	ID *IDType `xml:"cbc:ID"`
}

Identification represents an identification

type Invoice added in v0.5.0 

type Invoice struct {
	// Attributes
	XMLName        xml.Name
	CACNamespace   string `xml:"xmlns:cac,attr"`
	CBCNamespace   string `xml:"xmlns:cbc,attr"`
	QDTNamespace   string `xml:"xmlns:qdt,attr"`
	UDTNamespace   string `xml:"xmlns:udt,attr"`
	CCTSNamespace  string `xml:"xmlns:ccts,attr"`
	UBLNamespace   string `xml:"xmlns,attr"`
	XSINamespace   string `xml:"xmlns:xsi,attr"`
	EXTNamespace   string `xml:"xmlns:ext,attr"`
	SchemaLocation string `xml:"xsi:schemaLocation,attr,omitempty"`

	Extensions         *Extensions `xml:"ext:UBLExtensions,omitempty"`
	UBLVersionID       string      `xml:"cbc:UBLVersionID,omitempty"`
	CustomizationID    string      `xml:"cbc:CustomizationID,omitempty"`
	ProfileID          string      `xml:"cbc:ProfileID,omitempty"`
	ProfileExecutionID string      `xml:"cbc:ProfileExecutionID,omitempty"`
	ID                 string      `xml:"cbc:ID"`
	CopyIndicator      bool        `xml:"cbc:CopyIndicator,omitempty"`
	UUID               string      `xml:"cbc:UUID,omitempty"`
	IssueDate          string      `xml:"cbc:IssueDate"`
	IssueTime          string      `xml:"cbc:IssueTime,omitempty"`
	DueDate            string      `xml:"cbc:DueDate,omitempty"`

	InvoiceTypeCode    *IDType `xml:"cbc:InvoiceTypeCode,omitempty"`
	CreditNoteTypeCode *IDType `xml:"cbc:CreditNoteTypeCode,omitempty"`

	Note                           []string            `xml:"cbc:Note,omitempty"`
	TaxPointDate                   string              `xml:"cbc:TaxPointDate,omitempty"`
	DocumentCurrencyCode           string              `xml:"cbc:DocumentCurrencyCode,omitempty"`
	TaxCurrencyCode                string              `xml:"cbc:TaxCurrencyCode,omitempty"`
	PricingCurrencyCode            string              `xml:"cbc:PricingCurrencyCode,omitempty"`
	PaymentCurrencyCode            string              `xml:"cbc:PaymentCurrencyCode,omitempty"`
	PaymentAlternativeCurrencyCode string              `xml:"cbc:PaymentAlternativeCurrencyCode,omitempty"`
	AccountingCost                 string              `xml:"cbc:AccountingCost,omitempty"`
	LineCountNumeric               int                 `xml:"cbc:LineCountNumeric,omitempty"`
	BuyerReference                 string              `xml:"cbc:BuyerReference,omitempty"`
	InvoicePeriod                  []Period            `xml:"cac:InvoicePeriod,omitempty"`
	OrderReference                 *OrderReference     `xml:"cac:OrderReference,omitempty"`
	BillingReference               []*BillingReference `xml:"cac:BillingReference,omitempty"`
	DespatchDocumentReference      []Reference         `xml:"cac:DespatchDocumentReference,omitempty"`
	ReceiptDocumentReference       []Reference         `xml:"cac:ReceiptDocumentReference,omitempty"`
	StatementDocumentReference     []Reference         `xml:"cac:StatementDocumentReference,omitempty"`
	OriginatorDocumentReference    []Reference         `xml:"cac:OriginatorDocumentReference,omitempty"`
	ContractDocumentReference      []Reference         `xml:"cac:ContractDocumentReference,omitempty"`
	AdditionalDocumentReference    []Reference         `xml:"cac:AdditionalDocumentReference,omitempty"`
	ProjectReference               []ProjectReference  `xml:"cac:ProjectReference,omitempty"`
	Signature                      []Signature         `xml:"cac:Signature,omitempty"`
	AccountingSupplierParty        SupplierParty       `xml:"cac:AccountingSupplierParty"`
	AccountingCustomerParty        CustomerParty       `xml:"cac:AccountingCustomerParty"`
	PayeeParty                     *Party              `xml:"cac:PayeeParty,omitempty"`
	BuyerCustomerParty             *CustomerParty      `xml:"cac:BuyerCustomerParty,omitempty"`
	SellerSupplierParty            *SupplierParty      `xml:"cac:SellerSupplierParty,omitempty"`
	TaxRepresentativeParty         *Party              `xml:"cac:TaxRepresentativeParty,omitempty"`
	Delivery                       []*Delivery         `xml:"cac:Delivery,omitempty"`
	DeliveryTerms                  *DeliveryTerms      `xml:"cac:DeliveryTerms,omitempty"`
	PaymentMeans                   []PaymentMeans      `xml:"cac:PaymentMeans,omitempty"`
	PaymentTerms                   *PaymentTerms       `xml:"cac:PaymentTerms,omitempty"`
	PrepaidPayment                 []PrepaidPayment    `xml:"cac:PrepaidPayment,omitempty"`
	AllowanceCharge                []AllowanceCharge   `xml:"cac:AllowanceCharge,omitempty"`
	TaxExchangeRate                *ExchangeRate       `xml:"cac:TaxExchangeRate,omitempty"`
	PricingExchangeRate            *ExchangeRate       `xml:"cac:PricingExchangeRate,omitempty"`
	PaymentExchangeRate            *ExchangeRate       `xml:"cac:PaymentExchangeRate,omitempty"`
	PaymentAlternativeExchangeRate *ExchangeRate       `xml:"cac:PaymentAlternativeExchangeRate,omitempty"`
	TaxTotal                       []TaxTotal          `xml:"cac:TaxTotal,omitempty"`
	WithholdingTaxTotal            []TaxTotal          `xml:"cac:WithholdingTaxTotal,omitempty"`
	LegalMonetaryTotal             MonetaryTotal       `xml:"cac:LegalMonetaryTotal"`
	InvoiceLines                   []InvoiceLine       `xml:"cac:InvoiceLine,omitempty"`
	CreditNoteLines                []InvoiceLine       `xml:"cac:CreditNoteLine,omitempty"`
}

Invoice represents the root element of a UBL Invoice **or** Credit Note; the structures between the two types are so similar, that it doesn't make much sense to separate.

func ConvertInvoice added in v0.5.0 

func ConvertInvoice(env *gobl.Envelope, opts ...Option) (*Invoice, error)

ConvertInvoice is a convenience function that converts a GOBL envelope containing an invoice into a UBL Invoice or CreditNote document.

func (*Invoice) AddAttachments added in v0.48.0 

func (ui *Invoice) AddAttachments(attachments []*org.Attachment)

AddAttachments adds an attachment to the UBL Invoice. This is useful for including documents like invoice counter values or URLs

func (*Invoice) AddBinaryAttachment added in v0.25.0 

func (ui *Invoice) AddBinaryAttachment(attachment BinaryAttachment)

AddBinaryAttachment adds an embedded binary attachment to the UBL Invoice. This is useful for including documents like PDFs directly within the UBL XML. The binary data will be automatically base64-encoded.

func (*Invoice) AddExtension added in v0.48.0 

func (ui *Invoice) AddExtension(extension *Extension)

AddExtension adds a new extension to the ubl invoice

func (*Invoice) AddSignatureReference added in v0.48.0 

func (ui *Invoice) AddSignatureReference(signatureMethod, referenceSignatureID string)

AddSignatureReference adds a reference to a signature

func (*Invoice) Convert added in v0.18.0 

func (ui *Invoice) Convert() (*gobl.Envelope, error)

Convert converts the UBL Invoice to a GOBL envelope. It automatically detects the context based on CustomizationID and ProfileID. Binary attachments are ignored during conversion - use ExtractBinaryAttachments to retrieve them separately.

func (*Invoice) ExtractBinaryAttachments added in v0.18.0 

func (ui *Invoice) ExtractBinaryAttachments() []BinaryAttachment

ExtractBinaryAttachments extracts all binary attachments from the UBL Invoice. It returns a slice of BinaryAttachment containing the ID, description, and decoded binary data. External reference attachments are not included in the result.

type InvoiceLine added in v0.5.0 

type InvoiceLine struct {
	ID                  string              `xml:"cbc:ID"`
	Note                []string            `xml:"cbc:Note"`
	InvoicedQuantity    *Quantity           `xml:"cbc:InvoicedQuantity,omitempty"` // or CreditNoteQuantity
	CreditedQuantity    *Quantity           `xml:"cbc:CreditedQuantity,omitempty"`
	LineExtensionAmount Amount              `xml:"cbc:LineExtensionAmount"`
	AccountingCost      *string             `xml:"cbc:AccountingCost"`
	InvoicePeriod       *Period             `xml:"cac:InvoicePeriod"`
	OrderLineReference  *OrderLineReference `xml:"cac:OrderLineReference"`
	DocumentReference   *LineDocReference   `xml:"cac:DocumentReference,omitempty"`
	AllowanceCharge     []*AllowanceCharge  `xml:"cac:AllowanceCharge"`
	TaxTotal            []TaxTotal          `xml:"cac:TaxTotal,omitempty"`
	Item                *Item               `xml:"cac:Item"`
	Price               *Price              `xml:"cac:Price"`
}

InvoiceLine represents a line item in an invoice and credit note

type Item added in v0.5.0 

type Item struct {
	Description                *string                    `xml:"cbc:Description"`
	Name                       string                     `xml:"cbc:Name"`
	BuyersItemIdentification   *ItemIdentification        `xml:"cac:BuyersItemIdentification"`
	SellersItemIdentification  *ItemIdentification        `xml:"cac:SellersItemIdentification"`
	StandardItemIdentification *ItemIdentification        `xml:"cac:StandardItemIdentification"`
	OriginCountry              *Country                   `xml:"cac:OriginCountry"`
	CommodityClassification    *[]CommodityClassification `xml:"cac:CommodityClassification"`
	ClassifiedTaxCategory      *ClassifiedTaxCategory     `xml:"cac:ClassifiedTaxCategory"`
	AdditionalItemProperty     *[]AdditionalItemProperty  `xml:"cac:AdditionalItemProperty"`
}

Item represents an item in an invoice line

type ItemIdentification added in v0.5.0 

type ItemIdentification struct {
	ID *IDType `xml:"cbc:ID"`
}

ItemIdentification represents an item identification

type LineDocReference added in v0.36.0 

type LineDocReference struct {
	ID               IDType  `xml:"cbc:ID"`
	DocumentTypeCode *string `xml:"cbc:DocumentTypeCode,omitempty"`
}

LineDocReference defines a document reference at line level (BT-128)

type Location added in v0.5.0 

type Location struct {
	ID      *IDType        `xml:"cbc:ID"`
	Address *PostalAddress `xml:"cac:Address"`
}

Location represents a location

type LocationCoordinate added in v0.5.0 

type LocationCoordinate struct {
	LatitudeDegreesMeasure  *string `xml:"cbc:LatitudeDegreesMeasure"`
	LatitudeMinutesMeasure  *string `xml:"cbc:LatitudeMinutesMeasure"`
	LongitudeDegreesMeasure *string `xml:"cbc:LongitudeDegreesMeasure"`
	LongitudeMinutesMeasure *string `xml:"cbc:LongitudeMinutesMeasure"`
}

LocationCoordinate represents a location coordinate

type MonetaryTotal added in v0.5.0 

type MonetaryTotal struct {
	LineExtensionAmount   Amount  `xml:"cbc:LineExtensionAmount"`
	TaxExclusiveAmount    Amount  `xml:"cbc:TaxExclusiveAmount"`
	TaxInclusiveAmount    Amount  `xml:"cbc:TaxInclusiveAmount"`
	AllowanceTotalAmount  *Amount `xml:"cbc:AllowanceTotalAmount,omitempty"`
	ChargeTotalAmount     *Amount `xml:"cbc:ChargeTotalAmount,omitempty"`
	PrepaidAmount         *Amount `xml:"cbc:PrepaidAmount,omitempty"`
	PayableRoundingAmount *Amount `xml:"cbc:PayableRoundingAmount,omitempty"`
	PayableAmount         *Amount `xml:"cbc:PayableAmount,omitempty"`
}

MonetaryTotal represents the monetary totals of the invoice

type Option added in v0.5.0 

type Option func(*options)

Option is used to define configuration options to use during conversion processes.

func WithContext added in v0.5.0 

func WithContext(c Context) Option

WithContext sets the context to use for the configuration and business profile.

type OrderLineReference added in v0.5.0 

type OrderLineReference struct {
	LineID string `xml:"cbc:LineID"`
}

OrderLineReference represents a reference to an order line

type OrderReference added in v0.5.0 

type OrderReference struct {
	ID                string `xml:"cbc:ID"`
	SalesOrderID      string `xml:"cbc:SalesOrderID,omitempty"`
	IssueDate         string `xml:"cbc:IssueDate,omitempty"`
	CustomerReference string `xml:"cbc:CustomerReference,omitempty"`
}

OrderReference represents a reference to an order

type Party added in v0.5.0 

type Party struct {
	EndpointID          *EndpointID       `xml:"cbc:EndpointID"`
	PartyIdentification []Identification  `xml:"cac:PartyIdentification"`
	PartyName           *PartyName        `xml:"cac:PartyName"`
	PostalAddress       *PostalAddress    `xml:"cac:PostalAddress"`
	PartyTaxScheme      []PartyTaxScheme  `xml:"cac:PartyTaxScheme"`
	PartyLegalEntity    *PartyLegalEntity `xml:"cac:PartyLegalEntity"`
	Contact             *Contact          `xml:"cac:Contact"`
}

Party represents a party involved in a transaction

func (*Party) CountryCode added in v0.5.0 

func (p *Party) CountryCode() string

CountryCode tries to determine the most appropriate tax country code for the party.

type PartyLegalEntity added in v0.5.0 

type PartyLegalEntity struct {
	RegistrationName *string `xml:"cbc:RegistrationName"`
	CompanyID        *IDType `xml:"cbc:CompanyID"`
	CompanyLegalForm *string `xml:"cbc:CompanyLegalForm"`
}

PartyLegalEntity represents the legal entity of a party

type PartyName added in v0.5.0 

type PartyName struct {
	Name string `xml:"cbc:Name"`
}

PartyName represents the name of a party

type PartyTaxScheme added in v0.5.0 

type PartyTaxScheme struct {
	CompanyID *string    `xml:"cbc:CompanyID"`
	TaxScheme *TaxScheme `xml:"cac:TaxScheme"`
}

PartyTaxScheme represents a party's tax scheme

type PaymentMandate added in v0.5.0 

type PaymentMandate struct {
	ID                    IDType            `xml:"cbc:ID"`
	PayerFinancialAccount *FinancialAccount `xml:"cac:PayerFinancialAccount"`
}

PaymentMandate represents a payment mandate

type PaymentMeans added in v0.5.0 

type PaymentMeans struct {
	PaymentMeansCode      IDType            `xml:"cbc:PaymentMeansCode"`
	PaymentDueDate        *string           `xml:"cbc:PaymentDueDate"`
	InstructionID         *string           `xml:"cbc:InstructionID"`
	InstructionNote       []string          `xml:"cbc:InstructionNote,omitempty"`
	PaymentID             *string           `xml:"cbc:PaymentID"`
	CardAccount           *CardAccount      `xml:"cac:CardAccount"`
	PayerFinancialAccount *FinancialAccount `xml:"cac:PayerFinancialAccount"`
	PayeeFinancialAccount *FinancialAccount `xml:"cac:PayeeFinancialAccount"`
	PaymentMandate        *PaymentMandate   `xml:"cac:PaymentMandate"`
}

PaymentMeans represents the means of payment

type PaymentTerms added in v0.5.0 

type PaymentTerms struct {
	Note string `xml:"cbc:Note"`
}

PaymentTerms represents the terms of payment

type Period added in v0.5.0 

type Period struct {
	StartDate       string `xml:"cbc:StartDate,omitempty"`
	EndDate         string `xml:"cbc:EndDate,omitempty"`
	DescriptionCode string `xml:"cbc:DescriptionCode,omitempty"`
}

Period represents a time period with start and end dates

type PostalAddress added in v0.5.0 

type PostalAddress struct {
	StreetName           *string             `xml:"cbc:StreetName"`
	AdditionalStreetName *string             `xml:"cbc:AdditionalStreetName"`
	BuildingNumber       *string             `xml:"cbc:BuildingNumber,omitempty"`
	PlotIdentification   *string             `xml:"cbc:PlotIdentification,omitempty"`
	CitySubdivisionName  *string             `xml:"cbc:CitySubdivisionName,omitempty"`
	CityName             *string             `xml:"cbc:CityName"`
	PostalZone           *string             `xml:"cbc:PostalZone"`
	CountrySubentity     *string             `xml:"cbc:CountrySubentity"`
	AddressLine          []AddressLine       `xml:"cac:AddressLine"`
	Country              *Country            `xml:"cac:Country"`
	LocationCoordinate   *LocationCoordinate `xml:"cac:LocationCoordinate"`
}

PostalAddress represents a postal address

type PrepaidPayment added in v0.5.0 

type PrepaidPayment struct {
	ID            string  `xml:"cbc:ID"`
	PaidAmount    *Amount `xml:"cbc:PaidAmount"`
	ReceivedDate  *string `xml:"cbc:ReceivedDate"`
	InstructionID *string `xml:"cbc:InstructionID"`
}

PrepaidPayment represents a prepaid payment

type Price added in v0.5.0 

type Price struct {
	PriceAmount     Amount           `xml:"cbc:PriceAmount"`
	BaseQuantity    *Quantity        `xml:"cbc:BaseQuantity,omitempty"`
	AllowanceCharge *AllowanceCharge `xml:"cac:AllowanceCharge,omitempty"`
}

Price represents the price of an item

type ProjectReference added in v0.5.0 

type ProjectReference struct {
	ID string `xml:"cbc:ID,omitempty"`
}

ProjectReference represents a reference to a project

type Quantity added in v0.5.0 

type Quantity struct {
	UnitCode string `xml:"unitCode,attr"`
	Value    string `xml:",chardata"`
}

Quantity represents a quantity with a unit code

type Reference added in v0.5.0 

type Reference struct {
	ID                  IDType      `xml:"cbc:ID"`
	UUID                string      `xml:"cbc:UUID,omitempty"`
	IssueDate           string      `xml:"cbc:IssueDate,omitempty"`
	DocumentTypeCode    string      `xml:"cbc:DocumentTypeCode,omitempty"`
	DocumentType        string      `xml:"cbc:DocumentType,omitempty"`
	DocumentDescription string      `xml:"cbc:DocumentDescription,omitempty"`
	Attachment          *Attachment `xml:"cac:Attachment,omitempty"`
	ValidityPeriod      *Period     `xml:"cac:ValidityPeriod,omitempty"`
}

Reference represents a reference to a document

type Signature added in v0.5.0 

type Signature struct {
	ID                         string      `xml:"cbc:ID"`
	Note                       []string    `xml:"cbc:Note,omitempty"`
	ValidationDate             *string     `xml:"cbc:ValidationDate,omitempty"`
	ValidationTime             *string     `xml:"cbc:ValidationTime,omitempty"`
	ValidatorID                *string     `xml:"cbc:ValidatorID,omitempty"`
	CanonicalizationMethod     *string     `xml:"cbc:CanonicalizationMethod,omitempty"`
	SignatureMethod            *string     `xml:"cbc:SignatureMethod,omitempty"`
	SignatoryParty             *Party      `xml:"cac:SignatoryParty,omitempty"`
	DigitalSignatureAttachment *Attachment `xml:"cac:DigitalSignatureAttachment,omitempty"`
	OriginalDocumentReference  *Reference  `xml:"cac:OriginalDocumentReference,omitempty"`
}

Signature represents a digital signature

type SignatureInformation added in v0.48.0 

type SignatureInformation struct {
	ID                    string             `xml:"cbc:ID"`
	ReferencedSignatureID string             `xml:"sbc:ReferencedSignatureID"`
	Signature             *xmldsig.Signature `xml:"ds:Signature"`
}

SignatureInformation holds the IDs and the ds:Signature.

type SupplierParty added in v0.5.0 

type SupplierParty struct {
	Party *Party `xml:"cac:Party"`
}

SupplierParty represents the supplier party in a transaction

type TaxCategory added in v0.5.0 

type TaxCategory struct {
	ID                     *string    `xml:"cbc:ID,omitempty"`
	Percent                *string    `xml:"cbc:Percent,omitempty"`
	TaxExemptionReasonCode *string    `xml:"cbc:TaxExemptionReasonCode,omitempty"`
	TaxExemptionReason     *string    `xml:"cbc:TaxExemptionReason,omitempty"`
	TaxScheme              *TaxScheme `xml:"cac:TaxScheme,omitempty"`
}

TaxCategory represents a tax category

type TaxScheme added in v0.5.0 

type TaxScheme struct {
	ID          string `xml:"cbc:ID"`
	TaxTypeCode string `xml:"cbc:TaxTypeCode,omitempty"`
}

TaxScheme represents a tax scheme

type TaxSubtotal added in v0.5.0 

type TaxSubtotal struct {
	TaxableAmount Amount      `xml:"cbc:TaxableAmount,omitempty"`
	TaxAmount     Amount      `xml:"cbc:TaxAmount"`
	TaxCategory   TaxCategory `xml:"cac:TaxCategory"`
}

TaxSubtotal represents a tax subtotal

type TaxTotal added in v0.5.0 

type TaxTotal struct {
	TaxAmount      Amount        `xml:"cbc:TaxAmount"`
	RoundingAmount *Amount       `xml:"cbc:RoundingAmount,omitempty"`
	TaxSubtotal    []TaxSubtotal `xml:"cac:TaxSubtotal"`
}

TaxTotal represents a tax total

type VESIDMapping added in v0.22.0 

type VESIDMapping struct {
	// Invoice is the VESID for invoices
	Invoice string
	// CreditNote is the VESID for credit notes
	CreditNote string
}

VESIDMapping maps document types to their corresponding VESID values.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gobl.ubl command
Package main provides a CLI interface for the library
 Package main provides a CLI interface for the library

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.