This profile includes BASIC, with all the additional data required by the European Semantics Standard, whether optional or conditional. It is fully compliant to EN 16931, focussing on the core elements of an electronic invoice.
import { EN16931, type ProfileEN16931 } from "node-zugferd/profile/en16931";
import { COMFORT, type ProfileComfort } from "node-zugferd/profile/comfort";Basic Usage
Setup the Profile
First configure the zugferd instance (invoicer) to use the EN16931 profile.
This defines the standard and complexity level of the invoice.
import { EN16931 } from "node-zugferd/profile/en16931";
export const invoicer = zugferd({
profile: EN16931,
});Define Invoice Data
Now define the actual invoice content, including all required fields of the
profile, using the ProfileEN16931 type for type safety.
import { ProfileEN16931 } from "node-zugferd/profile/en16931";
const data: ProfileEN16931 = {
number: "INV-001",
// ...
};Create Invoice
Use the previously created instance (invoicer) to generate the invoice from your data. You can either:
- Generate standalone XML
- Embed the XML inside a PDF/A-3b compliant file.
import fs from "fs";
import { invoicer } from "./invoicer";
const invoice = invoicer.create(data);
// Only generate xml
const xml = await invoice.toXML();
// Or embed xml in a PDF-A/3b
const pdf = fs.readFileSync("./your/invoice.pdf");
const pdfA = await invoicer.embedInPdf(pdf); 🎉 That's it
Your invoice is now ready! You've successfully created a ZUGFeRD invoice using the EN16931 profile.
Schema
Extends BASIC
stringobjectobjectobjectstringSeller additional legal information
Additional legal information relevant for the Seller.
Such as share capital.
objectSeller Contact
A group of business terms providing contact information about the Seller.
stringSeller contact point
A contact point for a legal entity or person.
Such as person name, contact identification, department or office identification.
stringDepartment name
stringSeller contact telephone number
A phone number for the contact point.
stringSeller contact email address
An e-mail address for the contact point.
objectobjectstringBuyer trading name
A name by which the Buyer is known, other than Buyer name (also known as Business name).
This may be used if different from the Buyer name.
objectBuyer Contact
A group of business terms providing contact information relevant for the Buyer.
Contacting details can be given by the Buyer at the time of the ordering or as master data exchanged prior to ordering. It is recommended not to use contacting details for the purpose of routing the received Invoice internally by the recipient; the Buyer reference identifier should be used for this purpose.
stringBuyer contact point
A contact point for a legal entity or person.
Such as person name, contact identification, department or office identification.
stringDepartment name
stringBuyer contact telephone number
A phone number for the contact point.
stringBuyer contact email address
An e-mail address for the contact point.
objectDetails about the associated order confirmation
stringSales order reference
An identifier of a referenced sales order, issued by the Seller.
object[]Additional Supporting Documents
A group of business terms providing information about additional supporting documents substantiating the claims made in the Invoice.
The additional supporting documents can be used for both referencing a document number which is expected to be known by the receiver, an external document (referenced by a URL) or as an embedded document (such as a time report in pdf). The option to link to an external document will be needed, for example in the case of large attachments and/or when sensitive information, e.g. person-related services, has to be separated from the Invoice itself.
CHORUS PRO: If the group "ADDITIONAL SUPPORTING DOCUMENTS" is filled in, one of the following two business terms must be present: Attached Document (BT-125) or External document location (URI) (BT-124)
stringSupporting document reference
An identifier of the supporting document.
stringExternal document location
The URL (Uniform Resource Locator) that identifies where the external document is located.
A means of locating the resource including its primary access mechanism, e.g. http:// or ftp://. External document location shall be used if the Buyer requires additional information to support the Invoice. External documents do not form part of the invoice. Risks can be involved when accessing external documents.
stringSupporting document description
A description of the supporting document.
Such as: timesheet, usage report etc.
CHORUS PRO: Chorus Pro allows only two types of attachements: main attachment and additional attachment. In the case of a PDF / A-3 (Factur-X), only the type of complementary attachment is allowed.
stringAttached document
An attached document embedded as binary object or sent together with the invoice.
Attached document is used when documentation shall be stored with the Invoice for future reference or audit purposes.
CHORUS PRO : The attachment must be contained in a ZIP file. The maximum size of the attachment is 100 MB.
stringAttached document Mime code
The mime code of the attached document.
Allowed mime codes:
- application/pdf
- image/png
- image/jpeg
- text/csv
- application/vnd.openxmlformatsofficedocument.spreadsheetml.sheet
- application/vnd.oasis.opendocument.spreadsheet
stringAttached document Filename
The file name of the attached document
object[]Details on tender or lot reference
stringTender or lot reference
The identification of the call for tender or lot the invoice relates to.
In some countries a reference to the call for tender that has led to the contract shall be provided.
object[]stringInvoiced object identifier
An identifier for an object on which the invoice is based, given by the Seller.
It may be a subscription number, telephone number, meter point, vehicle, person etc., as applicable.
stringScheme identifier
The identification scheme identifier of the Invoiced object identifier.
If it may be not clear for the receiver what scheme is used for the identifier, a onditional scheme identifier should be used that shall be chosen from the UNTDID 1153 code list [6] entries.
objectobjectDetailed information about the associated goods receipt
stringReceiving advice reference
An identifier of a referenced receiving advice.
objectobjectstringPayment means text
The means, expressed as text, for how a payment is expected to be or has been settled.
Such as cash, credit transfer, direct debit, credit card, etc.
objectPayment Card Information
A group of business terms providing information about card used for payment contemporaneous with invoice issuance.
Only used if the Buyer has opted to pay by using a payment card such as a credit or debit card.
stringPayment card primary account number
The Primary Account Number (PAN) of the card used for payment.
In accordance with card payments security standards an invoice should never include a full card primary account number. At the moment PCI Security Standards Council has defined following: The first 6 digits and last 4 digits are the maximum number of digits to be shown.
stringPayment card holder name
The name of the payment card holder.
object[]stringPayment account name
The name of the payment account, at a payment service provider, to which payment should be made.
objectSeller bank information
stringPayment service provider identifier
An identifier for the payment service provider where a payment account is located.
Such as a BIC or a national clearing code where required. No identification scheme to be used.
To be used for Credit Transfer only CHORUS PRO: Only BIC format is allowed
Use for credit transfer
object[]dateValue added tax point date
This does not apply in Germany. Use date of delivery instead.
The date when the VAT becomes accountable for the Seller and for the Buyer in so far as that date can be determined and differs from the date of issue of the invoice, according to the VAT directive.
The tax point is usually the date goods were supplied or services completed (the 'basic tax point'). There are some variations. Please refer to Article 226 (7) of the Council Directive 2006/112/EC [2] for more information. This element is required if the Value added tax point date is different from the Invoice issue date. Both Buyer and Seller should use the Tax Point Date when provided by the Seller. The use of BT-7 and BT-8 is mutually exclusive.
This date shall not be present if the Value added tax point date is expressed in code in the "Value added tax point date code" (BT-8)
BR-CO-3: Value added tax point date (BT-7) and Value added tax point date code (BT-8) are mutually exclusive.
objectstring | numberRounding amount
The amount to be added to the invoice total to round the amount to be paid.
This case is not applied in France.
object[]objectstringItem Seller's identifier
An identifier, assigned by the Seller, for the item.
stringItem Buyer's identifier
An identifier, assigned by the Buyer, for the item.
stringItem description
A description for an item.
The Item description allows for describing the item and its features in more detail than the Item name.
object[]Item attributes
A group of business terms providing information about properties of the goods and services invoiced.
stringItem attribute name
The name of the attribute or property of the item.
Such as "Colour".
stringItem attribute value
The value of the attribute or property of the item.
Such as "Red".
objectDetailed information on the item classification
object[]Item classification identifier
A code for classifying the item by its type or nature.
Classification codes are used to allow grouping of similar items for a various purposes e.g. public procurement (CPV), e-Commerce (UNSPSC) etc.
stringItem classification identifier
A code for classifying the item by its type or nature.
Classification codes are used to allow grouping of similar items for a various purposes e.g. public procurement (CPV), e-Commerce (UNSPSC) etc.
stringScheme identifier
The identification scheme identifier of the Item classification identifier
The identification scheme shall be chosen from the entries in UNTDID 7143 [6].
stringScheme version identifer
The version of the identification scheme.
objectDetailed information on the item origin
stringItem country of origin
The code identifying the country from which the item originates.
The lists of valid countries are registered with the ISO 3166-1 Maintenance agency, "Codes for the representation of names of countries and their subdivisions".
objectobjectDetails of the associated order
string | numberReferenced purchase order line reference
An identifier for a referenced line within a purchase order, issued by the Buyer.
The purchase order identifier is referenced on document level.
objectobject[]string | numberInvoice line allowance base amount
The base amount that may be used, in conjunction with the Invoice line allowance percentage, to calculate the Invoice line allowance amount.
object[]string | numberInvoice line charge base amount
The base amount that may be used, in conjunction with the Invoice line charge percentage, to calculate the Invoice line charge amount.
objectObject identifier at the invoice item level
stringInvoice line object identifier
An identifier for an object on which the invoice line is based, given by the Seller.
It may be a subscription number, telephone number, meter point etc., as applicable.
stringScheme identifier Invocice line object identifier
The identification scheme identifier of the Invoice line object identifier.
If it may be not clear for the receiver what scheme is used for the identifier, a conditional scheme identifier should be used that shall be chosen from the UNTDID 1153 code list [6] entries.
objectDetailed information on the accounting reference
stringInvoice line Buyer accounting reference
A textual value that specifies where to book the relevant data into the Buyer's financial accounts.
If required, this reference shall be provided by the Buyer to the Seller prior to the issuing of the Invoice.