API & Integration

API-Authentifizierung

Alle API-Aufrufe erfordern einen Bearer-Token. Erstellen Sie Ihren API-Key im Dashboard unter /app/settings/api.

Bearer-Token

Authorization: Bearer vk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Der API-Zugang ist ab dem Max-Plan verfügbar. Behandeln Sie Ihren API-Key wie ein Passwort – er gewährt vollen Zugriff auf die Konvertierungs-API Ihrer Organisation.

Organisationen

Der Konvertierungs-Endpoint erfordert eine organizationId als Query-Parameter. Rufen Sie zuerst GET /api/v1/organizations auf, um Ihre verfügbaren Organisationen und deren IDs abzurufen.

API-Endpoint

Der zentrale Endpoint konvertiert eine hochgeladene PDF-Rechnung in strukturierte Formate.

Request

POST /api/v1/invoices/convert?organizationId=DEINE_ORG_ID

Der Request erfolgt als multipart/form-data mit folgenden Feldern:

Query-Parameter

Ablage in der Anwendung

Jede konvertierte Rechnung wird zusätzlich in Ihrer Organisation abgelegt und erscheint unter Rechnungen – mit Richtungserkennung, Geschäftspartner- und Artikel-Zuordnung, genau wie bei einem Upload über die Oberfläche. Die IDs der angelegten Rechnungen stehen in der Antwort im Feld stored.invoiceIds.

Fordern Sie format=zugferd an, wird die ausgelieferte hybride PDF zusammen mit ihrem XML archiviert – dieselbe Regel wie beim Versand aus der Anwendung: Eine E-Rechnung, die das Haus verlässt, ist vorher abgelegt. In der Antwort steht dann stored.archived: true.

Das ist wichtig für die Aufbewahrung: Die Download-URLs unter files verfallen nach 24 Stunden. Dauerhaft aufbewahrt wird nur das archivierte Dokument.

Wird dieselbe Datei ein zweites Mal geschickt, erkennt die API das über die Prüfsumme und legt keine doppelte Rechnung an – stored.status ist dann duplicate und verweist auf die bestehende Rechnung.

Wenn Sie ausschließlich konvertieren und nichts ablegen möchten, senden Sie persist=false. Die Konvertierung zählt in beiden Fällen gegen Ihr Monatskontingent.

Soll das dauerhaft gelten, schalten Sie die Ablage unter Einstellungen → API-Zugang ab – dann konvertiert die API grundsätzlich nur noch. Diese Vorgabe wirkt ausschließlich einschränkend: Ein persist=true im Request hebt sie nicht auf, damit ein Plugin die Ablage nicht wieder anschalten kann. Beachten Sie dabei, dass die gesetzliche Aufbewahrungspflicht (§ 147 AO, § 14b UStG) dann vollständig bei Ihnen liegt – die Download-URLs verfallen nach 24 Stunden.

API-Ausgabeformate

Folgende Ausgabeformate stehen zur Verfügung. Sie können mehrere Formate kommagetrennt im Feld format kombinieren.

Verfügbare Formate

• zugferd – ZUGFeRD 2.4 / Factur-X: XML (zugferd_xml) plus PDF/A-3 mit eingebettetem XML (zugferd_pdf)
• xrechnung – XRechnung 3.0 XML (xrechnung_xml)
• json – Strukturierte Rechnungsdaten als JSON
• datev – DATEV Schnittstelle online (LedgerImport XML)

Alle Formate erfüllen den EN16931-Standard für elektronische Rechnungen.

API-Beispiel (Request und Response)

Ein vollständiges Beispiel für einen Aufruf der Konvertierungs-API.

Beispiel-Request

# 1. Organisationen abrufen
curl https://vellonode.de/api/v1/organizations \
  -H "Authorization: Bearer vk_live_abc12345..."

# 2. Rechnung konvertieren (organizationId aus Schritt 1)
curl -X POST "https://vellonode.de/api/v1/invoices/convert?organizationId=DEINE_ORG_ID" \
  -H "Authorization: Bearer vk_live_abc12345..." \
  -F "[email protected]" \
  -F "format=zugferd,json" \
  -F "direction=incoming"

