Skip to main content

​
What is UBL Builder?

UBL Builder is a TypeScript library that simplifies the creation of XML documents compliant with the UBL 2.1 (Universal Business Language) standard. It provides a fluent, type-safe API for constructing complex business documents like invoices, credit notes, and other commercial transactions.
UBL 2.1 is an OASIS standard for electronic business documents, widely adopted for e-invoicing systems worldwide, including DIAN (Colombia), ZATCA (Saudi Arabia), and many other tax authorities.

​
Why UBL Builder?

Building UBL-compliant XML documents manually is error-prone and time-consuming. UBL Builder addresses this by:

Type Safety

Full TypeScript support with intelligent autocomplete and compile-time validation

Fluent API

Chainable methods for intuitive document construction

UBL 2.1 Compliant

Generates XML that adheres to OASIS UBL 2.1 specifications

Tax Authority Support

Built-in support for DIAN extensions and electronic invoicing requirements

​
Key Features

​
Document Types

Currently supports:
  • Invoice - Full UBL 2.1 invoice documents with all standard components

​
Core Components

1

Common Aggregate Components

Pre-built components for parties, addresses, tax schemes, payment terms, and more
2

Unqualified Data Types

Properly typed UDT elements like UdtIdentifier, UdtAmount, UdtDate, UdtCode
3

Extension Support

DIAN-specific extensions for Colombian electronic invoicing (CUFE, QR codes)

​
Advanced Features

  • Automatic Calculations - CUFE (Unique Invoice Code) generation using SHA-384
  • QR Code Generation - For invoice verification
  • Validation - Constructor validation and type checking
  • Flexible Output - Pretty-printed or compact XML with configurable headers

​
Use Cases

E-Invoicing Systems

Build compliant electronic invoices for tax authority submission in Colombia, Saudi Arabia, and other jurisdictions

ERP Integrations

Generate UBL documents from your existing business systems

Billing Platforms

Create standardized invoices for B2B transactions

Accounting Software

Export financial data in UBL format for interoperability

​
Standards Compliance

UBL Builder implements:
  • UBL 2.1 - Full OASIS UBL 2.1 specification
  • DIAN 2.1 - Colombian tax authority requirements
  • XML Schema - Proper namespace declarations and schema validation
  • Digital Signatures - Extension points for XMLDSig signatures
For detailed UBL 2.1 documentation, visit the OASIS UBL 2.1 specification and schema documentation.

​
Example: Quick Preview

Here’s a taste of how simple invoice creation can be: 
import { Invoice } from 'ubl-builder';

const invoice = new Invoice('INV-001', {
  timestamp: Date.now(),
  enviroment: '2', // Testing environment
  issuer: { /* ... */ },
  software: { /* ... */ }
});

invoice
  .setUBLVersionID('UBL 2.1')
  .setIssueDate('2026-03-06')
  .setDocumentCurrencyCode('USD');

const xml = invoice.getXml(true);
Check out the Quickstart guide for a complete working example!

​
Next Steps

Installation

Get started by installing the package

Quickstart

Build your first invoice in 5 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us