# UblEx
Parse and generate UBL (Universal Business Language) documents in Elixir with full round-trip support.
**Peppol BIS Billing 3.0 compliant** • **UBL 2.1** • **EN16931**
## Features
- **Parse** UBL Invoice, CreditNote, and ApplicationResponse XML documents
- **Generate** Peppol-compliant UBL XML
- **Validate** against official Peppol BIS Billing 3.0 rules (optional)
- **Round-trip support** - parse → generate → parse without data loss
- **Type-safe** - proper Elixir types (Date, Decimal, atoms)
- **Attachment support** - embed PDF files and other documents
- **Auto-detection** - automatically identify document types
- **Simple API** - no complex behaviours or callbacks
## Installation
Add `ubl_ex` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:ubl_ex, "~> 0.7.0"}
]
end
```
## Quick Start
### Parsing a UBL Document
```elixir
# Simple parse with automatic schema detection
{:ok, parsed} = UblEx.parse(xml_content)
# Or be explicit about the schema
{:ok, parsed} = UblEx.parse_xml(xml_content, :ubl_peppol)
# Access the data
IO.puts("Document type: #{parsed.type}") # :invoice, :credit, or :application_response
IO.puts("Invoice number: #{parsed.number}")
IO.puts("Supplier: #{parsed.supplier.name}")
IO.puts("Customer: #{parsed.customer.name}")
IO.puts("Total: #{length(parsed.details)} line items")
```
### Generating a UBL Invoice
```elixir
document_data = %{
type: :invoice,
number: "F2024001",
date: ~D[2024-01-15],
expires: ~D[2024-02-14],
supplier: %{
endpoint_id: "0797948229",
scheme: "0208",
name: "My Company",
street: "Main Street 123",
city: "Brussels",
zipcode: "1000",
country: "BE",
vat: "BE0797948229",
email: "invoice@mycompany.com"
},
customer: %{
endpoint_id: "0012345625",
scheme: "0208",
name: "Customer Corp",
vat: "BE0012345625",
street: "Customer Street",
housenumber: "45",
city: "Antwerp",
zipcode: "2000",
country: "BE"
},
details: [
%{
name: "Consulting Services - January 2024",
quantity: Decimal.new("40.0"),
price: Decimal.new("75.00"),
vat: Decimal.new("21.00"),
discount: Decimal.new("0.00")
}
]
}
# Generate the XML
xml = UblEx.generate(document_data)
```
### Generating a Credit Note
```elixir
credit_note_data = %{
type: :credit,
number: "C2024001",
date: ~D[2024-01-20],
# Reference original invoices
billing_references: ["F2024001", "F2024002"],
supplier: %{...},
customer: %{...},
details: [...]
}
xml = UblEx.generate(credit_note_data)
```
### Generating an Application Response
Application responses are used to acknowledge receipt and processing status of invoices:
```elixir
response_data = %{
type: :application_response,
id: "RESPONSE-001",
date: ~D[2025-06-02],
response_code: "AB", # AB = Acknowledged, RE = Rejected
document_reference: "INV-123",
sender: %{
endpoint_id: "0797948229",
scheme: "0208",
name: "My Company"
},
receiver: %{
endpoint_id: "0844125969",
scheme: "0208",
name: "Supplier Inc"
},
status_reason: "Invoice approved", # Optional
note: "Payment scheduled" # Optional
}
xml = UblEx.generate(response_data)
```
### Working with Attachments
```elixir
# Include PDF attachments (e.g., signed invoice)
document_data = %{
type: :invoice,
number: "F2024001",
# ... other fields ...
attachments: [
%{
filename: "F2024001.pdf",
mime_type: "application/pdf",
data: Base.encode64(pdf_binary)
},
%{
filename: "terms.pdf",
mime_type: "application/pdf",
data: Base.encode64(terms_pdf)
}
]
}
xml = UblEx.generate(document_data)
# Parse documents with attachments
{:ok, parsed} = UblEx.parse(xml)
parsed.attachments
# => [%{filename: "F2024001.pdf", mime_type: "application/pdf", data: "base64..."}]
```
### Generating SBDH-Wrapped Documents
For Peppol network transmission, wrap documents in a Standard Business Document Header (SBDH):
```elixir
# Same document data as before
document_data = %{
type: :invoice,
number: "F2024001",
date: ~D[2024-01-15],
# ... all other fields ...
}
# Generate with SBDH wrapper for Peppol network
sbdh_xml = UblEx.generate_with_sbdh(document_data)
# The SBDH includes routing information automatically derived from:
# - Supplier endpoint_id and scheme -> SBDH Sender
# - Customer VAT (if no endpoint_id) -> SBDH Receiver
# - Document type and customization -> SBDH Business Scope
# Parse SBDH-wrapped documents (automatically unwraps)
{:ok, parsed} = UblEx.parse(sbdh_xml)
# Returns the same data structure as parsing unwrapped UBL
```
### Validating UBL Documents
UblEx includes an optional validator that validates your generated UBL documents against official Peppol BIS Billing 3.0 rules using the free peppol.helger.com validation service.
**Note:** This feature requires the optional `req` dependency. Add it to your `mix.exs`:
```elixir
def deps do
[
{:ubl_ex, "~> 0.6.0"},
{:req, "~> 0.5.0"} # Required for validation
]
end
```
#### Validating an Invoice
```elixir
# Generate an invoice
document_data = %{type: :invoice, number: "F2024001", ...}
xml = UblEx.generate(document_data)
# Validate against Peppol BIS Billing 3.0
case UblEx.Validator.validate(xml, :invoice) do
{:ok, result} ->
IO.puts("✓ Valid Peppol invoice!")
if result.warnings != [] do
IO.puts("Warnings: #{inspect(result.warnings)}")
end
{:error, %{success: false, errors: errors}} ->
IO.puts("✗ Invalid invoice:")
Enum.each(errors, fn error -> IO.puts(" - #{error}") end)
end
```
#### Validating a Credit Note
```elixir
xml = UblEx.generate(%{type: :credit, ...})
UblEx.Validator.validate(xml, :credit)
```
#### Validation Options
```elixir
# Custom timeout (default: 30 seconds)
UblEx.Validator.validate(xml, :invoice, timeout: 60_000)
# Override VESID (validation executor set ID)
UblEx.Validator.validate(xml, :invoice, vesid: "eu.peppol.bis3:invoice:3.13.0")
```
#### Understanding Validation Results
The validator returns:
- **Errors** - Must be fixed for Peppol compliance
- **Warnings** - Should be fixed for best practices (e.g., country-specific requirements)
```elixir
{:ok, result} = UblEx.Validator.validate(xml, :invoice)
result.success # true/false
result.errors # List of error messages
result.warnings # List of warning messages
```
**Important Notes:**
- Validation requires an internet connection (calls external service)
- The service is provided free of charge without SLA
- For production use, consider caching validation results
- SBDH-wrapped documents cannot be validated directly (unwrap first)
## Document Structure
### Invoice and Credit Note Structure
```elixir
%{
# Document metadata
type: :invoice | :credit,
number: "F2024001",
date: ~D[2024-01-15],
expires: ~D[2024-02-14], # Invoices only
order_reference: "PO-12345",
billing_references: ["F001"], # Credit notes only
payment_id: "+++000/2024/00186+++", # Optional: Belgian structured payment reference
# Supplier information
supplier: %{
endpoint_id: "0797948229",
scheme: "0208", # Optional: inferred from country if not set
name: "Company Name",
street: "Street 123",
city: "City",
zipcode: "1000",
country: "BE",
vat: "BE0797948229",
email: "invoice@company.com",
iban: "BE68539007547034" # Required for payment means
},
# Customer information
customer: %{
endpoint_id: "0012345625",
# scheme: "0208", # Optional: inferred from country if not set
name: "Customer Name",
vat: "BE0012345625",
street: "Customer Street",
housenumber: "45",
city: "City",
zipcode: "2000",
country: "BE"
},
# Line items
details: [
%{
name: "Service or product description",
quantity: Decimal.new("1.00"),
price: Decimal.new("100.00"),
vat: Decimal.new("21.00"), # VAT percentage
discount: Decimal.new("0.00"), # Discount percentage
tax_category: :standard, # Optional: defaults to :standard for non-zero VAT, :zero_rated for 0%
tax_exemption_reason_code: "vatex-eu-ic", # Required for E, G, K, AE tax categories
tax_exemption_reason: "Exemption reason" # Required for E, G, K, AE tax categories
}
],
# Optional attachments
attachments: [
%{
filename: "invoice.pdf",
mime_type: "application/pdf",
data: "base64encoded..."
}
]
}
```
### Application Response Structure
```elixir
%{
# Document metadata
type: :application_response,
id: "RESPONSE-001",
date: ~D[2025-06-02],
response_code: "AB", # AB = Acknowledged, RE = Rejected, AP = Accepted with errors, CA = Conditionally accepted
document_reference: "INV-123", # The invoice/credit note being acknowledged
status_reason: "Optional reason",
note: "Optional note",
# Sender (the party sending the response)
sender: %{
endpoint_id: "0797948229",
scheme: "0208",
name: "Company Name"
},
# Receiver (the party receiving the response)
receiver: %{
endpoint_id: "0844125969",
scheme: "0208",
name: "Supplier Name"
}
}
```
## API Reference
### Parsing
#### `UblEx.parse(xml_content)`
Parse UBL XML with automatic schema detection. This is the recommended way to parse documents.
Returns `{:ok, parsed_data}` or `{:error, reason}`.
#### `UblEx.parse_xml(xml_content, schema_id)`
Parse XML with a specific schema (`:ubl_peppol`). Use this when you know the schema in advance.
Returns `{:ok, parsed_data}` or `{:error, reason}`.
### Generation
#### `UblEx.generate(document_data)`
Generate XML based on the `:type` field in the data (`:invoice`, `:credit`, or `:application_response`).
#### `UblEx.generate_with_sbdh(document_data)`
Generate XML wrapped in SBDH (Standard Business Document Header) for Peppol network transmission.
## Tax Categories
UblEx supports all Peppol BIS 3.0 tax categories via the `tax_category` field on line items:
| Atom | Peppol Code | Use Case |
|------|-------------|----------|
| `:standard` | S | Standard rated VAT (default for 6/12/21%) |
| `:zero_rated` | Z | Zero rated goods (default for 0% VAT) |
| `:exempt` | E | Exempt from tax |
| `:reverse_charge` | AE | Domestic reverse charge |
| `:intra_community` | K | EU cross-border B2B (intra-community supply) |
| `:export` | G | Export outside EU |
| `:outside_scope` | O | Services outside scope of tax |
### EU Intra-Community Transactions
For B2B transactions between EU countries where the customer is liable for VAT:
```elixir
document_data = %{
type: :invoice,
number: "F2024001",
# ...
details: [
%{
name: "Consulting Services",
quantity: Decimal.new("1.00"),
price: Decimal.new("1000.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :intra_community, # Generates tax category "K" in UBL
tax_exemption_reason_code: "vatex-eu-ic",
tax_exemption_reason: "Intra-community supply - Article 138 Directive 2006/112/EC"
}
]
}
```
### Mixed Tax Categories
You can mix different tax categories in the same invoice:
```elixir
details: [
%{
name: "Standard Service",
quantity: Decimal.new("1.00"),
price: Decimal.new("500.00"),
vat: Decimal.new("21.00"),
discount: Decimal.new("0.00")
# tax_category defaults to :standard, no exemption fields needed
},
%{
name: "EU Cross-Border Service",
quantity: Decimal.new("1.00"),
price: Decimal.new("1000.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :intra_community,
tax_exemption_reason_code: "vatex-eu-ic",
tax_exemption_reason: "Intra-community supply"
},
%{
name: "Export Service",
quantity: Decimal.new("1.00"),
price: Decimal.new("750.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :export,
tax_exemption_reason_code: "vatex-eu-g",
tax_exemption_reason: "Export outside EU"
}
]
```
### Tax Exemption Fields
According to Peppol BIS 3.0 validation rules (BR-O-11 through BR-O-14), when using tax categories `:exempt` (E), `:export` (G), `:intra_community` (K), or `:reverse_charge` (AE), you **must** provide tax exemption information:
- `tax_exemption_reason_code` - A VATEX code identifying the exemption reason
- `tax_exemption_reason` - A human-readable explanation
The VATEX code list follows the format `vatex-{country}-{code}`. Common codes include:
- `vatex-eu-ic` - Intra-community supply (Art. 138 EU VAT Directive)
- `vatex-eu-ae` - Reverse charge / Autoliquidation
- `vatex-eu-g` - Export outside EU
- `vatex-eu-132` - Exemptions for certain activities (medical, education, etc.)
For the complete list of VATEX codes, see the [official Peppol VATEX code list](https://docs.peppol.eu/poacc/billing/3.0/codelist/vatex/).
#### Example: Intra-Community Supply
```elixir
details: [
%{
name: "EU Cross-Border Service",
quantity: Decimal.new("1.00"),
price: Decimal.new("1000.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :intra_community,
tax_exemption_reason_code: "vatex-eu-ic",
tax_exemption_reason: "Intra-community supply - Article 138 Directive 2006/112/EC"
}
]
```
#### Example: Domestic Reverse Charge
```elixir
details: [
%{
name: "Construction Services",
quantity: Decimal.new("1.00"),
price: Decimal.new("5000.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :reverse_charge,
tax_exemption_reason_code: "vatex-eu-ae",
tax_exemption_reason: "Reverse charge - VAT to be paid by the customer"
}
]
```
#### Example: Export Outside EU
```elixir
details: [
%{
name: "Exported Goods",
quantity: Decimal.new("1.00"),
price: Decimal.new("2000.00"),
vat: Decimal.new("0.00"),
discount: Decimal.new("0.00"),
tax_category: :export,
tax_exemption_reason_code: "vatex-eu-g",
tax_exemption_reason: "Export outside EU - Article 146 Directive 2006/112/EC"
}
]
```
## Peppol Scheme IDs
The `scheme` field on supplier and customer is optional. If not provided, it is automatically inferred from the `country` field using the following mappings:
| Country | Scheme | Description |
|---------|--------|-------------|
| AT | 9915 | Austria - VAT |
| BE | 0208 | Belgium - KBO/BCE |
| BG | 9926 | Bulgaria - VAT |
| CY | 9928 | Cyprus - VAT |
| CZ | 9929 | Czech Republic - VAT |
| DE | 0204 | Germany - Leitweg-ID |
| DK | 0096 | Denmark - CVR |
| EE | 9931 | Estonia - VAT |
| ES | 9920 | Spain - VAT |
| FI | 0037 | Finland - LY-tunnus |
| FR | 0009 | France - SIRET |
| GR | 9933 | Greece - VAT |
| HR | 9934 | Croatia - VAT |
| HU | 9910 | Hungary - VAT |
| IE | 9935 | Ireland - VAT |
| IT | 0201 | Italy - Codice Fiscale |
| LT | 9937 | Lithuania - VAT |
| LU | 9938 | Luxembourg - VAT |
| LV | 9939 | Latvia - VAT |
| MT | 9943 | Malta - VAT |
| NL | 0106 | Netherlands - KvK |
| PL | 9945 | Poland - VAT |
| PT | 9946 | Portugal - VAT |
| RO | 9947 | Romania - VAT |
| SE | 0007 | Sweden - Organisationsnummer |
| SI | 9949 | Slovenia - VAT |
| SK | 9950 | Slovakia - VAT |
For countries not in this list, the fallback is `0088` (EAN/GLN - international).
You can always override the inferred scheme by explicitly setting the `scheme` field on the party.
## Real-World Usage
### Basic Invoice Processing
```elixir
defmodule MyApp.Invoices do
def import_ubl_invoice(xml_file_path) do
with {:ok, xml} <- File.read(xml_file_path),
{:ok, parsed} <- UblEx.parse(xml) do
# Save to your database
%Invoice{}
|> Invoice.changeset(%{
number: parsed.number,
date: parsed.date,
supplier_name: parsed.supplier.name,
customer_name: parsed.customer.name,
total: calculate_total(parsed.details)
})
|> Repo.insert()
end
end
defp calculate_total(details) do
Enum.reduce(details, Decimal.new(0), fn item, acc ->
line_total = Decimal.mult(item.quantity, item.price)
Decimal.add(acc, line_total)
end)
end
end
```
### Generate Invoice from Database
```elixir
defmodule MyApp.Invoices do
def generate_ubl_xml(invoice_id) do
invoice = Repo.get!(Invoice, invoice_id) |> Repo.preload([:customer, :supplier, :line_items])
document_data = %{
type: :invoice,
number: invoice.number,
date: invoice.date,
expires: invoice.due_date,
supplier: %{
endpoint_id: invoice.supplier.endpoint_id,
scheme: invoice.supplier.scheme,
name: invoice.supplier.name,
street: invoice.supplier.street,
city: invoice.supplier.city,
zipcode: invoice.supplier.zipcode,
country: invoice.supplier.country,
vat: invoice.supplier.vat,
email: invoice.supplier.email
},
customer: %{
endpoint_id: invoice.customer.endpoint_id,
scheme: invoice.customer.scheme,
name: invoice.customer.name,
vat: invoice.customer.vat,
street: invoice.customer.street,
housenumber: invoice.customer.housenumber,
city: invoice.customer.city,
zipcode: invoice.customer.zipcode,
country: invoice.customer.country
},
details: Enum.map(invoice.line_items, fn item ->
base = %{
name: item.description,
quantity: item.quantity,
price: item.unit_price,
vat: item.vat_rate,
discount: item.discount_percentage
}
if item.tax_category, do: Map.put(base, :tax_category, item.tax_category), else: base
end)
}
UblEx.generate(document_data)
end
end
```
## Compliance
This library generates UBL documents compliant with:
- **UBL 2.1** - Universal Business Language version 2.1
- **Peppol BIS Billing 3.0** - Pan-European Public Procurement Online
- **EN16931** - European standard for electronic invoicing
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