Die Rechnung wird dabei zusätzlich in Ihrer Organisation abgelegt. Mit -F "persist=false" wird nur konvertiert; dauerhaft abschalten lässt sich die Ablage unter Einstellungen → API-Zugang.

Beispiel-Response (200)

{
  "id": "conv_a1b2c3d4e5f6...",
  "data": {
    "invoiceNumber": "RE-2026-001",
    "invoiceDate": "2026-06-01",
    "dueDate": "2026-07-01",
    "currency": "EUR",
    "seller": {
      "name": "Muster GmbH",
      "vatId": "DE123456789"
    },
    "buyer": {
      "name": "Beispiel AG",
      "vatId": "DE987654321"
    },
    "totals": {
      "netTotal": 1500.00,
      "vatAmount": 285.00,
      "grossTotal": 1785.00
    }
  },
  "validation": {
    "valid": true,
    "profile": "EN16931",
    "errors": []
  },
  "files": {
    "zugferd_xml": { "url": "https://vellonode.de/api/v1/files/abc123..." },
    "zugferd_pdf": { "url": "https://vellonode.de/api/v1/files/def456..." },
    "json": { "url": "https://vellonode.de/api/v1/files/ghi789..." }
  },
  "stored": {
    "status": "saved",
    "documentId": "clx1234567890",
    "invoiceIds": ["clx0987654321"],
    "archived": true
  },
  "usage": { "used": 42, "limit": 100 }
}

Die Download-URLs unter files liefern die generierten Dateien – sie verfallen nach 24 Stunden.

Das Feld stored beschreibt die Ablage in der Anwendung. status ist dabei einer der folgenden Werte:

archived sagt, ob die ausgelieferte ZUGFeRD-PDF samt XML archiviert wurde. Das Feld fehlt, wenn keine ZUGFeRD-PDF angefordert war.

API-Fehlercodes

Die API verwendet Standard-HTTP-Statuscodes. Alle Fehler-Responses haben das Format { "error": { "code": "...", "message": "..." } }.

Übersicht

API-Rate-Limits

Zum Schutz der Infrastruktur gelten Rate-Limits pro API-Key.

Limits

• 30 Anfragen pro Minute pro API-Key
• Bei Überschreitung: 429-Response mit Retry-After-Header
• Download-URLs (/api/v1/files/...) sind nicht rate-limitiert

Implementieren Sie ein Backoff anhand des Retry-After-Headers, um Anfragen automatisch zu drosseln.

API-Kontingent

Jede API-Konvertierung verbraucht eine Einheit aus demselben monatlichen Rechnungskontingent wie die Web-Oberfläche.

Verbrauch prüfen

Den aktuellen Verbrauch sehen Sie in jeder erfolgreichen Response im Feld usage oder im Dashboard unter /app/settings/api.

"usage": { "used": 42, "limit": 100 }

Kontingent erschöpft

Ist das Kontingent aufgebraucht, antwortet die API mit Status 402 (quota_exceeded). Die 402-Response enthält ebenfalls das usage-Objekt, sodass Sie programmatisch den aktuellen Verbrauch und das Limit auslesen können:

{ "error": { "code": "quota_exceeded", "message": "..." }, "usage": { "used": 100, "limit": 100 } }

Upgraden Sie Ihren Plan, um das monatliche Kontingent zu erhöhen.

API-Organisationen abrufen

Mit GET /api/v1/organizations rufen Sie alle Organisationen ab, auf die Ihr API-Key Zugriff hat.

Request

GET /api/v1/organizations
Authorization: Bearer vk_live_...

Response (200)

{
  "organizations": [
    {
      "id": "clx...",
      "name": "Muster GmbH",
      "vatId": "DE123456789",
      "role": "admin",
      "plan": "max",
      "subscriptionStatus": "active",
      "invoiceLimit": 500
    }
  ]
}

Die id verwenden Sie als organizationId-Parameter beim Konvertierungs-Endpoint.

API-Benutzerprofil (/me)

