This page documents the conversion of ordering-related information between UBL XML and GOBL JSON formats. Ordering references include buyer references, purchase order numbers, contract references, billing periods, despatch/receipt document references, tender identifiers, and object identifiers.
For information about delivery logistics, see page 4.6. For payment term references, see page 4.5. For party identification, see page 4.1. For attachment handling, see page 4.8.
Ordering conversion is bidirectional, supporting both GOBL → UBL generation and UBL → GOBL parsing. The addOrdering function ordering.go68-147 generates UBL elements from GOBL, while goblAddOrdering ordering_parse.go23-112 performs the reverse conversion.
Sources: ordering.go:1-148, ordering_parse.go:1-155
In GOBL, the ordering field within bill.Invoice consolidates all order-related references:
The structure groups related procurement documents into arrays, allowing multiple references of each type. The hasOrderingData function ordering_parse.go12-21 determines whether any field contains data before adding the ordering block during parsing.
Sources: ordering_parse.go:12-21, ordering.go:68-147
Sources: ordering_parse.go:23-112
The addOrdering function ordering.go68-147 generates UBL elements from GOBL ordering data. This process includes special handling for tax representatives and supports multiple reference types:
Sources: ordering.go:68-147
The following table describes bidirectional field mapping between UBL and GOBL:
| UBL Element | GOBL Field | UBL → GOBL | GOBL → UBL | Notes |
|---|---|---|---|---|
BuyerReference | ordering.Code | ordering_parse.go26-28 | ordering.go73-75 | Direct string conversion |
InvoicePeriod[0] | ordering.Period | ordering_parse.go31-33 | ordering.go87-94 | Only first period parsed; both dates formatted |
TaxRepresentativeParty | ordering.Seller | invoice_parse.go137-145 | ordering.go79-85 | Original supplier moved to ordering.Seller when tax rep present |
OrderReference.ID | ordering.Purchases[0] | ordering_parse.go57-63 | ordering.go96-101 | Single purchase order |
DespatchDocumentReference[] | ordering.Despatch[] | ordering_parse.go35-44 | ordering.go103-107 | Multiple despatch documents |
ReceiptDocumentReference[] | ordering.Receiving[] | ordering_parse.go46-55 | ordering.go109-113 | Multiple receipt documents |
ContractDocumentReference[] | ordering.Contracts[] | ordering_parse.go65-74 | ordering.go115-119 | Multiple contracts |
OriginatorDocumentReference[] | ordering.Tender[] | ordering_parse.go76-85 | ordering.go121-125 | Multiple tender/RFP references |
AdditionalDocumentReference[] (type "130") | ordering.Identities[] | ordering_parse.go87-105 | ordering.go127-146 | Object identifiers with optional scheme ID |
Sources: ordering_parse.go:23-112, ordering.go:68-147, invoice_parse.go:137-145
The goblReference function ordering_parse.go114-135 converts UBL Reference structures to GOBL org.DocumentRef objects. This function is reused for despatch, receipt, contract, and tender references during UBL → GOBL parsing.
The function extracts:
ID.Valuecbc.KeyparseDate() functiongoblPeriodDates()Sources: ordering_parse.go:114-135
The goblPeriodDates function ordering_parse.go137-154 converts UBL Period structures containing start and end dates to GOBL cal.Period objects:
Both start and end dates are optional. The function returns nil if date parsing fails ordering_parse.go142-149 This conversion is used for both InvoicePeriod ordering_parse.go32 and ValidityPeriod within document references ordering_parse.go132
Sources: ordering_parse.go:137-154
When both ordering.Seller and supplier are present in GOBL, the conversion treats the supplier as a tax representative ordering.go79-85:
AccountingSupplierParty.Party is moved to TaxRepresentativePartyordering.Seller party becomes the new AccountingSupplierPartyDuring parsing, the reverse operation occurs invoice_parse.go137-145: when TaxRepresentativeParty is present, it becomes the ordering.Seller and the tax representative replaces the main supplier.
Sources: ordering.go:79-85, invoice_parse.go:137-145
The AdditionalDocumentReference array in UBL serves multiple purposes. The conversion logic filters by DocumentTypeCode to extract specific reference types.
When DocumentTypeCode="130", the reference represents an object identifier used for tracking physical assets or shipments:
UBL → GOBL:
GOBL → UBL:
During parsing ordering_parse.go87-105 the code comes from ID.Value and the scheme from ID.SchemeID is stored in extensions. During generation ordering.go127-146 the system searches for an identity with the untdid-document-reference extension key to populate the schemeID attribute.
Sources: ordering_parse.go:87-105, ordering.go:127-146
The following example demonstrates a comprehensive ordering block with multiple reference types:
This structure is generated from UBL elements including BuyerReference, InvoicePeriod, ContractDocumentReference, OrderReference, ReceiptDocumentReference, and DespatchDocumentReference.
Sources: ordering.go:68-147, ordering_parse.go:23-112
The hasOrderingData function ordering_parse.go12-21 checks whether any ordering field contains data before adding the ordering block to the invoice:
| Field | Check Condition |
|---|---|
Code | Non-empty string |
Period | Non-nil pointer |
Despatch | Array length > 0 |
Receiving | Array length > 0 |
Purchases | Array length > 0 |
Contracts | Array length > 0 |
Tender | Array length > 0 |
Identities | Array length > 0 |
If all fields are empty, the entire ordering block is omitted from the GOBL invoice ordering_parse.go104-106 This ensures that invoices without ordering references remain clean without empty data structures.
Sources: ordering_parse.go:10-19, ordering_parse.go:104-109
GOBL does not currently support multiple billing periods per invoice ordering_parse.go28 so only the first InvoicePeriod element is converted. Additional periods in the UBL source are ignored.
The OrderReference field in UBL represents a single purchase order ordering_parse.go55-61 which is converted to a single-element array in GOBL. If multiple purchase orders need to be referenced, they would need to be provided through other UBL elements or extensions.
The conversion logic for ordering data is currently only implemented in the UBL → GOBL direction. Converting GOBL ordering data back to UBL elements would require a separate implementation in the generation pipeline.
Sources: ordering_parse.go:28, ordering_parse.go:55-61
Refresh this wiki