XRechnung per API erstellen: Ein vollständiges Tutorial mit RechnungsAPI

Die elektronische Rechnungsstellung wird in Deutschland immer wichtiger. Seit November 2020 sind Bundesbehörden verpflichtet, elektronische Rechnungen im XRechnung-Format zu akzeptieren. Für viele Unternehmen bedeutet dies eine Herausforderung: Wie erstellt man konforme XRechnungen, ohne sich in die komplexen XML-Standards einarbeiten zu müssen?

In diesem Tutorial zeigen wir, wie Sie mit der RechnungsAPI einfach und schnell XRechnungen erstellen können - ganz ohne UBL-Kenntnisse.

Inhaltsverzeichnis

• Was ist eine XRechnung?
• Das Problem mit nativen UBL/XML
• Setup und Installation: Der erste Schritt
• Client-Initialisierung
• Schritt-für-Schritt: XRechnung erstellen
• Vollständiges Arbeitsbeispiel
• Erweiterte Features für professionelle Anwendungen
• Fazit

Was ist eine XRechnung?

XRechnung ist der deutsche Standard für elektronische Rechnungen im öffentlichen Sektor. Es basiert auf der europäischen Norm EN 16931 und nutzt technisch das UBL (Universal Business Language) Format. XRechnungen sind strukturierte XML-Dokumente, die maschinell verarbeitet werden können und dadurch Prozesse automatisieren.

Das Problem mit nativen UBL/XML

Wer schon einmal versucht hat, XRechnungen direkt als XML zu erstellen, weiß: Es ist komplex und fehleranfällig. Schauen wir uns ein paar Beispiele an, wie eine einfache Adresse in nativem UBL aussieht:

Adressdarstellung: Der Unterschied wird sofort sichtbar

Eine einfache Adresse in nativem UBL erfordert eine verschachtelte XML-Struktur mit spezifischen Namespace-Präfixen:

<cac:PostalAddress>
    <cbc:StreetName>Musterstraße</cbc:StreetName>
    <cbc:AdditionalStreetName>55a</cbc:AdditionalStreetName>
    <cbc:CityName>Hamburg</cbc:CityName>
    <cbc:PostalZone>12345</cbc:PostalZone>
    <cac:Country>
        <cbc:IdentificationCode>DE</cbc:IdentificationCode>
    </cac:Country>
</cac:PostalAddress>

Dieselbe Adresse in der RechnungsAPI benötigt nur wenige Zeilen verständliches JSON:

{
  "address": {
    "line1": "Musterstraße 55a",
    "postalCode": "12345",
    "city": "Hamburg",
    "country": "DE"
  }
}

Der Unterschied ist deutlich: Statt verschachtelter XML-Strukturen mit kryptischen Namespace-Präfixen wie cac: und cbc: haben wir ein intuitives, selbsterklärendes JSON-Format. Entwickler müssen sich nicht mehr mit XML-Namespaces, Validierung oder der korrekten Verschachtelung auseinandersetzen.

Kontaktdaten: Einfachheit vs. Komplexität

Die Darstellung von Kontaktdaten zeigt die Problematik noch deutlicher. Das erforderliche UBL XML:

<cac:Contact>
    <cbc:Name>Max Mustermann</cbc:Name>
    <cbc:ElectronicMail>max.mustermann@example.com</cbc:ElectronicMail>
    <cbc:Telephone>+49123456789</cbc:Telephone>
</cac:Contact>

Im Vergleich dazu unser vereinfachtes, aber vollständiges Format:

{
  "contact": {
    "name": "Max Mustermann",
    "email": "max.mustermann@example.com",
    "phone": "+49123456789"
  }
}

Hier wird besonders deutlich, wie die RechnungsAPI die Barriere für Entwickler senkt, die keine XML-Experten sind, aber trotzdem konforme XRechnungen erstellen müssen.

Rechnungspositionen: Wo die Komplexität explodiert