/api/v1/me bietet zwei Operationen: Profil abrufen und den eigenen API-Key widerrufen (Logout).

Profil abrufen

GET /api/v1/me
Authorization: Bearer vk_live_...

Response (200)

{
  "user": {
    "id": "clx...",
    "email": "[email protected]",
    "name": "Max Mustermann",
    "lastProvider": "google"
  }
}

lastProvider zeigt den zuletzt verwendeten Login-Anbieter (z. B. google, microsoft-entra-id, credentials).

API-Key widerrufen (Logout)

DELETE /api/v1/me
Authorization: Bearer vk_live_...

Widerruft den API-Key, der im Authorization-Header übergeben wurde. Der Key ist sofort ungültig. Nützlich für Logout-Flows in OAuth-Integrationen.

Response (200)

{ "success": true, "message": "API-Key widerrufen." }

OpenAPI-Spezifikation

Die vollständige OpenAPI 3.1 Spezifikation ist maschinenlesbar verfügbar unter /api/v1/openapi.

Verwendung

Mit der Spezifikation können Sie:

• Client-SDKs in verschiedenen Sprachen generieren (z.B. mit openapi-generator)
• Die API in Tools wie Postman oder Insomnia importieren
• Requests und Responses automatisiert validieren

OAuth / IDP-Hint Login

Für Integrationen (z. B. Office-Add-ins), die den Benutzer per OAuth anmelden und einen API-Token erhalten möchten, steht ein Implicit-Flow zur Verfügung.

OAuth Implicit Flow

GET /oauth/authorize?client_id=vellonode-office-addin&response_type=token&redirect_uri=https://localhost:3001/auth.html&state=xyz&idp_hint=google

Parameter

Erfolg

Nach erfolgreichem Login leitet der Server zurück:

302 → <redirect_uri>#access_token=vk_live_...&token_type=Bearer&state=xyz

Der access_token ist ein vollwertiger API-Key und funktioniert als Authorization: Bearer ... auf allen v1-Endpoints.

Fehlerfall

302 → <redirect_uri>#error=access_denied&error_description=...&state=xyz

Unterstützte Anbieter

Ohne idp_hint wird die reguläre Login-Seite angezeigt. Ist der Benutzer bereits angemeldet, wird er direkt authentifiziert und zurückgeleitet.

API-Datei-Downloads

Die Download-URLs in der Konvertierungs-Response (files-Objekt) sind tokenbasiert und benötigen keinen Bearer-Header.

Mechanik

• Jede URL enthält einen einmaligen Token: /api/v1/files/<token>
• Kein Authorization-Header nötig – der Token im URL ist die Authentifizierung
• Die URLs sind 24 Stunden gültig, danach antwortet der Server mit 410 Gone
• Antwort enthält Content-Disposition: attachment – Browser löst automatisch Download aus
• CORS ist aktiviert – Zugriff aus Add-ins und Browser-Apps möglich

Beispiel-Zugriff

# Direkt herunterladen (kein Auth-Header nötig)
curl -O https://vellonode.de/api/v1/files/abc123...

Hinweise

• Speichern Sie die URLs sofort nach der Konvertierung – sie sind nicht erneut abrufbar
• Pro Konvertierung wird unabhängig von der Anzahl der Formate 1 Einheit vom Kontingent verbraucht
• invoiceLimit (aus /api/v1/organizations) ist das Gesamtlimit des Plans, usage.limit (aus der Convert-Response) ist der aktuelle Verbrauchsstand

Stripe-Konto verbinden

Stripe stellt Rechnungen aus, liefert sie aber nur als PDF — also als „sonstige Rechnung" im Sinne des § 14 UStG, nicht als E-Rechnung. Die Stripe-Anbindung liest die Rechnungsdaten strukturiert aus Ihrem Stripe-Konto und erzeugt daraus eine ZUGFeRD-Rechnung (PDF/A-3 mit eingebettetem XML nach EN 16931).

