@nuclicore/e-invoice

JavaScript SDK for Nuclicore's e-invoice API — generate and validate EN 16931 / ZUGFeRD (Factur-X) electronic invoices: a PDF/A-3 with the invoice CII XML embedded.

It is a thin client over the Nuclicore integration gateway and builds on @nuclicore/documents, reusing its transport (auth, gateway URL, environment resolution). All heavy lifting — layout rendering, XML generation, PDF/A-3 embedding, and conformity validation — happens server-side.

Installation

npm install @nuclicore/e-invoice

Configuration

Option 1: Environment variables

NUCLICORE_APP_ID=your-app-id
NUCLICORE_INTEGRATION_KEY=your-api-key
# Optional — defaults to https://integrations.build.nuclicore.com
NUCLICORE_GATEWAY_URL=https://integrations.build.nuclicore.com

import { NuclicoreEInvoice } from '@nuclicore/e-invoice';

const einvoice = new NuclicoreEInvoice();

Option 2: Constructor config

import { NuclicoreEInvoice } from '@nuclicore/e-invoice';

const einvoice = new NuclicoreEInvoice({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  gatewayUrl: 'https://integrations.build.nuclicore.com', // optional
  environment: 'production', // 'preview' | 'production' — defaults based on NODE_ENV
});

Constructor values take precedence over environment variables.

Usage

Generate an e-invoice

Provide the invoice data in the standardized JSON format and receive a PDF/A-3 Buffer with the EN 16931 CII XML embedded (Factur-X / ZUGFeRD).

import { writeFileSync } from 'fs';
import { NuclicoreEInvoice } from '@nuclicore/e-invoice';

const einvoice = new NuclicoreEInvoice();

const pdf = await einvoice.generate({
  invoice: {
    invoiceNumber: 'R-2026-000123',
    issueDate: '2026-07-06',
    documentType: 'receipt',
    currency: 'EUR',
    seller: {
      name: 'Muster GmbH',
      vatId: 'DE123456789',
      address: { line1: 'Hauptstr. 1', city: 'Berlin', postCode: '10115', countryCode: 'DE' },
      contact: { email: '[email protected]' },
    },
    buyer: {
      name: 'Kunde AG',
      address: { line1: 'Marktplatz 5', city: 'Munich', postCode: '80331', countryCode: 'DE' },
    },
    lines: [
      { name: 'Consulting', quantity: 10, unit: 'HUR', unitPrice: 100, vatRate: 19 },
      { name: 'License',    quantity: 1,  unitPrice: 250, vatRate: 19 },
    ],
    payment: { means: '30', iban: 'DE02120300000000202051', reference: 'R-2026-000123' },
    // vatBreakdown and totals are optional — computed and cross-checked server-side.
  },
});

writeFileSync('./receipt.pdf', pdf);

The invoice fields mirror the EN 16931 semantic model (BT/BG terms are noted in the TypeScript field docs). vatBreakdown and totals may be omitted — the gateway computes them from the line items, and validates them when provided. When you provide them, the gateway writes vatBreakdown, taxBasisTotal, vatTotal, grandTotal, paidAmount, roundingAmount and duePayable as given (two decimals) and does not recompute them. The sum of line net amounts (BT-106) is always written as the sum of the lines' lineNetAmount values, as EN 16931 rule BR-CO-10 requires.

Add Factur-X to your own PDF

Keep your own layout: pass your PDF and the invoice data, and get the hybrid PDF/A-3 back with the CII XML embedded as factur-x.xml.

const hybrid = await einvoice.attach({ invoice, pdf: readFileSync('./my-invoice.pdf') });

The XML is built from invoice only, so make sure your PDF shows the same data.

Contract, period, SEPA and item attributes (1.1.0)

All fields below are optional. Payloads that don't use them produce exactly the same XML as 1.0.1.