Bei Rechnungspositionen wird die Komplexität von UBL besonders deutlich. Eine einzige Rechnungsposition erfordert in nativem UBL (hier stark vereinfacht dargestellt):

<cac:InvoiceLine>
    <cbc:ID>1</cbc:ID>
    <cbc:InvoicedQuantity unitCode="HUR">3</cbc:InvoicedQuantity>
    <cbc:LineExtensionAmount currencyID="EUR">285.00</cbc:LineExtensionAmount>
    <cac:Item>
        <cbc:Name>Beratung und Konzeption</cbc:Name>
        <cbc:Description>Analyse und Erarbeitung eines Konzepts</cbc:Description>
        <cac:ClassifiedTaxCategory>
            <cbc:ID>S</cbc:ID>
            <cbc:Percent>19</cbc:Percent>
            <cac:TaxScheme>
                <cbc:ID>VAT</cbc:ID>
            </cac:TaxScheme>
        </cac:ClassifiedTaxCategory>
    </cac:Item>
    <cac:Price>
        <cbc:PriceAmount currencyID="EUR">95.00</cbc:PriceAmount>
    </cac:Price>
</cac:InvoiceLine>

Die gleiche Information im RechnungsAPI-Format konzentriert sich auf das Wesentliche:

{
  "unitPrice": { "value": "95.00", "currency": "EUR" },
  "quantity": { "value": "3", "unit": "HUR" },
  "item": {
    "name": "Beratung und Konzeption",
    "description": "Analyse und Erarbeitung eines Konzepts",
    "vat": { "code": "S", "rate": "19.00" }
  }
}

Diese Vereinfachung bedeutet nicht, dass Funktionalität verloren geht. Die RechnungsAPI generiert im Hintergrund das vollständig konforme UBL-XML.

Setup und Installation: Der erste Schritt

Wir verwenden im nachfolgenden Abschnitt beispielhaft das offizielle Node.js SDK von RechnungsAPI. Da RechnungsAPI eine REST-API mit OpenAPI Spezifikation ist, lassen sich die notwendigen HTTP-Aufrufe in jeder gängigen Programmiersprache erledigen. Auch die automatische Erstellung von Client-Code mithilfe von OpenAPI-Generatoren ist möglich.

Beginnen wir mit der praktischen Implementierung. Zuerst installieren wir den offiziellen Client:

npm install @rechnungs-api/client

Das SDK bietet vollständige TypeScript-Unterstützung, was bedeutet, dass Ihr Editor Sie bei der Entwicklung mit Autocomplete und Typprüfung unterstützt. Dies reduziert Fehler erheblich und beschleunigt die Entwicklung.

Client-Initialisierung

Erstellen Sie eine Client-Instanz mit Ihrem API-Key. Den Key erhalten Sie nach der Registrierung auf rechnungs-api.de.

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

export const client = new Client({
  // Verwenden Sie Umgebungsvariablen für produktive Anwendungen
  apiKey: process.env.RECHNUNGS_API_KEY || "YOUR_API_KEY",
});

Wichtig: Verwenden Sie für Tests den Test-API-Key (beginnt mit test_) und für Produktion den Produktions-Key (beginnt mit prod_).

Schritt-für-Schritt: XRechnung erstellen

Schritt 1: Absender definieren - Ihr Unternehmen rechtssicher darstellen

Der Absender ist, falls Sie nicht im Namen anderer Rechnungen erstellen wollen, in der Regel Ihr eigenes Unternehmen. Viele der hier gemachten Angaben sind für eine rechtskonforme XRechnung erforderlich. Die XRechnung-Spezifikation ist sehr strikt, was die Vollständigkeit der Absenderinformationen angeht:

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