Das Sicht-PDF bleibt dabei Stripes eigenes Dokument. Bild und Daten stammen aus derselben Quelle und können nicht auseinanderlaufen. Es wird nichts geschätzt und keine KI-Analyse verbraucht.

Schritt 1: Eingeschränkten Key in Stripe anlegen

1. In Stripe auf Entwickler → API-Schlüssel gehen
2. Eingeschränkten Schlüssel erstellen wählen
3. Einen sprechenden Namen vergeben, z.B. „Vellonode E-Rechnung"
4. Diese Leserechte setzen:
   • Invoices: Lesen (zwingend erforderlich)
   • Customers: Lesen (empfohlen — für Anschrift und USt-IdNr. des Kunden)
   • Subscriptions: Lesen (empfohlen — für den Leistungszeitraum)
   • PaymentMethods: Lesen (optional — für Kartenart und die letzten vier Ziffern in der E-Rechnung)
   • Mandates: Lesen (optional — für die Mandatsreferenz bei SEPA-Lastschrift)
5. Schreibrechte werden nicht benötigt. Die Anbindung liest ausschließlich.
6. Den erzeugten Schlüssel (rk_live_…) kopieren

Schritt 2: Key hinterlegen

Unter Einstellungen → Stripe-Anbindung den Schlüssel eintragen und speichern. Er wird vor dem Speichern gegen Stripe geprüft und danach verschlüsselt abgelegt; angezeigt werden nur die letzten vier Zeichen.

Ab dem Verbinden werden neue Rechnungen berücksichtigt. Bestandsrechnungen aus der Vergangenheit werden bewusst nicht ungefragt importiert — sie würden Ihr Rechnungskontingent verbrauchen.

Ältere Rechnungen nachholen: Unter Einstellungen → Stripe-Anbindung → Ältere Rechnungen nachholen wählen Sie ein Startdatum (höchstens 92 Tage zurück) und holen alle Stripe-Rechnungen ab diesem Tag als E-Rechnung nach — etwa ab Monats- oder Quartalsbeginn. Jede neu importierte Rechnung zählt gegen das Kontingent, bereits importierte werden übersprungen. Ist der automatische Versand eingeschaltet, gehen auch die nachgeholten E-Rechnungen an Ihre Kunden.

Schritt 3: Webhook einrichten (optional, empfohlen)

Ohne Webhook werden neue Rechnungen stündlich abgeglichen. Mit Webhook läuft der Import in Sekunden.

1. In Stripe auf Entwickler → Webhooks → Endpunkt hinzufügen
2. Als URL die Adresse eintragen, die auf der Seite „Stripe-Anbindung" angezeigt wird
3. Diese Ereignisse auswählen:
   • invoice.finalized — importiert die Rechnung, sobald Stripe sie ausstellt
   • invoice.paid — trägt die Zahlung ein, sobald Stripe den Betrag eingezogen hat
   • invoice.voided — vermerkt eine in Stripe stornierte Rechnung
4. Das erzeugte Signaturgeheimnis (whsec_…) in Vellonode eintragen

Haben Sie den Webhook früher nur mit invoice.finalized eingerichtet, funktioniert er weiter; Zahlungen und Stornos zieht dann der stündliche Abgleich nach. Für die sofortige Übernahme ergänzen Sie die beiden anderen Ereignisse am bestehenden Endpunkt.

Erst testen, dann live

Die Anbindung funktioniert auch mit einem Key aus dem Testmodus (rk_test_…) und einem Webhook im Testmodus. So können Sie mit einer Testrechnung prüfen, ob Ihre Stripe-Einstellungen und Organisationsdaten für eine E-Rechnung reichen. Beachten Sie: Auch Testrechnungen zählen gegen Ihr Kontingent. Zum Livegang tauschen Sie Key und Signaturgeheimnis gegen die Live-Werte aus.

Warum kein Stripe Connect?

Connect ist für Plattformen gedacht, die Geld im Namen anderer bewegen, und verlangt ein Plattform-Profil samt Haftungsübernahme. Hier wird ausschließlich gelesen. Ein eingeschränkter Schlüssel ist der Weg, den Stripe für Drittanbieter-Integrationen vorsieht — und Sie können ihn jederzeit widerrufen.

