API & Webhooks

Datenimport über die REST-API

Aktualisiert am 11. März 2026

Überblick

Beim Wechsel von einem anderen System zu Kyvento übernehmen Sie Ihren Datenbestand – Kunden, Abonnements, offene und bereits abgeschlossene Rechnungen sowie die zugehörigen Zahlungen – über die Kyvento REST-API. Dieser Artikel beschreibt die Reihenfolge der Übernahme, die dafür vorgesehenen Endpunkte und die Einstellungen, mit denen sich ein unterbrochener Importlauf gefahrlos wiederholen lässt.

Kein Massenimport per Datei: Kyvento bietet keinen Datei-Upload für Massendaten an. Ein solcher Import würde die Fachdienste umgehen, die bei jeder Anlage greifen – die Prüfung der Umsatzsteuer-Identifikationsnummer, die Ermittlung des Steuersatzes sowie die Ereignisse, auf denen Mahnwesen, Buchhaltungsexport und Auswertungen aufbauen. Die Übernahme erfolgt daher über dieselben Endpunkte wie Ihre laufende Integration, Datensatz für Datensatz.

Voraussetzungen

Ein Personal Access Token (siehe API-Zugang einrichten und API-Key erstellen). Übergeben Sie ihn bei jedem Aufruf im Header Authorization: Bearer <Token>.
Die erforderlichen Berechtigungen auf dem Token: customers:full, subscriptions:full und invoices:full. Ein Token mit reinem Lesezugriff ist für die Übernahme nicht ausreichend.
Alle Produkte und Rabattcodes, auf die Ihre Abonnements verweisen, müssen in Kyvento bereits vorhanden sein. Legen Sie diese vorab an – über die Oberfläche oder über POST /api/v1/products und POST /api/v1/coupons.
Ein Export Ihres bisherigen Systems, in dem jeder Datensatz eine eindeutige und dauerhafte Kennung besitzt. Diese Kennung benötigen Sie für die Wiederholbarkeit des Imports.

Reihenfolge der Übernahme

Übernehmen Sie die Daten in der folgenden Reihenfolge, da jeder Schritt auf den IDs des vorangegangenen Schritts aufbaut. Basisadresse aller Endpunkte ist https://api.kyvento.com/v1.

Schritt	Datenart	Endpunkt
1	Kunden	`POST /api/v1/customers`
2	Abonnements dieser Kunden	`POST /api/v1/subscriptions`
3	Bereits abgeschlossene und offene Rechnungen	`POST /api/v1/invoices` und anschließend `POST /api/v1/invoices/{invoice}/finalize`
4	Zahlungen zu diesen Rechnungen	`POST /api/v1/invoices/{invoice}/record-payment`

Schritt 1: Kunden anlegen

Beginnen Sie mit den Stammdaten. Zwei Besonderheiten sind dabei zu beachten:

customer_type ist ein Pflichtfeld und muss den Wert business (Unternehmen) oder individual (Privatperson) enthalten. Davon hängt unter anderem die steuerliche Behandlung ab.
Die Adressfelder werden flach übergeben. Ein verschachteltes Adress-Objekt ist nicht vorgesehen; Straße, Hausnummer, Postleitzahl, Ort und Land stehen unmittelbar auf oberster Ebene.

POST /api/v1/customers
Authorization: Bearer 42|aBcDe…
Content-Type: application/json

{
  "customer_type": "business",
  "company_name": "Nordwind Software GmbH",
  "email": "buchhaltung@nordwind-software.example",
  "vat_id": "DE347829165",
  "street": "Musterstraße",
  "house_number": "12",
  "postal_code": "20095",
  "city": "Hamburg",
  "country": "DE"
}

Vorsicht bei abweichenden Feldnamen: Felder, die der Endpunkt nicht kennt, werden ohne Fehlermeldung verworfen. Ein verschachtelt übergebenes Adress-Objekt führt daher zu einem Kunden ohne Anschrift. Wir empfehlen, den ersten übernommenen Datensatz in der Oberfläche zu prüfen, bevor Sie den gesamten Bestand übertragen.