const sender: SenderParty = {
  name: "Muster GmbH",
  address: {
    line1: "Musterstraße 55a",
    postalCode: "12345", 
    city: "Hamburg",
    country: "DE",
  },
  // Elektronische Adresse - erforderlich für XRechnung
  electronicAddress: {
    scheme: "EM", // EM = E-Mail
    value: "info@example.com",
  },
  contact: {
    name: "Max Mustermann",
    email: "max.mustermann@example.com", 
    phone: "+49123456789",
    website: "https://www.example.com",
  },
  vatId: "DE123456789", // USt-IdNr.
  taxId: "12/345/67890", // Steuernummer
  owner: "Max Mustermann", // Geschäftsführer
  registration: {
    office: "Amtsgericht Hamburg",
    number: "HRB 123456",
  },
};

Detaillierte Erläuterung der wichtigsten Felder:

• electronicAddress: Dieses Feld ist für XRechnung zwingend erforderlich und dient der elektronischen Zustellung. Der Wert scheme: "EM" steht für E-Mail-Adresse. Andere mögliche Schemes sind beispielsweise Leitweg-IDs für Behörden.
• vatId: Die Umsatzsteuer-Identifikationsnummer ist für umsatzsteuerpflichtige Unternehmen verpflichtend und muss das Format "DE" + 9 Ziffern haben.
• taxId: Die Steuernummer des zuständigen Finanzamts. Das Format variiert je nach Bundesland.
• owner: Bei Kapitalgesellschaften (GmbH, AG) ist die Angabe der vertretungsberechtigten Person erforderlich.
• registration: Handelsregistereintrag ist bei Kapitalgesellschaften verpflichtend. Die Angaben müssen exakt mit dem Handelsregisterauszug übereinstimmen.

Diese Vollständigkeit der Angaben stellt sicher, dass Ihre XRechnungen von allen Empfängersystemen korrekt verarbeitet werden können und alle rechtlichen Anforderungen erfüllen.

Schritt 2: Empfänger definieren - Kunden korrekt erfassen

Der Empfänger ist Ihr Kunde, und auch hier sind vollständige Angaben wichtig für die Verarbeitbarkeit der XRechnung. Besonders bei Rechnungen an Behörden gibt es spezielle Anforderungen:

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

const recipient: RecipientParty = {
  name: "Beispiel UG (haftungsbeschränkt)",
  address: {
    line1: "Musterweg 3c",
    postalCode: "54321",
    city: "Berlin", 
    country: "DE",
  },
  electronicAddress: {
    scheme: "EM",
    value: "buchhaltung@beispiel-ug.de",
  },
  contact: {
    name: "Erika Musterfrau",
    email: "erika.musterfrau@beispiel-ug.de",
    phone: "+49987654321",
  },
  vatId: "DE987654321",
};

Das Feld eletronicAddress wird dabei mit dem Electronic Address Scheme (EAS) definiert.

Besonderheiten bei Rechnungen an Behörden: Wenn Sie Rechnungen an öffentliche Auftraggeber (Behörden, Kommunen, etc.) stellen, müssen Sie deren spezielle elektronische Adresse verwenden - die sogenannte Leitweg-ID. In diesem Fall würden Sie die electronicAddress wie folgt anpassen:

electronicAddress: {
  scheme: "130", // Standard-Schema für deutsche Leitweg-IDs
  value: "991-12345-67890-12", // Die spezifische Leitweg-ID der Behörde
}

Die Leitweg-ID erhalten Sie normalerweise zusammen mit der Auftragsbestätigung oder können diese beim Auftraggeber erfragen. Sie ist essentiell für die korrekte Zustellung der XRechnung an die richtige Kostenstelle innerhalb der Behörde.

Schritt 3: Zahlungsinformationen festlegen - Wie soll bezahlt werden?

Die Zahlungsinformationen sind ein kritischer Teil jeder Rechnung und müssen präzise definiert werden, damit Ihre Kunden wissen, wie sie bezahlen sollen:

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

const payment: PaymentInformation = {
  means: [{
    code: "30", // SEPA-Überweisung 
    bankAccount: {
      bankName: "Muster Bank",
      iban: "DE12345678901234567890",
      bic: "MUSTDE12XXX",
    },
  }],
  terms: "Zahlbar innerhalb von 30 Tagen netto",
};