Stripe-Rechnungen: Voraussetzungen und Versand

Damit aus einer Stripe-Rechnung eine gültige E-Rechnung nach EN 16931 wird, müssen einige Angaben in Stripe vorhanden sein. Fehlt eine davon, bricht der Import mit einer Meldung ab, die das fehlende Feld benennt — es entsteht bewusst keine formal gültige, inhaltlich unvollständige Rechnung.

Voraussetzungen in Ihrem Stripe-Konto

• Stripe Tax aktiv (automatic_tax) — liefert Steuersatz, Steuerbetrag und die Kennzeichnung für Reverse Charge
• Rechnungsadresse verpflichtend erheben (billing_address_collection: required) — ohne Land des Kunden ist keine E-Rechnung möglich
• USt-IdNr. abfragen (tax_id_collection) — Voraussetzung für die Steuerschuldnerschaft des Leistungsempfängers bei EU-Kunden

Voraussetzungen in Ihren Organisationsstammdaten

Der Rechnungssteller kommt aus Ihrer Organisation, weil Stripe diese Daten über die API nicht herausgibt. Unter Einstellungen → Organisation müssen hinterlegt sein:

• Name und vollständige Anschrift inklusive Ländercode
• USt-IdNr. oder Steuernummer (§ 14 Abs. 4 Nr. 2 UStG)

Zustellung an Ihre Kunden

Unter Einstellungen → Stripe-Anbindung → Zustellung lässt sich der automatische Versand einschalten. Die hybride ZUGFeRD-PDF geht dann an die E-Mail-Adresse, die an der Stripe-Rechnung hinterlegt ist, abgesendet von Ihrer Organisations-Adresse.

Wichtig: Schalten Sie in diesem Fall den Rechnungsversand in Stripe ab. Sonst erhält Ihr Kunde zwei Dokumente zur selben Rechnungsnummer und archiviert womöglich das ohne strukturierten Datensatz.

Bleibt der Versand aus, liegt die E-Rechnung trotzdem als Ausgangsrechnung in Ihrem Konto und lässt sich von dort versenden oder exportieren. Auch die Bereitstellung zum Abruf gilt laut BMF-Schreiben vom 15.10.2024 als wirksame Übermittlung.

Was aus Stripe übernommen wird

Die Kopfsummen entstehen aus den Positionen und werden gegen Stripes Rechnungssumme geprüft. Weichen sie ab, entsteht keine E-Rechnung, sondern ein Eintrag im Importprotokoll mit beiden Beträgen.

Sonderfälle

