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@betaAdd the plugin to your instance
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 ID | Discovery Endpoint |
|---|---|
b4value | https://login.b4value.net/realms/prod/.well-known/openid-configuration |
| https://login.qs.b4value.net/realms/qs/.well-known/openid-configuration (Sandbox) |
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 ID | Discovery Endpoint |
|---|---|
bundesdruckerei | https://login.bdr-businessportal.de/realms/prod/.well-known/openid-configuration |
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 ID | Discovery Endpoint |
|---|---|
datev-e-rechnungsplattform | https://signin.datev.de/datevam/oauth2/realms/root/realms/user/.well-known/openid-configuration |
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 ID | Discovery Endpoint |
|---|---|
datev-smarttransfer | https://login.smarttransfer.datev.de/realms/prod/.well-known/openid-configuration |
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 ID | Discovery Endpoint |
|---|---|
quadient | https://login.quadient-eservices.com/realms/prod/.well-known/openid-configuration |
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 ID | Discovery Endpoint |
|---|---|
sgh | https://login.ivi.sgh-net.de/realms/prod/.well-known/openid-configuration |
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 ID | Discovery Endpoint |
|---|---|
ricoh | https://login.ricoh-idx.net/realms/prod/.well-known/openid-configuration |
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.
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