Ü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.

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. Alle Pfade in diesem Artikel beziehen sich auf https://app.kyvento.com – ein vollständiger Aufruf lautet also zum Beispiel https://app.kyvento.com/api/v1/customers.

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": "Moorlinden Software GmbH",
  "email": "buchhaltung@moorlinden.example",
  "vat_id": "DE347829165",
  "street": "Musterstraße",
  "house_number": "12",
  "postal_code": "20095",
  "city": "Hamburg",
  "country": "DE"
}

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. Damit die erste Rechnung aus Kyvento nahtlos an die letzte Rechnung des Vorsystems anschließt, übernehmen Sie dabei die Termine aus Ihrem bisherigen System:

• start_date (Kalendertag, YYYY-MM-DD) – der ursprüngliche Vertragsbeginn. Ein zurückliegender Tag legt das Abo als übernommenen Bestandsvertrag an, ohne Nachfakturierung der verstrichenen Zeit; ein zukünftiger Tag legt es vorgemerkt an, Zugang und Abrechnung beginnen erst dann. Ohne Angabe startet das Abo sofort.
• billing_anchor_day (1–31) – der im Altsystem etablierte Abrechnungstag im Monat. Ohne Angabe leitet Kyvento ihn aus dem Startdatum ab. Bei Produkten mit Testphase ist das Feld nicht zulässig – der Abrechnungstag entsteht dort erst mit dem Ende der Testphase.

Soll der nächste Abrechnungstermin eines bereits angelegten Abos verschoben werden, nutzen Sie POST /api/v1/subscriptions/{subscription}/reschedule-next-renewal. Das Feld next_billing_date nimmt ausschließlich ein Kalenderdatum im Format YYYY-MM-DD an; bei einem Stichtags-Anker gilt es um 0 Uhr in der Zeitzone Ihres Kontos.

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.

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 – ein frei wählbarer, eindeutiger Wert, ein bestimmtes Format wie UUID ist nicht vorgeschrieben. Kyvento merkt sich Schlüssel und Antwort für 24 Stunden: Trifft derselbe Schlüssel in dieser Zeit mit identischem Anfrage-Inhalt erneut ein, erhalten Sie die ursprüngliche Antwort zurück (Header X-Idempotency-Replayed: true), ohne dass ein zweiter Datensatz entsteht. Derselbe Schlüssel mit verändertem Inhalt wird mit 422 abgewiesen. Nach Ablauf der 24 Stunden greift der Schutz nicht mehr – einen Importlauf, der länger unterbrochen war, prüfen Sie daher vor der Wiederholung auf bereits angelegte Datensätze.

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

1. Probelauf mit einem Datensatz: Übernehmen Sie zunächst einen einzelnen Kunden mit einem Abonnement, einer Rechnung und einer Zahlung.
2. 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?
3. 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.
4. 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