E-Rechnungsfähigkeit per API nachrüsten: So integrieren ERP- und Branchensoftware-Hersteller ZUGFeRD

Die E-Rechnungspflicht trifft auch Softwarehersteller

Seit 2025 müssen Unternehmen im B2B-Bereich elektronische Rechnungen empfangen können. Ab 2027/2028 wird auch der Versand verpflichtend. Das betrifft nicht nur die Unternehmen selbst — sondern auch die Software, die sie einsetzen.

Für Hersteller von ERP-Systemen, Branchensoftware, Handwerkersoftware oder Abrechnungslösungen bedeutet das: Ihre Kunden erwarten E-Rechnungsfähigkeit. Wer sie nicht bietet, verliert Kunden an Wettbewerber, die es tun.

Eigenentwicklung vs. API: Die Build-or-Buy-Entscheidung

Eine ZUGFeRD-/XRechnung-Engine selbst zu bauen ist aufwendiger als es aussieht:

Konservative Schätzung: 3–6 Monate Entwicklungszeit für eine solide Implementierung, plus laufende Wartung bei Standard-Updates.

Die Alternative: Eine API, die das alles übernimmt. Ihre Software schickt ein PDF, die API liefert validiertes ZUGFeRD oder XRechnung zurück. Integrationsaufwand: wenige Tage.

Integrationsmuster für Softwarehersteller

Muster 1: Eingangsrechnungen verarbeiten

Der Kunde Ihrer Software erhält PDF-Rechnungen und möchte die Daten automatisch im System haben.

Kunde lädt PDF hoch → Ihre Software → API-Aufruf
                                         │
                                         ▼
                              JSON mit Rechnungsdaten
                                         │
                                         ▼
                              Daten in Ihrem System anlegen
                              (Lieferant, Rechnung, Positionen)

API-Aufruf:

POST /api/v1/invoices/convert?organizationId=IHRE_ORG_ID
Authorization: Bearer vk_live_...
Content-Type: multipart/form-data

file: [PDF-Bytes]
format: json

Hinweis: Die organizationId ist ein Pflichtparameter. Sie erhalten Ihre Organisations-ID über GET /api/v1/organizations.

Response-Daten direkt mappen:

// Pseudo-Code für Ihr Backend
const result = await callVellonodeAPI(pdfBuffer);
const data = result.data;

await db.invoice.create({
  invoiceNumber: data.invoiceNumber,
  invoiceDate:   data.invoiceDate,
  supplierName:  data.seller?.name,
  supplierVatId: data.seller?.vatId,
  netTotal:      data.totals?.netTotal,
  vatAmount:     data.totals?.vatAmount,
  grossTotal:    data.totals?.grossTotal,
  lines: data.lines.map(line => ({
    description: line.description,
    quantity:    line.quantity,
    unitPrice:   line.unitPrice,
    vatRate:     line.vatRate,
    netAmount:   line.netAmount,
  })),
});

Muster 2: Ausgangsrechnungen als ZUGFeRD erzeugen

Der Kunde erstellt Rechnungen in Ihrer Software und möchte sie als ZUGFeRD-PDF versenden.

Rechnung in Ihrer Software → PDF generieren → API-Aufruf
                                                  │
                                                  ▼
                                       ZUGFeRD-XML + Validierung
                                                  │
                                                  ▼
                                       XML in PDF einbetten
                                       oder separat versenden

API-Aufruf:

POST /api/v1/invoices/convert?organizationId=IHRE_ORG_ID
Authorization: Bearer vk_live_...
Content-Type: multipart/form-data

file: [Rechnungs-PDF]
format: zugferd,xrechnung

Die API liefert sowohl ZUGFeRD-XML als auch XRechnung-XML zurück. Ihre Software kann dem Kunden die Wahl lassen, welches Format versendet wird.

Muster 3: Hybridbetrieb (Eingang + Ausgang)

Die meisten ERP-Systeme brauchen beides. Die API deckt beide Richtungen mit demselben Endpoint ab — der Unterschied liegt nur im gewünschten Output-Format.

API-Integration: Technische Details

Authentifizierung

Jeder Ihrer Kunden erstellt seinen eigenen API-Key in seinem Vellonode-Konto. Das bedeutet:

• Kein Shared Key: Jeder Kunde hat sein eigenes Kontingent und seine eigene Abrechnung
• Key-Rotation: Kunden können Keys jederzeit widerrufen und neue erstellen
• Multi-Key: Bis zu 5 aktive Keys pro Benutzer (z.B. für Staging/Production)

