node-zugferd
IntroductionInstallation

General

ParserTemplates

Exchange Networks

TRAFFIQX®

Validators

MustangXSD

Utilities

Magic BytesInstrumentation

TRAFFIQX®

Send and receive electronic invoices through the TRAFFIQX® Invoice API (TIA).

The TRAFFIQX® Invoice API connects your application to the TRAFFIQX® network. It supports sending and receiving invoices through the customer’s chosen TRAFFIQX® provider. This plugin wraps the TIA endpoints for ZUGFeRD and structured data uploads, and for inbox and outbox operations.

Before using the API, your organization needs access to TIA and credentials for a supported provider. The provider supplies the client ID and OAuth setup; sandbox availability and configuration depend on that provider. See TRAFFIQX® Invoice API and DATEV’s first steps.

For endpoint details, see the DATEV TIA API reference.

Installation

Install the plugin

npm install @node-zugferd/traffiqx@beta

Add the plugin to your instance

invoicer.ts
import { zugferd } from "node-zugferd";
import { en16931 } from "@node-zugferd/en-16931";
import { traffiqx } from "@node-zugferd/traffiqx";
import {
    b4value,
    bundesdruckerei,
} from "@node-zugferd/traffiqx/provider";

export const invoicer = zugferd({
    profiles: [en16931],
    plugins: [
        traffiqx({ 
            provider: [ 
                b4value({ 
                    clientId: process.env.B4VALUE_CLIENT_ID!, 
                    sandbox: process.env.NODE_ENV !== "production", 
                }), 
                bundesdruckerei({ 
                    clientId: process.env.BUNDESDRUCKEREI_CLIENT_ID!, 
                }), 
            ], 
        }), 
    ],
    // ...
});

Provider

The plugin accepts one provider or an array of providers. With an array, pass providerId to every operation so the plugin can route the request to the matching base URL and provider-specific headers. The value must match the selected factory's providerId exactly (for example, b4value.net GmbH). With one configured provider, providerId is optional. Use the client ID and sandbox setting issued for each provider.

import { b4value } from "@node-zugferd/traffiqx/provider/b4value";

b4value({
    clientId: process.env.B4VALUE_CLIENT_ID,
    sandbox: process.env.NODE_ENV !== "production",
});

Options

Prop

Type

import { bundesdruckerei } from "@node-zugferd/traffiqx/provider/bundesdruckerei";

bundesdruckerei({
    clientId: process.env.BUNDESDRUCKEREI_CLIENT_ID,
});

Options

Prop

Type

import { datevERechnungsplattform } from "@node-zugferd/traffiqx/provider/datev-e-rechnungsplattform";

datevERechnungsplattform({
    appName: "My App",
    clientId: process.env.DATEV_CLIENT_ID,
    sandbox: process.env.NODE_ENV !== "production",
});

Options

Prop

Type

import { datevSmartTransfer } from "@node-zugferd/traffiqx/provider/datev-smarttransfer";

datevSmartTransfer({
    appName: "My App",
    clientId: process.env.DATEV_CLIENT_ID,
});

Options

Prop

Type

import { quadient } from "@node-zugferd/traffiqx/provider/quadient";

quadient({
    clientId: process.env.QUADIENT_CLIENT_ID,
});

Options

Prop

Type

import { sgh } from "@node-zugferd/traffiqx/provider/sgh";

sgh({
    clientId: process.env.SGH_CLIENT_ID,
});

Options

Prop

Type

import { ricoh } from "@node-zugferd/traffiqx/provider/ricoh";

ricoh({
    clientId: process.env.RICOH_CLIENT_ID,
});

Options

Prop

Type

Usage

Every operation accepts providerId. It is required when provider is configured as an array and optional when a single provider is configured. Use the exact provider ID shown by the selected provider factory.

Upload ZUGFeRD Invoices

Customers can upload a document data in the ZUGFeRD format to the outbox workspace so that an invoice can be created from them.