| Field | Type | EN 16931 | Written as (CII) | | ----- | ---- | -------- | ---------------- | | seller.id | string | BT-29 | ram:SellerTradeParty/ram:ID (first child) | | buyer.id | string | BT-46 | ram:BuyerTradeParty/ram:ID (first child) | | contractReference | string | BT-12 | ram:ApplicableHeaderTradeAgreement/ram:ContractReferencedDocument/ram:IssuerAssignedID | | deliveryDate | string (yyyy-MM-dd) | BT-72 | ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime (issue date when omitted) | | billingPeriod.start | string (yyyy-MM-dd) | BG-14 / BT-73 | ram:ApplicableHeaderTradeSettlement/ram:BillingSpecifiedPeriod/ram:StartDateTime | | billingPeriod.end | string (yyyy-MM-dd) | BG-14 / BT-74 | ram:ApplicableHeaderTradeSettlement/ram:BillingSpecifiedPeriod/ram:EndDateTime | | lines[].attributes[].name | string | BG-32 / BT-160 | ram:SpecifiedTradeProduct/ram:ApplicableProductCharacteristic/ram:Description | | lines[].attributes[].value | string | BG-32 / BT-161 | ram:SpecifiedTradeProduct/ram:ApplicableProductCharacteristic/ram:Value | | payment.creditorId | string | BT-90 | ram:ApplicableHeaderTradeSettlement/ram:CreditorReferenceID | | payment.mandateReference | string | BT-89 | ram:SpecifiedTradePaymentTerms/ram:DirectDebitMandateID | | payment.debtorIban | string | BT-91 | ram:SpecifiedTradeSettlementPaymentMeans/ram:PayerPartyDebtorFinancialAccount/ram:IBANID | | payment.additionalAccounts[] | EInvoiceAccount[] | BG-17 (repeated) | one more ram:SpecifiedTradeSettlementPaymentMeans per account, same ram:TypeCode |

All dates are written as udt:DateTimeString format="102" (yyyyMMdd).

SEPA direct debit (means 59)

payment: {
  means: '59',
  dueDate: '2026-10-30',
  reference: '2610-00017-071',
  // Shown to humans: mask the IBAN here (BT-20). Written unchanged.
  terms: 'Der Rechnungsbetrag wird am oder nach dem 30.10.2026 von Ihrem Konto IBAN DE** **** **** **** **30 00 eingezogen.',
  creditorId: 'DE98ZZZ09999999999',          // BT-90
  mandateReference: 'WENA-1001-01',          // BT-89
  debtorIban: 'DE89370400440532013000',      // BT-91, unmasked
},

SEPA credit transfer to two accounts (means 58)

payment: {
  means: '58',
  iban: 'DE28870520003330004940', bic: 'WELADED1FGX', accountName: 'WENA-CAR Produkt GmbH',
  additionalAccounts: [
    { iban: 'DE20870961240120307924', bic: 'GENODEF1MIW', accountName: 'WENA-CAR Produkt GmbH' },
  ],
},

Contract, customer number, service period and item attributes

invoice: {
  // ...
  contractReference: 'G-2610-00016-476',            // BT-12
  deliveryDate: '2026-10-16',                       // BT-72
  billingPeriod: { start: '2026-10-16', end: '2028-10-15' }, // BG-14
  buyer: { id: '1001', name: 'Autohaus Testmann GmbH', address: { countryCode: 'DE' } }, // BT-46
  lines: [{
    name: 'Händlergarantie PREMIUM ELEKTRO/HYBRID XL',
    quantity: 1, unitPrice: 605.04, vatRate: 19,
    attributes: [                                   // BG-32, kept in this order
      { name: 'FIN', value: 'WVWZZZ1KZAW000001' },
      { name: 'Fahrzeugtyp', value: 'Audi A4' },
    ],
  }],
}

Checks on the new fields

validate(), generate() and attach() run the same checks. Each problem is returned as a ValidationIssue whose field is the JSON path inside invoice. Empty strings count as "not given".

| Field | Rule | code | | ----- | ---- | ------ | | payment.debtorIban, payment.additionalAccounts[i].iban | ISO 13616 format (uppercase, no spaces, country length) | IBAN-FORMAT | | same | mod-97 check digits | IBAN-CHECKSUM | | payment.creditorId | country, 2 check digits, 3-character business code, national identifier | CREDITOR-ID-FORMAT | | payment.creditorId | mod-97 check digits (business code excluded) | CREDITOR-ID-CHECKSUM | | payment.creditorId, payment.mandateReference, payment.debtorIban | only with means 59 | DIRECT-DEBIT-MEANS | | payment.additionalAccounts | only with means 30 or 58 (no means = 30) | CREDIT-TRANSFER-MEANS | | deliveryDate, billingPeriod.start, billingPeriod.end | valid ISO date yyyy-MM-dd | ISO-DATE | | billingPeriod | start not after end | BR-29 | | lines[i].attributes[j].name / .value | not empty | BR-54 |