Verständnis der Payment Codes: Die Codes folgen dem UNTDID 4461. Die wichtigsten Codes für deutsche Unternehmen sind:

• 30 - SEPA-Überweisung (am häufigsten verwendet)
• 10 - Barzahlung (für Kleinbeträge)
• 20 - Scheckzahlung (selten verwendet)
• 30 - Krebitübertragung (SEPA-Überweisung)
• 31 - Debitübertragung (Lastschriftverfahren)
• 42 - Zahlung direkt an Bank
• 48 - Bankguthaben (Gutschrift)

Schritt 4: Rechnungspositionen erstellen

Jetzt definieren wir die einzelnen Leistungen oder Produkte:

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

const lines: DocumentLineCreateRequest[] = [
  {
    unitPrice: { value: "95.00", currency: "EUR" },
    item: {
      name: "Beratung und Konzeption",
      description: "Analyse und Erarbeitung eines Konzepts für die Digitalisierung",
      vat: { code: "S", rate: "19.00" }, // S = Standard rate
    },
    quantity: { value: "3", unit: "HUR" }, // HUR = Hour (Stunde)
  },
  {
    unitPrice: { value: "500.00", currency: "EUR" },
    item: {
      name: "Logo-Design",
      description: "Entwicklung eines Corporate Designs inkl. Logo",
      vat: { code: "S", rate: "19.00" },
    },
    quantity: { value: "1", unit: "H87" }, // H87 = Piece (Stück)
  },
];

Wichtige Hinweise zu Einheit-Codes: Die API verwendet die UN/ECE-Empfehlung No. 20 für Einheitencodes. Diese standardisierten Codes stellen sicher, dass Ihre Rechnungen international verständlich sind:

• HUR = Stunde (Hour) - für Dienstleistungen
• H87 = Stück (Piece) - für einzelne Artikel oder Leistungen
• MTR = Meter - für Längenangaben
• MTK = Quadratmeter - für Flächenangaben
• MTQ = Kubikmeter - für Volumenangaben
• KGM = Kilogramm - für Gewichtsangaben
• DAY = Tag - für tagesweise Abrechnung

Umsatzsteuer-Codes und deren Bedeutung: Die Umsatzsteuer-Codes folgen dem internationalen Standard UNTDID 5305:

• S = Standard rate (Normalsatz, aktuell 19% in Deutschland)
• A = Reduced rate (ermäßigter Satz, aktuell 7% in Deutschland)
• Z = Zero rate (0% - für bestimmte Leistungen wie Ausfuhrlieferungen)
• E = Exempt (steuerbefreit - für bestimmte medizinische, pädagogische Leistungen)
• AE = VAT Reverse Charge (Reverse-Charge-Verfahren bei B2B-Leistungen)

Schritt 5: XRechnung-Konfiguration

Die XRechnung-Konfiguration ist der Teil, der Ihre normale Rechnung in eine XRechnung verwandelt. Hier werden die Parameter gesetzt, die bestimmen, wie das finale XML-Dokument generiert wird:

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

const eInvoiceConfig: EInvoiceConfiguration = {
  type: "xrechnung", // Alternativ "zugferd"
  syntax: "ubl", // Alternativ "cii"
  embedPdf: true, // PDF in XML einbetten
};

Detaillierte Erklärung der Parameter:

• type: "xrechnung": Dies aktiviert die XRechnung-Generierung. Die RechnungsAPI unterstützt auch andere Standards wie "zugferd" für ZUGFeRD-Rechnungen, die im B2B-Bereich verwendet werden.
• syntax: "ubl": Definiert die verwendete XML-Syntax. UBL (Universal Business Language) ist der in Deutschland bevorzugte Standard für XRechnung. Alternativ steht "cii" (UN/CEFACT Cross Industry Invoice) zur Verfügung.
• embedPdf: true: RechnungsAPI kann optional auf basis der Rechnungsdaten auch eine menschenlesbare PDF erstellen. Mit der Option embedPdf lässt sich diese PDF als Datensatz in die UBL-Datei einbetten.

