RechnungsAPI Client for JavaScript / TypeScript

This is the official JavaScript and TypeScript client for RechnungsAPI, a powerful API for generating German invoices, including e-invoices with ZUGFeRD and XRechnung. The API also supports automated double-entry bookkeeping.

This library is fully typed and provides convenient access to all API endpoints.

Documentation

For more detailed information about the API, its features, and all available options, please refer to the official RechnungsAPI Documentation.

The complete API specification is also available as an OpenAPI v3 file.

Installation

You can install the client library using npm or your favorite package manager:

npm install @rechnungs-api/client

Authentication

To use the API, you need an API key. You can get one by signing up at RechnungsAPI.

Initialize the client with your API key. It's recommended to store your key in an environment variable.

import { Client } from "@rechnungs-api/client";

export const client = new Client({
	// It is recommended to load the API key from environment variables
	apiKey: process.env.RECHNUNGS_API_KEY || "YOUR_API_KEY",
});

Usage

Creating an Invoice

Here is an example of how to create a compliant PDF invoice with an embedded ZUGFeRD/XRechnung XML file.

import * as fs from "node:fs/promises";
import type {
	DocumentCreateRequest,
	RecipientParty,
	SenderParty,
} from "@rechnungs-api/client";
import { client } from "./client"; // Your initialized client

// 1. Define the Sender (your company's details)
const sender: SenderParty = {
	name: "Muster GmbH",
	address: {
		line1: "Musterstraße 55a",
		postalCode: "12345",
		city: "Hamburg",
		country: "DE",
	},
	electronicAddress: {
		scheme: "EM",
		value: "[email protected]",
	},
	contact: {
		name: "Max Mustermann",
		email: "[email protected]",
		phone: "+49123456789",
		website: "https://www.rechnungs-api.de",
	},
	vatId: "DE1234569",
	taxId: "12/345/67890",
	owner: "Max Mustermann",
	registration: {
		office: "Amtsgericht Hamburg",
		number: "HRB 12345678",
	},
};

// 2. Define the Recipient (your client's details)
const recipient: RecipientParty = {
	name: "Beispiel UG (haftungsbeschränkt)",
	address: {
		line1: "Musterweg 3c",
		postalCode: "54321",
		city: "Berlin",
		country: "DE",
	},
	electronicAddress: {
		scheme: "EM",
		value: "[email protected]",
	},
	contact: {
		name: "Erika Musterfrau",
		email: "[email protected]",
		phone: "+49987654321",
	},
	vatId: "DE987654321",
};

// 3. Construct the invoice document
const documentRequest: DocumentCreateRequest = {
	type: "invoice",
	locale: "de-DE",
	number: "RE-1012",
	issueDate: "2025-02-28",
	dueDate: "2025-02-28",
	sender,
	recipient,
	buyerReference: "00",

	preTableText:
		"Sehr geehrte Damen und Herren,\n\nDie folgende Leistung wird Ihnen in Rechnung gestellt:",
	postTableText:
		"Bitte überweisen Sie den Betrag binnen 30 Tagen auf das vereinbarte Bankkonto.",

	// Add line items
	lines: [
		{
			unitPrice: { value: "95.00", currency: "EUR" },
			item: {
				name: "Beratung und Konzeption",
				description: "Analyse und Erarbeitung eines Konzepts.",
				vat: { code: "S", rate: "19.00" },
			},
			quantity: { value: "3", unit: "HUR" }, // HUR = Hour
		},
		{
			unitPrice: { value: "500.00", currency: "EUR" },
			item: {
				name: "Erstellung des Logos",
				vat: { code: "S", rate: "19.00" },
			},
			quantity: { value: "1", unit: "H87" }, // H87 = Piece
		},
	],
	// Define payment details
	payment: {
		means: [{
			code: "30", // SEPA credit transfer
			bankAccount: {
				bankName: "Muster Bank",
				iban: "DE12345678901234567890",
				bic: "MUSTER123",
			},
		}],
		terms: "30 Tage Netto",
	},
	// Enable electronic invoicing (e.g., ZUGFeRD / XRechnung)
	eInvoice: {
		type: "zugferd",
		profile: "xrechnung",
	},
	// Customize the look of your invoice
	theme: {
		logo: `data:image/png;base64,${(await fs.readFile("./your_logo.png")).toString("base64")}`,
		fontFamily: "Open Sans",
	},
};

// 4. Create the document via the API
const document = await client.createDocument(documentRequest);
console.log("Successfully created document:", document);

// 5. Download the generated PDF file
const pdfBuffer = await client.readDocument(document.id, "pdf");
await fs.writeFile("invoice.pdf", Buffer.from(pdfBuffer));
console.log("Saved invoice.pdf successfully!");

Working with Ledgers

The API provides a double-entry bookkeeping system to track financial transactions.

Here's a simplified example of how to create a ledger, add accounts, and record transactions.

import type { LedgerAccountCreateRequest } from "@rechnungs-api/client";
import { client } from "./client"; // Your initialized client

// 1. Create a new ledger for your accounting
const ledger = await client.createLedger({
	customData: { internalId: "project-alpha" },
});
console.log("Created ledger:", ledger);

// 2. Define your chart of accounts
const accounts: LedgerAccountCreateRequest[] = [
	{ number: "1800", type: "assets", name: "Bank" },
	{ number: "1200", type: "assets", name: "Forderungen aus LuL" },
	{ number: "4400", type: "revenue", name: "Erlöse 19% USt." },
	{ number: "3806", type: "liabilities", name: "USt. 19%" },
];

// 3. Create the accounts in the ledger
for (const account of accounts) {
	await client.createLedgerAccount(ledger.id, account);
}
console.log("Successfully created accounts.");

// 4. Record a transaction for a new invoice (Value: 1000 + 190 VAT)
await client.createLedgerTransaction(ledger.id, {
	accountingDate: "2025-08-02",
	description: "Invoice RE-100",
	positions: [
		{ debitAccountNumber: "1200", creditAccountNumber: "4400", value: "1000" },
		{ debitAccountNumber: "1200", creditAccountNumber: "3806", value: "190" },
	],
});
console.log("Transaction for invoice RE-100 recorded.");

// 5. Record a transaction for the payment of the invoice
await client.createLedgerTransaction(ledger.id, {
	accountingDate: "2025-08-20",
	description: "Payment for RE-100",
	positions: [
		{ debitAccountNumber: "1800", creditAccountNumber: "1200", value: "1190" },
	],
});
console.log("Payment transaction recorded.");

// 6. List account balances
const balances = await client.listLedgerBalances(ledger.id);
console.log("Current account balances:", balances);