This example demonstrates the simplest possible invoice you can create with the UBL Builder library. It includes only the essential fields required for a valid UBL 2.1 invoice.
Installation
First, install the library:
Basic Invoice Code
import { Invoice } from 'ubl-builder';
const invoice = new Invoice('123456789', {});
invoice.addProperty('xmlns', 'urn:oasis:names:specification:ubl:schema:xsd:Invoice-2');
const xml = invoice.getXml();
console.log(xml);
Generated XML Output
The code above generates the following UBL 2.1 XML:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Invoice
xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">
<cbc:UBLVersionID>UBL 2.1</cbc:UBLVersionID>
<cbc:ID>123456789</cbc:ID>
<cbc:IssueDate>2020-09-13</cbc:IssueDate>
<cbc:IssueTime>02:10:44-05:00</cbc:IssueTime>
</Invoice>
Adding Basic Fields
Let’s enhance the invoice with additional required fields:
import { Invoice } from 'ubl-builder';
const invoiceOptions = {
enviroment: '2', // '1' for production, '2' for testing
issuer: {
prefix: 'INV',
resolutionNumber: '321654987',
startDate: '2024-01-01',
endDate: '2025-12-31',
startRange: '1000',
endRange: '5000',
technicalKey: 'tech-key-123',
},
software: {
id: 'soft-123',
pin: '123456789',
providerNit: '900123456-1',
},
};
const invoice = new Invoice('INV-001', invoiceOptions);
// Set default UBL namespaces
invoice.setDefaultProperties();
// Set basic invoice fields
invoice.setID('INV-001');
invoice.setUBLVersionID('UBL 2.1');
invoice.setIssueDate('2026-03-06');
invoice.setIssueTime('10:30:00-05:00');
invoice.setInvoiceTypeCode('01'); // Standard invoice
invoice.setDocumentCurrencyCode('USD');
invoice.addNote('Payment due within 30 days');
const xml = invoice.getXml(true); // true for pretty formatting
console.log(xml);
Key Fields Explained
| Field | Description |
|---|
ID | Unique invoice number |
UBLVersionID | UBL standard version (typically “UBL 2.1”) |
IssueDate | Date the invoice was issued (YYYY-MM-DD format) |
IssueTime | Time the invoice was issued (HH:MM:SS±HH:MM format) |
InvoiceTypeCode | Type of invoice (01 = standard, 02 = credit note, etc.) |
DocumentCurrencyCode | Currency code (USD, EUR, COP, etc.) |
Note | Additional notes or payment terms |
The invoice constructor requires two parameters:
- Invoice ID (string): The unique invoice identifier
- Options (object): Configuration object with issuer, software, and environment details
For a minimal test invoice, you can pass an empty object {} as the options parameter. However, for production use, always include complete issuer and software configuration.
Next Steps