Warum UBL wählen? UBL ist der in Deutschland am weitesten verbreitete Standard für XRechnung und wird von allen öffentlichen Empfängern unterstützt. Die meisten ERP-Systeme und Rechnungsverarbeitungssoftware sind auf UBL optimiert.

Schritt 6: Die vollständige Rechnung zusammenbauen

Jetzt fügen wir alle definierten Komponenten zu einer vollständigen Rechnung zusammen. Hier werden auch zusätzliche Metadaten und Texte definiert, die die Rechnung vervollständigen:

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

const documentRequest: DocumentCreateRequest = {
  // Alternativ auch `credit-note` und andere Dokumententype verfügbar.
  type: "invoice",
  locale: "de-DE",
  number: "RE-2024-001",
  issueDate: "2024-02-28",
  dueDate: "2024-03-29", // 30 Tage später
  
  sender,
  recipient,
  payment,
  lines,
  
  // XRechnung aktivieren
  eInvoice: eInvoiceConfig,
  
  // Buyer Reference für XRechnung (oft erforderlich)
  buyerReference: "PROJEKT-2024-XR",
  
  // Texte für die Rechnung
  preTableText: "Sehr geehrte Damen und Herren,\n\nfür die erbrachten Leistungen stellen wir Ihnen folgende Positionen in Rechnung:",
  postTableText: "Vielen Dank für Ihren Auftrag! Bitte überweisen Sie den Betrag bis zum Fälligkeitsdatum auf das angegebene Konto.",
  
  // Optional: Theme für PDF-Gestaltung
  theme: {
    fontFamily: "Open Sans",
    // logo: `data:image/png;base64,${logoBase64}`, // Base64-kodiertes Logo
  },
};

Wichtige Felder für XRechnung:

• buyerReference: Dies ist oft die Referenz des Käufers und kann eine Auftragsnummer, Projektnummer oder bei Behörden die Leitweg-ID sein. Viele öffentliche Auftraggeber verlangen diese Referenz zur korrekten Zuordnung.
• issueDate und dueDate: Beide Datumsangaben müssen im ISO-Format (YYYY-MM-DD) angegeben werden. Die Fälligkeit sollte realistisch gewählt werden - üblich sind 14, 30 oder 60 Tage.
• preTableText und postTableText: Diese Texte machen Ihre Rechnung professioneller und persönlicher. Sie können hier wichtige Hinweise, Danksagungen oder zusätzliche Informationen unterbringen.

Das Theme-System der RechnungsAPI ermöglicht es, das Erscheinungsbild Ihrer Rechnungen an Ihr Corporate Design anzupassen, ohne dass Sie sich um die PDF-Generierung kümmern müssen.

Schritt 7: Rechnung erstellen und herunterladen - Der finale Schritt

Nachdem alle Komponenten definiert sind, können wir endlich die XRechnung erstellen. Dieser Prozess läuft vollständig automatisiert ab:

import * as fs from "node:fs/promises";

try {
  // Dokument erstellen
  console.log("Erstelle XRechnung...");
  const document = await client.createDocument(documentRequest);
  console.log(`XRechnung erstellt! ID: ${document.id}`);
  
  // XRechnung XML herunterladen  
  console.log("Lade XRechnung XML herunter...");
  const xmlBuffer = await client.readDocument(document.id, "xml");
  await fs.writeFile("xrechnung.xml", Buffer.from(xmlBuffer));
  console.log("XRechnung XML gespeichert als xrechnung.xml");
  
  return document;
} catch (error) {
  console.error("Fehler beim Erstellen der XRechnung:", error);
  throw error;
}

Die eingebettete PDF in der XRechnung sieht wie folgt aus:

Vollständiges Arbeitsbeispiel

Hier ist das komplette, lauffähige Beispiel:

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

// Client initialisieren
const client = new Client({
  apiKey: process.env.RECHNUNGS_API_KEY || "YOUR_API_KEY",
});

