PlanifyMinds · eRechnung Hub
API Quickstart
Die API unterstützt das Erstellen, Validieren, Importieren und Exportieren von E-Rechnungen für EN 16931, XRechnung und Factur-X. Der Fokus liegt auf nachvollziehbaren Datenflüssen, klaren Fehlerbildern und sauberen Übergaben in bestehende Systeme.
POST /invoices
Rechnung anlegen oder serverseitig erzeugen lassen – inklusive strukturierter Stammdaten, Positionen und Rechnungsmetadaten.
POST /validate
Belege gegen EN 16931, XRechnung-Regeln und technische Pflichtfelder prüfen und Fehler strukturiert zurückgeben.
POST /api/invoices/[id]/export
XML-, PDF- oder ZIP-Ausgaben erzeugen und den Export technisch nachvollziehbar in bestehende Prozesse überführen.
Auth & erster Request
API-Key aus den Einstellungen verwenden
Den API-Key generierst du im Produktbereich unter Einstellungen. Er wird in jedem Request per Header mitgesendet. Für Sandbox und Produktion sollten getrennte Schlüssel und Umgebungen verwendet werden. Der technische Einstieg kann direkt im Dashboard neben Rechnungen, Empfängern und Support genutzt werden.
// Beispiel (Node.js + fetch)
const res = await fetch("https://api.planifyminds.com/erh/invoices", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": process.env.ERH_API_KEY,
},
body: JSON.stringify({
supplier: {
name: "Demo GmbH",
vatId: "DE123456789",
street: "Hauptstraße 1",
zip: "12345",
city: "Musterstadt",
country: "DE",
},
customer: {
name: "Stadt Musterhausen",
leitwegId: "12345-67890-000",
},
invoice: {
number: "2025-1001",
issueDate: "2025-01-10",
currency: "EUR",
},
items: [
{
description: "Wartung Wärmepumpe",
quantity: 1,
unitPrice: 120.0,
},
],
}),
});
const data = await res.json();
console.log(data);Integrationshinweise
Sauber starten, später stabil skalieren
- Zuerst vollständige Flows in der Sandbox testen und danach im Dashboard gegen echte Arbeitsabläufe spiegeln
- Pflichtfelder früh serverseitig validieren und Fehler sauber an die Fachlogik zurückgeben
- Exporte, IDs und Statusänderungen protokollieren, damit Abläufe später nachvollziehbar bleiben
- Webhook-Events zunächst separat loggen, bevor komplexe Business- Logik daran hängt
1. Validierung
Rechnung formal prüfen
Vor produktiver Weiterverarbeitung sollte jede Rechnung gegen Regeln, Pflichtfelder und formale Datenqualität validiert werden. Fehler und Warnungen kommen strukturiert zurück.
POST /validate
Request-Body: {
// gleiche Struktur wie bei /invoices
}
Response:
{
"valid": true,
"warnings": [],
"errors": []
}2. Export
XML, PDF oder ZIP erzeugen
Nach erfolgreicher Prüfung kann die Rechnung in definierte Ausgabeformate exportiert und in Freigaben, ERP-Flows oder nachgelagerte Systeme überführt werden.
POST /api/invoices/[id]/export
Request-Body:
{
"format": "zip"
}
Response:
{
"invoiceId": "inv_82f81",
"format": "zip",
"status": "EXPORTED",
"exportedAt": "2025-01-10T09:15:00Z"
}3. Webhooks & Betrieb
Statusänderungen automatisiert verarbeiten
Für produktive Integrationen empfiehlt sich die Nutzung von Webhooks, um Statusänderungen, Exporte oder Folgeaktionen sauber weiterzuverarbeiten. So bleiben Prozesse im Hintergrund stabil, nachvollziehbar und eng mit dem operativen Dashboard-Kontext verbunden.
POST https://deine-app.de/api/erh/webhook
{
"event": "invoice.exported",
"invoiceId": "inv_82f81",
"status": "EXPORTED",
"details": {
"timestamp": "2025-01-10T09:16:20Z",
"format": "zip"
}
}