E-Invoicing contributions

Current state in Lago

Lago currently supports two types of E-Invoicing formats: Cross Industry Invoices (CII) and Universal Business Language (UBL). Both implementations follow the French and German E-Invoicing structure. Some EU countries may use different naming conventions, but they generally rely on the same underlying CII or UBL data structures, with country specific additions or removals. This contribution guide is intended for developers who want to extend Lago’s E-Invoicing capabilities to support additional jurisdictions or customize existing formats, especially for Peppol network compliance.

CII - Cross Industry Invoices

Cross Industry Invoices represent the hybrid format combining a PDF/A-3 file with an embedded XML file. The XML structure follows the CII standard, which is widely used in Europe, including France’s Factur-X implementation. Lago supports e-invoicing for the following record types:

invoice
credit_note
payments

Each record type has a dedicated Builder class responsible for generating the XML document in the required format. Builder classes are located at:

app/serializers/e_invoices/<invoices|credit_notes|payments>/<cii|ubl>/builder.rb

CII implementation lives in the Lago API project under:

app/serializers/e_invoices/cii

Classes and XML Tags

Class	XML Tag	Description	Parameters / Notes
`Cii::CrossIndustryInvoice`	`rsm:CrossIndustryInvoice`	Root element for the invoice and its direct children	Requires a Ruby block
`Cii::Header`	`rsm:ExchangedDocument`	Header information for the document	`type_code`: document type `notes`: optional additional information
`Cii::LineItem`	`ram:IncludedSupplyChainTradeLineItem`	Represents a single invoice line item	`data`: `Cii::LineItem::Data` containing item details
`Cii::TradeAgreement`	`ram:ApplicableHeaderTradeAgreement`	Commercial agreement details	`options`: optional `Cii::TradeAgreement::Options` `tax_registration`: controls tax registration rendering, default `true`
`Cii::TradeDelivery`	`ram:ApplicableHeaderTradeDelivery`	Delivery information for goods or services	`delivery_date`: date goods or services were delivered
`Cii::TradeSettlement`	`ram:ApplicableHeaderTradeSettlement`	Settlement and payment context	Requires a Ruby block
`Cii::TradeSettlementPayment`	`ram:SpecifiedTradeSettlementPaymentMeans`	Payment means used for settlement	No specific parameters
`Cii::ApplicableTradeTax`	`ram:ApplicableTradeTax`	Tax information applied to the invoice	Multiple tax related parameters
`Cii::TradeAllowanceCharge`	`ram:SpecifiedTradeAllowanceCharge`	Allowances or charges applied to the invoice	Multiple allowance and charge parameters
`Cii::PaymentTerms`	`ram:SpecifiedTradePaymentTerms`	Defines payment terms	No specific parameters
`Cii::MonetarySummation`	`ram:SpecifiedTradeSettlementHeaderMonetarySummation`	Monetary totals and summaries	`amounts`: `Cii::MonetarySummation::Amounts` with rendered values

UBL - Universal Business Language

Universal Business Language (UBL) is another widely adopted E-Invoicing standard, particularly in the Peppol network. UBL invoices are XML-only documents that follow a specific schema defined by OASIS. The UBL implementation is located in the Lago API project under:

app/serializers/e_invoices/ubl

Contributing new jurisdictions - The example of Germany

Overview

This guide outlines the steps to contribute a new E-Invoicing format for Germany, specifically the XRechnung and ZUGFeRD formats based on UBL and CII standards. Germany supports two e-invoicing formats:

ZUGFeRD 2.3.3 (EN 16931) CII

This format combines a human readable PDF with embedded XML data. It is the most commonly used option due to lower implementation and operational costs compared to fiscal EDI based processes.

XRechnung UBL Invoice

This is a pure XML electronic invoice based on UBL 2.1. It follows German XRechnung semantic requirements and is typically transmitted via the PEPPOL network using the PEPPOL BIS Billing 3.0 specification. It is used for German B2G compliance and EU wide interoperability.

Implementation notes

ZUGFeRD 2.3.3 has no differences compared to the French Factur-X implementation. Existing CII code can be fully reused. XRechnung may require additional tags that are not present in the French UBL implementation. These tags should be added under the UBL folder. Example:

The InvoicePeriod tag is optional in standard UBL but required in XRechnung. It is currently not implemented in the French version.
Some tags present in the French implementation may not be valid for XRechnung. Rendering of such tags should be controlled via conditional logic based on billing_entity.country.

def serialize
  # other mandatory tags

  render_specific_tag if conditions_met?

  # other tags
end

private

def conditions_met?
  ["DE"].include?(billing_entity.country)
end

def render_specific_tag
  xml["cac"].GermanySpecificTag(value)
end

If a completely new and independent tag is required, create a dedicated class to render it. The corresponding Builder class should invoke it only when the conditions for the specific country or implementation are met.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Invoicing

Payments & Cash Collection

Data & Analytics

Resources

E-Invoicing contributions

Current state in Lago

CII - Cross Industry Invoices

Classes and XML Tags

UBL - Universal Business Language

Contributing new jurisdictions - The example of Germany

Overview

ZUGFeRD 2.3.3 (EN 16931) CII

XRechnung UBL Invoice

Implementation notes

​Current state in Lago

​CII - Cross Industry Invoices

​Classes and XML Tags

​UBL - Universal Business Language

​Contributing new jurisdictions - The example of Germany

​Overview

ZUGFeRD 2.3.3 (EN 16931) CII

XRechnung UBL Invoice

​Implementation notes

Current state in Lago

CII - Cross Industry Invoices

Classes and XML Tags

UBL - Universal Business Language

Contributing new jurisdictions - The example of Germany

Overview

Implementation notes