// Absender definieren
const sender: SenderParty = {
  name: "Muster GmbH",
  address: {
    line1: "Musterstraße 55a",
    postalCode: "12345",
    city: "Hamburg", 
    country: "DE",
  },
  electronicAddress: {
    scheme: "EM",
    value: "info@example.com",
  },
  contact: {
    name: "Max Mustermann",
    email: "max.mustermann@example.com",
    phone: "+49123456789",
    website: "https://www.example.com",
  },
  vatId: "DE123456789",
  taxId: "12/345/67890", 
  owner: "Max Mustermann",
  registration: {
    office: "Amtsgericht Hamburg",
    number: "HRB 123456",
  },
};

// Empfänger definieren
const recipient: RecipientParty = {
  name: "Beispiel UG (haftungsbeschränkt)",
  address: {
    line1: "Musterweg 3c",
    postalCode: "54321",
    city: "Berlin",
    country: "DE",
  },
  electronicAddress: {
    scheme: "EM", 
    value: "buchhaltung@beispiel-ug.de",
  },
  contact: {
    name: "Erika Musterfrau",
    email: "erika.musterfrau@beispiel-ug.de",
    phone: "+49987654321",
  },
  vatId: "DE987654321",
};

// Rechnung erstellen
const documentRequest: DocumentCreateRequest = {
  type: "invoice",
  locale: "de-DE", 
  number: "RE-2024-001",
  issueDate: "2024-02-28",
  dueDate: "2024-03-29",
  
  sender,
  recipient,
  buyerReference: "PROJEKT-2024-XR",
  
  preTableText: "Sehr geehrte Damen und Herren,\n\nfür die erbrachten Leistungen stellen wir Ihnen folgende Positionen in Rechnung:",
  postTableText: "Vielen Dank für Ihren Auftrag! Bitte überweisen Sie den Betrag bis zum Fälligkeitsdatum auf das angegebene Konto.",
  
  // Rechnungspositionen
  lines: [
    {
      unitPrice: { value: "95.00", currency: "EUR" },
      item: {
        name: "Beratung und Konzeption", 
        description: "Analyse und Erarbeitung eines Konzepts für die Digitalisierung",
        vat: { code: "S", rate: "19.00" },
      },
      quantity: { value: "3", unit: "HUR" },
    },
    {
      unitPrice: { value: "500.00", currency: "EUR" },
      item: {
        name: "Logo-Design",
        description: "Entwicklung eines Corporate Designs inkl. Logo", 
        vat: { code: "S", rate: "19.00" },
      },
      quantity: { value: "1", unit: "H87" },
    },
  ],
  
  // Zahlungsinformationen
  payment: {
    means: [{
      code: "30",
      bankAccount: {
        bankName: "Muster Bank",
        iban: "DE12345678901234567890", 
        bic: "MUSTDE12XXX",
      },
    }],
    terms: "Zahlbar innerhalb von 30 Tagen netto",
  },
  
  // XRechnung aktivieren
  eInvoice: {
    type: "xrechnung",
    syntax: "ubl",
    embedPdf: true,
  },
  
  // Theme anpassen
  theme: {
    fontFamily: "Open Sans",
  },
};

// Hauptfunktion
async function main() {
  try {
    console.log("Erstelle XRechnung...");
    const document = await client.createDocument(documentRequest);
    console.log(`✅ XRechnung erstellt! ID: ${document.id}`);
    
    // XRechnung XML herunterladen
    const xmlBuffer = await client.readDocument(document.id, "xml");
    await fs.writeFile("xrechnung.xml", Buffer.from(xmlBuffer)); 
    console.log("✅ XRechnung XML gespeichert als xrechnung.xml");
    
    // Dokumentdetails ausgeben
    console.log("\n📋 Rechnungsdetails:");
    console.log(`Nummer: ${document.number}`);
    console.log(`Nettobetrag: ${document.netAmount.value} ${document.netAmount.currency}`);
    console.log(`Bruttobetrag: ${document.grossAmount.value} ${document.grossAmount.currency}`);
    console.log(`Erstellt: ${document.createdAt}`);
    console.log(`Verfällt: ${document.expiresAt}`);
    
  } catch (error) {
    console.error("❌ Fehler:", error);
  }
}