In Ihrer Software speichern Sie den API-Key als Konfigurationsparameter — ähnlich wie einen SMTP-Server oder eine DATEV-Verbindung.

Fehlerbehandlung

Die API liefert strukturierte Fehlercodes. Ihre Software sollte mindestens diese Fälle behandeln:

switch (response.status) {
  case 200:
    // Erfolg — Daten verarbeiten
    break;
  case 402:
    // Kontingent aufgebraucht
    showError("E-Rechnungs-Kontingent aufgebraucht. "
      + "Bitte Plan upgraden.");
    break;
  case 413:
    // Datei zu groß (>10 MB)
    showError("PDF zu groß. Maximum: 10 MB.");
    break;
  case 422:
    // Extraktion fehlgeschlagen
    showError("PDF konnte nicht verarbeitet werden. "
      + "Bitte manuell prüfen.");
    break;
  case 429:
    // Rate-Limit
    const retryAfter = response.headers["Retry-After"];
    await sleep(retryAfter * 1000);
    retry();
    break;
}

Validierungsergebnis nutzen

Die Response enthält ein validation-Objekt mit dem EN16931-Validierungsergebnis. Das können Sie Ihren Kunden direkt anzeigen:

if (!result.validation.valid) {
  for (const error of result.validation.errors) {
    // z.B. { code: "BR-01", message: "...", field: "..." }
    warnings.push(
      `${error.code}: ${error.message}`
    );
  }
}

So sieht der Kunde sofort, ob seine Rechnung EN16931-konform ist — bevor er sie verschickt.

Praxisbeispiel: Handwerkersoftware mit 2.000 Installationen

Ein Hersteller von Handwerkersoftware (Angebote, Aufträge, Rechnungen) für Maler- und Lackiererbetriebe stand vor der Herausforderung, seinen 2.000 Bestandskunden E-Rechnungsfähigkeit zu bieten.

Ausgangslage:

• Desktop-Anwendung (.NET/WPF) mit eigenem PDF-Generator
• Keine E-Rechnungs-Logik vorhanden
• Kunden sind kleine Betriebe (2–15 Mitarbeiter), geringe Belegvolumen
• Eigenentwicklung geschätzt auf 4 Monate + laufende Wartung

Integration der Vellonode API:

• Entwicklungsaufwand: 3 Tage (C# HttpClient, JSON-Parsing, UI-Anpassungen)
• Neuer Button "Als E-Rechnung versenden" in der Rechnungsansicht
• PDF wird im Hintergrund an die API gesendet, ZUGFeRD-XML wird ins PDF eingebettet
• Validierungsergebnis wird dem Benutzer als Ampel angezeigt (grün/gelb/rot)

Ergebnis:

• Feature-Release als Teil eines regulären Updates — kein Migrationsprojekt
• Jeder Kunde bringt seinen eigenen Vellonode-Account mit (Kostenverteilung: Endkunde zahlt, nicht der Softwarehersteller)
• Wartung der E-Rechnungs-Engine entfällt komplett — Updates kommen automatisch über die API

White-Label-Ansatz: API im Hintergrund

Für die Endkunden ist die API unsichtbar. Sie sehen nur die Funktionalität in Ihrer Software:

• "Rechnung als ZUGFeRD versenden"
• "XRechnung für diesen Auftrag erzeugen"
• "Eingangsrechnung automatisch erfassen"

Der API-Key wird einmalig in den Einstellungen hinterlegt. Ab dann funktioniert alles automatisch.

Lizenzmodell für Softwarehersteller

Es gibt zwei gängige Modelle:

1. Endkunde zahlt selbst: Der Endkunde erstellt ein Vellonode-Konto und wählt einen Plan. Ihr Software-Support hilft bei der Einrichtung. Vorteil: kein Kostenrisiko für Sie.

2. Reseller-Modell: Sie bündeln API-Volumen und geben es an Ihre Kunden weiter. Bei Interesse an einem Reseller-Modell kontaktieren Sie uns unter [email protected].

Nächste Schritte

1. Test-Konto erstellen unter vellonode.de/auth/register
2. API-Key generieren und mit 5 Test-PDFs experimentieren
3. OpenAPI-Spec laden: /api/v1/openapi — Client-Code generieren
4. Integration bauen — erfahrungsgemäß 2–5 Tage
5. Rollout — API-Key-Eingabefeld in den Einstellungen, Feature hinter einem Flag

Die API-Dokumentation finden Sie unter /api/v1/openapi.