Schritt 2: Abonnements anlegen

Legen Sie anschließend die laufenden Verträge über POST /api/v1/subscriptions an – mit der Kunden-ID aus Schritt 1 und dem zuvor eingerichteten Produkt. Übernehmen Sie dabei den ursprünglichen Vertragsbeginn und den nächsten Abrechnungstermin aus Ihrem bisherigen System, damit die erste Rechnung aus Kyvento nahtlos an die letzte Rechnung des Vorsystems anschließt.

Schritt 3: Rechnungen anlegen und finalisieren

Rechnungen übernehmen Sie über POST /api/v1/invoices. Zwei Besonderheiten sind dabei maßgeblich:

Rechnungen benötigen Positionen

Die übergebenen Summenfelder gelten ausschließlich für den Entwurf. Bei der Finalisierung ermittelt Kyvento den Rechnungsbetrag neu aus den Positionen (items). Eine Rechnung ohne Positionen weist daher einen Betrag von 0,00 € aus und nimmt anschließend keine Zahlung mehr an. Übergeben Sie mindestens eine Position:

POST /api/v1/invoices
Authorization: Bearer 42|aBcDe…
Content-Type: application/json

{
  "customer_id": 42,
  "items": [
    {
      "description": "Wartung 07/2026 (Vorsystem)",
      "quantity": 1,
      "unit_price": 100.00,
      "tax_rate": 19
    }
  ]
}

Finalisierung vor der Zahlungserfassung

POST /api/v1/invoices erzeugt zunächst einen Entwurf. Zu einem Beleg wird dieser erst durch POST /api/v1/invoices/{invoice}/finalize. Die Erfassung einer Zahlung auf einen Entwurf wird abgewiesen; finalisieren Sie die Rechnung daher vor Schritt 4.

Schritt 4: Zahlungen erfassen

Rechnungen, die in Ihrem bisherigen System bereits beglichen wurden, erhalten ihre Zahlung über POST /api/v1/invoices/{invoice}/record-payment. Dieser Endpunkt dokumentiert eine bereits erfolgte Zahlung und löst keinen Zahlungsvorgang aus.

Unterschied zwischen record-payment und collect: Während record-payment eine bereits erfolgte Zahlung dokumentiert, löst POST /api/v1/invoices/{invoice}/collect einen tatsächlichen Zahlungseinzug aus. Bei der Übernahme bereits beglichener Rechnungen käme es dadurch zu einer erneuten Belastung Ihrer Kunden. Für die Datenübernahme ist ausschließlich record-payment vorgesehen.

Wiederholbarkeit über den Idempotency-Key

Ein Importlauf kann aus technischen Gründen abbrechen, etwa durch eine unterbrochene Verbindung. Alle vier Endpunkte unterstützen daher den Header Idempotency-Key (eine UUID v4). Kyvento speichert den übergebenen Schlüssel: Trifft derselbe Schlüssel erneut ein, erhalten Sie die ursprüngliche Antwort zurück, ohne dass ein zweiter Datensatz entsteht.

Damit dieser Schutz bei einem erneuten Lauf greift, muss der Schlüssel aus dem Quelldatensatz abgeleitet werden und bei jedem Durchlauf identisch sein – beispielsweise als UUID v5 über eine Zeichenkette der Form vorsystem:kunde:4711. Ein je Versuch neu erzeugter Zufallsschlüssel hebt die Wirkung auf und führt beim zweiten Lauf zu doppelten Datensätzen.

POST /api/v1/customers
Authorization: Bearer 42|aBcDe…
Idempotency-Key: 8c4f1e2a-5d7b-5f3c-9a1e-6b2d4c8e0f37
Content-Type: application/json

Umsatzsteuer-Identifikationsnummern