main();

Erweiterte Features für professionelle Anwendungen

Die RechnungsAPI bietet über die Grundfunktionalität hinaus viele erweiterte Features, die Ihre Rechnungen noch professioneller und funktionaler machen.

Logo hinzufügen - Ihr Corporate Design umsetzen

Ein professionelles Logo macht Ihre Rechnungen vertrauensvoller und verstärkt Ihre Markenidentität. Die RechnungsAPI unterstützt verschiedene Bildformate:

import * as fs from "node:fs/promises";

// Logo als Base64 laden
const logoBuffer = await fs.readFile("./logo.png");
const logoBase64 = logoBuffer.toString("base64");

// Im theme verwenden
const documentRequest: DocumentCreateRequest = {
  // ... andere Felder
  theme: {
    logo: `data:image/png;base64,${logoBase64}`,
    fontFamily: "Open Sans",
  },
};

Lieferadresse hinzufügen

In vielen Geschäftssituationen unterscheidet sich die Lieferadresse von der Rechnungsadresse. Dies ist besonders bei Großkunden mit mehreren Standorten üblich:

const documentRequest: DocumentCreateRequest = {
  // ... andere Felder
  delivery: {
    address: {
      line1: "Lieferstraße 10",
      postalCode: "98765",
      city: "München", 
      country: "DE",
    },
  },
};

Lieferzeitraum definieren

Für Dienstleistungen oder langfristige Projekte ist die Angabe des Leistungszeitraums sowohl rechtlich als auch praktisch wichtig:

const documentRequest: DocumentCreateRequest = {
  // ... andere Felder
  deliveryPeriod: {
    startDate: "2024-02-01", // Beginn der Leistungserbringung
    endDate: "2024-02-28",   // Ende der Leistungserbringung
    vatDate: "35", // USt. wird am Ende des Zeitraums fällig
  },
};

Bedeutung der verschiedenen Datums-Parameter:

• startDate: Wann haben Sie mit der Leistungserbringung begonnen?
• endDate: Wann war die Leistung vollständig erbracht?
• vatDate: Wann wird die Umstatzsteuer fällig? Hier wird der Standard UNTDID 2005 verwendet.

Häufige vatDate-Codes:

• 35: USt. wird am Ende des Leistungszeitraums fällig
• 72: USt. wird bei Rechnungsstellung fällig
• 432: USt. wird bei Zahlung fällig

Error Handling

Implementieren Sie robustes Error Handling:

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

try {
  const document = await client.createDocument(documentRequest);
  // ...
} catch (error) {
  if (error instanceof ApiError) {
    // API-spezifische Fehler
    console.error(`API Fehler [${error.status}]: ${error.body}`);
  }
  throw error;
}

Fazit

Die RechnungsAPI macht die Erstellung von XRechnungen deutlich einfacher als die direkte XML-Bearbeitung. Statt sich mit komplexen UBL-Strukturen zu beschäftigen, arbeiten Sie mit einem intuitiven JSON-API.

Die wichtigsten Vorteile im Überblick:

• Einfach: JSON statt XML
• Sicher: Automatische Validierung
• Komplett: PDF + XRechnung XML in einem Aufruf
• Flexibel: Unterstützung für viele XRechnung-Features
• Developer-friendly: TypeScript-Support, gute Dokumentation

Mit diesem Tutorial können Sie sofort anfangen, XRechnungen zu erstellen. Die RechnungsAPI übernimmt die komplexe XML-Generierung und Sie können sich auf Ihre Geschäftslogik konzentrieren.

Für weitere Informationen und erweiterte Features besuchen Sie die offizielle Dokumentation. Dort lässt sich die API auch direkt mit Beispielen ausprobieren.