const pdf = await invoicer.toPDF(await readFile("./invoice.pdf"));

const { data, error } = await invoicer.traffiqx.upload({
    data: await pdf.save(),
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

Upload Structured Data (XRechnung)

Customers can upload document data in UBL or CII format with a corresponding PDF view to the outbox workspace so that an invoice can be created from them.

const { data, error } = await invoicer.traffiqx.uploadStructuredData({
    data: await readFile("./invoice.xml"),
    view_component: await readFile("./invoice.pdf"),
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

Query Document Status

Query the status of an uploaded document using the unique document ID.

const { data, error } = await invoicer.traffiqx.outbox.status({
    documentId: "ea096fd8-6f98-4e19-b600-b75b7068f961",
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

List Outbox Documents

Retrieve the document IDs of all uploaded invoice data, depending on the set filter.

const { data, error } = await invoicer.traffiqx.outbox.list({
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    // query filter
    downloaded: false,
    status: "inProcess",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

Download Outbox Document

Downloading a sent original document from the outbox workspace.

const { data, error } = await invoicer.traffiqx.outbox.download({
    documentId: "ea096fd8-6f98-4e19-b600-b75b7068f961",
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

if (error) throw new Error(error.title);
const zip = await data.arrayBuffer();

Options

Prop

Type

Outbox Document Metadata

Retrieve the metadata of a document using the unique document ID.

const { data, error } = await invoicer.traffiqx.outbox.metadata({
    documentId: "ea096fd8-6f98-4e19-b600-b75b7068f961",
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

List Inbox Documents

Retrieve the InboxDocumentId of all received documents by downloaded status

const { data, error } = await invoicer.traffiqx.inbox.list({
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    // query filter
    downloaded: false,
    from_date: "2026-08-10",
    to_date: new Date(),
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

Download Inbox Document

Downloading the data of a received document from the inbox workspace

const { data, error } = await invoicer.traffiqx.inbox.download({
    documentId: "ea096fd8-6f98-4e19-b600-b75b7068f961",
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

if (error) throw new Error(error.title);
const zip = await data.arrayBuffer();

Options

Prop

Type

Inbox Document Metadata

Retrieve the metadata of a received document using the unique document ID.

const { data, error } = await invoicer.traffiqx.inbox.metadata({
    documentId: "ea096fd8-6f98-4e19-b600-b75b7068f961",
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: async (ctx) => {
        // Return provider access token
        return await getAccessToken(ctx.meta.userId);
    },
    // Additional metadata accessible in context
    meta: {
        userId: "12345",
    },
});

Options

Prop

Type

Usage with Better Auth

Register the OAuth Provider

node-zugferd bundles better-auth presets for each provider's IdP:

Provider IDDiscovery Endpoint
b4valuehttps://login.b4value.net/realms/prod/.well-known/openid-configuration
https://login.qs.b4value.net/realms/qs/.well-known/openid-configuration (Sandbox)
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { b4value } from "@node-zugferd/traffiqx/better-auth/b4value";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                b4value({ 
                    clientId: process.env.B4VALUE_CLIENT_ID!, 
                    clientSecret: process.env.B4VALUE_CLIENT_SECRET!, 
                    sandbox: process.env.NODE_ENV !== "production", 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
bundesdruckereihttps://login.bdr-businessportal.de/realms/prod/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { bundesdruckerei } from "@node-zugferd/traffiqx/better-auth/bundesdruckerei";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                bundesdruckerei({ 
                    clientId: process.env.BUNDESDRUCKEREI_CLIENT_ID!, 
                    clientSecret: process.env.BUNDESDRUCKEREI_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
datev-e-rechnungsplattformhttps://signin.datev.de/datevam/oauth2/realms/root/realms/user/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { datevERechnungsplattform } from "@node-zugferd/traffiqx/better-auth/datev-e-rechnungsplattform";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                datevERechnungsplattform({ 
                    clientId: process.env.DATEV_CLIENT_ID!, 
                    clientSecret: process.env.DATEV_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
datev-smarttransferhttps://login.smarttransfer.datev.de/realms/prod/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { datevSmartTransfer } from "@node-zugferd/traffiqx/better-auth/datev-smarttransfer";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                datevSmartTransfer({ 
                    clientId: process.env.DATEV_CLIENT_ID!, 
                    clientSecret: process.env.DATEV_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
quadienthttps://login.quadient-eservices.com/realms/prod/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { quadient } from "@node-zugferd/traffiqx/better-auth/quadient";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                quadient({ 
                    clientId: process.env.QUADIENT_CLIENT_ID!, 
                    clientSecret: process.env.QUADIENT_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
sghhttps://login.ivi.sgh-net.de/realms/prod/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { sgh } from "@node-zugferd/traffiqx/better-auth/sgh";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                sgh({ 
                    clientId: process.env.SGH_CLIENT_ID!, 
                    clientSecret: process.env.SGH_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});
Provider IDDiscovery Endpoint
ricohhttps://login.ricoh-idx.net/realms/prod/.well-known/openid-configuration
auth.ts
import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";
import { ricoh } from "@node-zugferd/traffiqx/better-auth/ricoh";

const auth = betterAuth({
    plugins: [
        genericOAuth({
            config: [
                ricoh({ 
                    clientId: process.env.RICOH_CLIENT_ID!, 
                    clientSecret: process.env.RICOH_CLIENT_SECRET!, 
                }), 
            ],
        }),
    ],
});

Retrieve an accessToken

The following example will use the b4value provider.

async function getAccessToken() {
    const accounts = await auth.api.listUserAccounts({
        headers: await headers(),
    });

    const account = accounts.find((acc) => acc.providerId === "b4value");

    if (!account) {
        throw new Error("B4Value account is not linked");
    }

    const { accessToken } = await auth.api.getAccessToken({
        body: {
            accountId: account.id,
        },
        headers: await headers(),
    });

    return accessToken;
}

For more details, please refer to the official Better Auth Documentation.

Call a TRAFFIQX endpoint

Use the access token for the signed-in user's linked provider account. The meta value is passed to the token callback, so it can carry your own user or tenant identifier. Keep token retrieval on your server and do not expose provider tokens to browser code.

send-invoice.ts
const { data, error } = await invoicer.traffiqx.upload({
    data: await readFile("./invoice.pdf"),
    traffiqxId: "0042000711688",
    providerId: "b4value.net GmbH",
    accessToken: getAccessToken,
    meta: { userId: "12345" },
});

Best Practices

  • Run uploads and follow-up status checks in a durable background worker. Persist the job state so transient failures or process restarts do not lose track of a document.
  • Make uploads idempotent in your application. Create a stable idempotency key for each business document, record the returned document_id, and check that record before retrying a request whose outcome is unknown. The TRAFFIQX plugin does not provide an idempotency key itself.
  • Retry transient failures with bounded exponential backoff. Before retrying an upload after a timeout, reconcile against the outbox so a successful request with a lost response does not create a duplicate.

Options

Prop

Type


 

llms.txt
Templates

Register named templates and pass one to toPDF when you create an invoice.

Mustang

Validate invoice XML with the Mustang CLI.

Edit on GitHubPrivacyImprint

On this page

InstallationInstall the pluginAdd the plugin to your instanceProviderUsageUpload ZUGFeRD InvoicesUpload Structured Data (XRechnung)Query Document StatusList Outbox DocumentsDownload Outbox DocumentOutbox Document MetadataList Inbox DocumentsDownload Inbox DocumentInbox Document MetadataUsage with Better AuthRegister the OAuth ProviderRetrieve an accessTokenCall a TRAFFIQX endpointBest PracticesOptions

How is this guide?