Eine übergebene vat_id wird nach der Anlage gegen das EU-Portal VIES geprüft, nicht währenddessen. Der Kunde wird in jedem Fall angelegt und erhält einen Prüfstatus, den Sie später abfragen können. Wir empfehlen, den Import nicht bis zum Vorliegen des Prüfergebnisses anzuhalten, da die Verfügbarkeit von VIES außerhalb unseres Einflussbereichs liegt. Übernehmen Sie zunächst den vollständigen Bestand und werten Sie die Prüfstatus im Anschluss aus.

Anfragelimits

Für die Datenübernahme gelten dieselben Limits pro Minute wie für die übrige API-Nutzung Ihres Tarifs. Werten Sie den Header X-RateLimit-Remaining aus und richten Sie sich bei einer Antwort mit dem Status 429 nach der im Header Retry-After angegebenen Wartezeit; eine fest hinterlegte Wartezeit führt entweder zu weiteren Fehlversuchen oder zu unnötiger Verzögerung. Weitere Hinweise finden Sie im Artikel API-Rate-Limits und Best Practices.

Erfolgskontrolle

Probelauf mit einem Datensatz: Übernehmen Sie zunächst einen einzelnen Kunden mit einem Abonnement, einer Rechnung und einer Zahlung.
Prüfung in der Oberfläche: Sind Anschrift und Umsatzsteuer-Identifikationsnummer des Kunden vollständig? Weist die Rechnung den erwarteten Betrag aus? Ist sie als bezahlt gekennzeichnet?
Prüfung der Wiederholbarkeit: Lassen Sie denselben Datensatz ein zweites Mal durch Ihr Skript laufen. Entsteht dabei ein Duplikat, sind die Idempotency-Keys nicht stabil abgeleitet und sollten vor der vollständigen Übernahme angepasst werden.
Vollständige Übernahme und Abgleich: Vergleichen Sie abschließend die Anzahl der Kunden, Abonnements und offenen Posten mit Ihrem bisherigen System.

Wenn es nicht klappt

Rechnung weist 0,00 € aus: Es wurden keine Positionen (items) übergeben. Legen Sie die Rechnung mit Positionen erneut an; eine nachträgliche Korrektur des Betrags ist nicht vorgesehen.
Zahlung wird abgewiesen: Die Rechnung befindet sich noch im Entwurfsstatus. Rufen Sie zunächst finalize auf.
Kunde ohne Anschrift: Die Adressfelder wurden verschachtelt übergeben und dabei verworfen. Verwenden Sie die flachen Feldnamen aus Schritt 1.
Status 401 oder 403: Das Token fehlt, ist abgelaufen oder verfügt nicht über die erforderliche Berechtigung (customers:full, subscriptions:full, invoices:full).
Status 429: Das Anfragelimit ist erreicht. Setzen Sie die Übernahme nach der in Retry-After angegebenen Wartezeit fort.
Doppelte Datensätze nach einem erneuten Lauf: Die Idempotency-Keys werden je Versuch neu erzeugt. Leiten Sie diese stattdessen aus der Kennung des Quelldatensatzes ab.

Umfangreiche Datenübernahmen

Umfangreiche oder komplexe Datenübernahmen müssen Sie nicht selbst durchführen. Datenimporte und -migrationen bieten wir als kostenpflichtige Zusatzleistung an; die Beauftragung erfolgt vorab über eine individuelle Vereinbarung zu Leistungsinhalt und Umfang.

Wenden Sie sich hierzu an support@kyvento.com und teilen Sie uns mit, aus welchem System Sie wechseln und welcher Datenumfang zu übernehmen ist. Sie erhalten daraufhin ein Angebot mit den anfallenden Kosten.

Nächste Schritte

Zugang und Berechtigungen einrichten – siehe API-Zugang einrichten und API-Key erstellen
Endpunkte, Felder und Beispielaufrufe im Detail – siehe API-Dokumentation und Beispiele
Anfragelimits berücksichtigen – siehe API-Rate-Limits und Best Practices
Nach der Übernahme über Ereignisse informiert bleiben – siehe Webhooks konfigurieren

← Zurück zum Support