Introduction
einvoice-ts reads, builds, validates and writes electronic invoices and credit notes in the UBL syntax of Peppol BIS Billing 3.0, the Peppol profile of the European standard EN 16931. It is written in TypeScript, ships as ES modules and uses no Node.js APIs, so the same code runs on a server and in a browser.
What it does
- Build an invoice from the facts you know.
createInvoice()fills in the identifiers the syntax requires and computes the line amounts, the VAT breakdown and the totals. - Serialize a document to UBL 2.1 XML with
serialize(). Equal documents give identical XML. - Parse UBL XML into a typed model with
parse(). Structural problems are reported, not thrown. - Validate a document against the EN 16931, Peppol and Danish rules with
validate(), without a Schematron or XSLT engine. Each issue carries the official rule id, its message, the XPath of the element and a link to the rule's page on docs.peppol.eu. - Extend the rules: compose rulesets, add your own rules, disable or soften existing ones.
It does not send invoices over the Peppol network (that is the job of an access point) and it does not render PDFs.
Only the validator validates
createInvoice(), parse() and serialize() never check a document against the rules, so what they return can be invalid. Call validate() or validateXml() before you send a document or accept one.
The packages
| Package | What it holds | Depends on |
|---|---|---|
@facturometro/einvoice | Everything below, re-exported, plus validateXml() | the four packages below |
@facturometro/core | Model types, createInvoice(), Decimal, code lists, runtime schema, errors | nothing |
@facturometro/parser | parse(), parseInvoice(), parseCreditNote() and the structural diagnostics | core, @rgrove/parse-xml |
@facturometro/serializer | serialize() | core |
@facturometro/validator | validate(), assertValid(), the built-in rulesets and the extension API | core |
All five are versioned and released together, so any set of them with the same version works together.
Which one to install
Install @facturometro/einvoice unless you have a reason not to: one import gives you the whole pipeline. The packages are side-effect free ES modules, so a bundler drops what you do not use.
Install single packages when you need only part of the pipeline and want the dependency to say so: @facturometro/core and @facturometro/serializer to emit invoices, or @facturometro/validator to check documents you build. The validator never loads the XML parser. See Installation.
Status
Version 0.1.0 implements Peppol BIS Billing 3.0.21 with its EN 16931 rules, its Peppol rules and the Danish national rules. The other national rule packs of the Peppol release are not implemented yet; see Specification versions and the FAQ.