The gateway does not require creditorId, mandateReference or debtorIban for means 59. If your process needs them, check that in your app.

Validate before (or without) generating

Check conformity and get structured feedback without producing a PDF:

const result = await einvoice.validate({ invoice });

if (!result.valid) {
  for (const issue of result.errors) {
    console.error(`[${issue.code ?? 'ERR'}] ${issue.field ?? ''} ${issue.message}`);
  }
}

validate() runs the input checks and the EN 16931 Schematron business rules in the gateway and returns { valid, errors, warnings, format, profile }. generate() and attach() run the same validation first and fail with HTTP 422 (listing the errors) instead of producing a non-conformant invoice.

Formats & profile

| Field | v1 value | Meaning | | ----- | -------- | ------- | | format | factur-x | ZUGFeRD-compatible hybrid PDF/A-3 with embedded CII XML | | profile | en16931 | EN 16931 (COMFORT) profile |

Switching environments

The SDK defaults to preview in development and production when NODE_ENV=production. Switch at runtime:

einvoice.setEnvironment('production');
console.log(einvoice.getEnvironment()); // 'production'

Error handling

generate() throws a standard Error when generation fails (message from the API). For structured, field-level feedback, call validate() first.

try {
  const pdf = await einvoice.generate({ invoice });
} catch (err) {
  console.error(err.message);
}

Common errors:

| Error | Cause | | ----- | ----- | | appId is required | Missing NUCLICORE_APP_ID env var or appId config | | invoice is required | No invoice object provided | | invoice.invoiceNumber is required | Missing invoice number | | invoice.lines must contain at least one line | Empty line items | | Insufficient credits | Account needs more credits |

API reference

new NuclicoreEInvoice(config?)

| Parameter | Type | Default | Description | | --------- | ---- | ------- | ----------- | | config.appId | string | NUCLICORE_APP_ID env | Application ID | | config.apiKey | string | NUCLICORE_INTEGRATION_KEY env | API key | | config.gatewayUrl | string | NUCLICORE_GATEWAY_URL env or https://integrations.build.nuclicore.com | Gateway URL | | config.environment | 'preview' \| 'production' | Based on NODE_ENV | Target environment |

einvoice.generate(params): Promise<Buffer>

| Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | params.invoice | EInvoiceInput | Yes | Standardized invoice data | | params.format | 'factur-x' | No | Output format (default factur-x) | | params.profile | 'en16931' | No | EN 16931 profile (default en16931) | | params.fileName | string | No | Filename hint for the returned PDF |

Returns the generated PDF/A-3 as a Buffer.

einvoice.attach(params): Promise<Buffer>

| Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | params.invoice | EInvoiceInput | Yes | Standardized invoice data (produces the embedded XML) | | params.pdf | Buffer | Yes | Your PDF to embed factur-x.xml into | | params.format | 'factur-x' | No | Output format (default factur-x) | | params.profile | 'en16931' | No | EN 16931 profile (default en16931) | | params.fileName | string | No | Filename hint for the returned PDF |

Returns the hybrid PDF/A-3 as a Buffer. PDF/A-3 conformance depends on your PDF (fonts must be embedded).

einvoice.validate(params): Promise<ValidationResult>

| Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | params.invoice | EInvoiceInput | Yes | Invoice data to validate | | params.format | 'factur-x' | No | Format to validate against | | params.profile | 'en16931' | No | EN 16931 profile |

Returns { valid, errors, warnings, format, profile }.

einvoice.getAppId(): string

Returns the configured application ID.

einvoice.getEnvironment(): string

Returns the current environment ('preview' or 'production').

einvoice.setEnvironment(env: 'preview' | 'production'): void

Switches the target environment at runtime.

Changelog

1.1.0

• New optional fields: seller.id / buyer.id (BT-29 / BT-46), contractReference (BT-12), deliveryDate (BT-72), billingPeriod (BG-14), lines[].attributes (BG-32), payment.creditorId (BT-90), payment.mandateReference (BT-89), payment.debtorIban (BT-91), payment.additionalAccounts (BG-17 repeated).
• New types: EInvoiceLineAttribute, EInvoiceAccount, EInvoiceBillingPeriod.
• Needs the integration gateway release that understands these fields. An older gateway ignores them without an error.
• No breaking changes: payloads without the new fields produce the same XML as 1.0.1.

License

MIT