A TypeScript toolkit for preparing and reading documents for e-invoicing and PEPPOL integration. This library helps you generate PEPPOL-compliant UBL XML invoices from structured data.
PEPPOL (Pan-European Public Procurement On-Line) is a set of specifications that enables cross-border e-procurement in Europe and beyond. This toolkit simplifies the process of creating compliant electronic invoices.
- 🚀 Generate PEPPOL-compliant UBL XML invoices
- 📦 ESM and CommonJS builds for broad compatibility
- 🔷 Written in TypeScript with bundled type definitions
- 🧪 Built with fast-xml-parser for reliable XML generation
- ⚡ Simple API for quick integration
npm install @pixeldrive/peppol-toolkitimport { PeppolToolkit, createToolkit } from '@pixeldrive/peppol-toolkit';
// Using the class directly
const toolkit = new PeppolToolkit();
// Or using the factory function
// const toolkit = createToolkit();
// Generate PEPPOL UBL XML from invoice data
const invoiceData = {};
const peppolXML = toolkit.invoiceToPeppolUBL(invoiceData);
console.log(peppolXML);const { PeppolToolkit, createToolkit } = require('@pixeldrive/peppol-toolkit');
const toolkit = new PeppolToolkit();
const peppolXML = toolkit.invoiceToPeppolUBL({});The main class that provides invoice conversion functionality.
invoiceToPeppolUBL(invoice: Invoice): string- Converts an invoice object to PEPPOL-compliant UBL XML
- Returns: XML string formatted for PEPPOL compliance
Factory function that creates a new instance of PeppolToolkit.
This toolkit supports the following PEPPOL BIS UBL invoice elements based on the current implementation:
- CustomizationID - PEPPOL compliance identifier
- ProfileID - PEPPOL business process identifier
- ID - Invoice number/identifier
- IssueDate - Invoice issue date
- DueDate - Payment due date (optional)
- InvoiceTypeCode - Type of invoice (e.g., 380, 383)
- DocumentCurrencyCode - Currency for the invoice
- BuyerReference - Buyer's reference identifier
- EndpointID - Electronic address with scheme
- PartyIdentification - Party identifiers with schemes
- PartyName - Party name (optional)
- PostalAddress - Complete address information
- StreetName
- AdditionalStreetName (optional)
- CityName
- PostalZone
- Country identification code
- PartyTaxScheme - VAT information
- CompanyID (VAT number)
- TaxScheme ID (VAT)
- PartyLegalEntity - Legal entity details
- RegistrationName
- CompanyID (optional)
- CompanyLegalForm (optional)
- Contact - Contact information (optional)
- Name
- Telephone
- ElectronicMail
- PaymentMeans - Payment method details
- PaymentMeansCode
- PaymentID
- PayeeFinancialAccount (optional)
- Account ID
- Account Name
- FinancialInstitutionBranch
- PaymentTerms - Payment terms note (optional)
- TaxTotal - Complete tax breakdown
- TaxAmount with currency
- TaxSubtotal details
- TaxableAmount with currency
- TaxAmount with currency
- TaxCategory information
- Category ID/Code
- Percent rate
- TaxExemptionReason (optional)
- TaxExemptionReasonCode (optional)
- TaxScheme (VAT)
- LegalMonetaryTotal - Invoice totals
- LineExtensionAmount - Sum of line amounts
- TaxExclusiveAmount - Amount excluding tax
- TaxInclusiveAmount - Amount including tax
- PayableAmount - Final payable amount
- AllowanceTotalAmount (optional)
- ChargeTotalAmount (optional)
- PrepaidAmount (optional)
- PayableRoundingAmount (optional)
- InvoiceLine - Individual line items
- ID - Line identifier
- Note (optional)
- InvoicedQuantity with unit code
- LineExtensionAmount with currency
- Item information
- Name
- Description (optional)
- ClassifiedTaxCategory
- Category ID
- Percent rate
- TaxScheme (VAT)
- Price information
- PriceAmount with currency
- XML Namespaces - Proper UBL 2.1 namespaces
- Currency Support - Multi-currency handling
- Unit Codes - UN/ECE Recommendation No. 20 unit codes
- Country Codes - ISO 3166-1 alpha-2 country codes
- Schema Validation - Zod-based type validation
- XML Formatting - Properly formatted XML output
Starting from version 1.0.0, this library will follow Semantic Versioning (SemVer). Until then, breaking changes may occur in minor and patch releases as the API is still being stabilized.
- Initial invoice-to-UBL XML generation API
- Define and export robust Invoice TypeScript types
- Add input validation helpers
- Support CreditNote documents
- Implement UBL 2.1 schema validation (offline)
- Implement PEPPOL BIS profile validation (offline)
- Enable online validation against remote services
- Support attachments/binary objects embedding (e.g., PDF)
- CLI: Convert JSON invoices to UBL XML
- Documentation: Examples and recipe-style guides
- QA: Expand unit tests
Last updated: 2025-09-29
npm run build- Build the librarynpm run dev- Build in watch mode for developmentnpm run test- Run testsnpm run lint- Lint the codebasenpm run format- Format code with Prettier
- Node.js 18+ recommended
- Works in TypeScript and JavaScript projects
PEPPOL is an international standard for electronic document exchange, particularly for invoicing and procurement. It ensures that electronic documents can be exchanged seamlessly between different systems across borders.
This toolkit helps you:
- Generate UBL (Universal Business Language) XML invoices
- Ensure PEPPOL compliance for cross-border transactions
- Integrate e-invoicing capabilities into your applications
Contributions are welcome! This project is in active development and we're looking for contributors to help build out the full feature set.
Please feel free to:
- Open issues for bugs or feature requests
- Submit pull requests with improvements
- Help with documentation and examples
MIT
This software is provided "as is" without warranty of any kind. Please ensure compliance with your local regulations and PEPPOL requirements when using this toolkit in production.