@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.

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 input, CII XSD, and EN 16931 profile field checks in the gateway and returns { valid, errors, warnings, format, profile }.

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.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.

License

MIT