• Bruttopreise (tax_behavior: inclusive) werden in Netto und Steuer zerlegt.
• Rabatte und Gutscheine — auf Position oder Rechnung — werden vom Positionsbetrag abgezogen und in der Positionsbezeichnung ausgewiesen („abzgl. Nachlass …").
• Tarifwechsel (Proration): Gutschriftpositionen für die Restlaufzeit stehen mit negativer Menge und positivem Preis in der E-Rechnung, wie EN 16931 es verlangt (BR-27).
• Versandkosten am Rechnungskopf werden als eigene Position übernommen.
• Rechnungen mit negativer Summe werden als Gutschrift (Typ 381) mit positiven Beträgen ausgegeben.

Zahlungen und Stornos

Zahlungsart. Die E-Rechnung sagt maschinenlesbar, wie bezahlt wird (BT-81): Zieht Stripe ein, steht dort Kartenzahlung, SEPA-Lastschrift oder Online-Zahlungsdienst (z. B. PayPal) — und keine IBAN. So fordert die Rechnung die Buchhaltung Ihres Kunden nicht zur Überweisung auf, obwohl Stripe den Betrag einzieht. Nur bei einer Zahlungsaufforderung (Stripe-Einstellung „Rechnung senden") steht Ihre IBAN als Überweisungsziel darin. Mit dem optionalen Leserecht auf PaymentMethods kommen Kartenart und die letzten vier Ziffern hinzu; ohne es bleibt es bei der Zahlungsart.

Die E-Rechnung enthält keinen Zahlungsstand. Sie ist die Rechnung über den vollen Betrag; dass Stripe einzieht, sagt die Zahlungsbedingung („wird über das bei Stripe hinterlegte Zahlungsmittel eingezogen"). Ob und wann bezahlt wurde, steht an der Rechnung unter Zahlungen — nicht im Beleg. In der E-Rechnung abgesetzt werden ausschließlich früher berechnete Anzahlungen, etwa in einer Schlussrechnung (§ 14 Abs. 5 Satz 2 UStG); bei Abo-Rechnungen gibt es das nicht.

Importiert wird, sobald Stripe die Rechnung ausstellt — meist bevor der Betrag eingezogen ist. Vellonode trägt die Zahlung deshalb nach, sobald Stripe die Rechnung als bezahlt führt: sofort über das Webhook-Ereignis invoice.paid, sonst beim stündlichen Abgleich (für bis zu 120 Tage alte Rechnungen). Die Zahlung erscheint an der Rechnung als Zahlungseingang „über Stripe". Bezahlte Rechnungen stehen damit nicht in den offenen Posten und werden nicht gemahnt. Haben Sie die Zahlung bereits über den Kontoauszug zugeordnet, wird sie nicht doppelt angelegt.

Als bezahlt gilt eine Rechnung, die Stripe auf „paid" führt — auch wenn sie aus dem Kundenguthaben beglichen oder in Stripe als außerhalb bezahlt markiert wurde.

Storno: Stornieren Sie eine Rechnung in Stripe (Status „void"), wird sie in Vellonode als storniert vermerkt. Ist sie dort bereits verbucht (z. B. DATEV-Export) oder sind Zahlungen erfasst, vermerkt Vellonode das nicht still, sondern meldet es im Importprotokoll — dann erstellen Sie in Vellonode eine Gutschrift.

Grenzen

• Gutschriften (Credit Notes) aus Stripe werden nicht übernommen. Eine Korrektur erstellen Sie in Vellonode als Gutschrift zur importierten Rechnung.
• Mehrere Steuerkategorien auf einer Position lassen sich nach EN 16931 nicht abbilden; der Import bricht mit einer Meldung ab.
• Format: Erzeugt wird ZUGFeRD 2.4 im Profil EN 16931. Einen Peppol-Zugangspunkt bietet Vellonode nicht an.

Kontingent und Nachvollziehbarkeit

Importierte Rechnungen zählen wie jede andere Ausgangsrechnung gegen Ihr Monatslimit. Das Kontingent wird erst gebucht, nachdem die E-Rechnung erzeugt wurde — was vorher scheitert, kostet nichts.

Was mit welcher Rechnung passiert ist, steht im Importprotokoll auf der Seite „Stripe-Anbindung": importiert, übersprungen oder fehlgeschlagen, jeweils mit Begründung, dazu ob sie versendet und ob sie in Stripe bezahlt oder storniert ist.

Häufige Meldungen

• „BT-44: Der Stripe-Kunde hat keinen Namen" — Namen am Kunden im Stripe-Dashboard ergänzen und die Rechnung über „Ältere Rechnungen nachholen" erneut abgleichen.
• „BT-55: … keine Rechnungsanschrift mit Land" — Rechnungsanschrift am Kunden ergänzen; für künftige Rechnungen die Adresse in Checkout bzw. im Kundenportal verpflichtend abfragen.
• „Der Organisation fehlt USt-IdNr. und Steuernummer" — unter Einstellungen → Organisation ergänzen.
• „… weicht von der Stripe-Rechnungssumme ab" — die Rechnung enthält eine Konstellation, die nicht sicher abbildbar ist. Wenden Sie sich mit der Rechnungsnummer an den Support.

Hinweis zum erneuten Abgleich: Eine fehlgeschlagene Rechnung wird beim nächsten Abgleich erneut versucht, sobald sie im Zeitraum liegt — nach einer Korrektur in Stripe genügt daher „Nachholen" mit einem Datum vor dem Rechnungsdatum.