API-Dokumentation und Beispiele

Überblick

Die vollständige Referenz der Kyvento-REST-API finden Sie unter apidocs.kyvento.com – immer aktuell, denn die Dokumentation wird direkt aus dem Quellcode der API generiert und mit jedem Release automatisch aktualisiert. Dieser Artikel gibt Orientierung, was Sie dort finden und wie Sie am schnellsten zur ersten erfolgreichen Anfrage kommen.

Was die Dokumentation enthält

• Alle öffentlichen Endpunkte mit Parametern, Validierungsregeln und vollständigen Beispiel-Antworten – gruppiert nach Bereichen (Kunden, Abonnements, Rechnungen, Zahlungen, Webhooks, …).
• Beispiel-Aufrufe je Endpunkt zum direkten Übernehmen.
• Grundlagen-Kapitel zu Authentifizierung, Webhook-Ereignissen und -Signaturen, Wiederholungs-Verhalten und Pagination.
• Die maschinenlesbare OpenAPI-3-Spezifikation – damit importieren Sie die komplette API in Werkzeuge wie Postman oder Insomnia oder generieren Client-Code für Ihre Programmiersprache.

Die erste Anfrage in drei Schritten

1. Token erstellen: Einstellungen → „API-Tokens" → „+ Neuer Token" (für den Anfang genügt „Nur Lesen") – Details im Artikel „API-Zugang einrichten und API-Key erstellen".
2. Testaufruf senden: etwa die eigene Kundenliste abrufen:
   curl -H "Authorization: Bearer IHR_TOKEN" https://api.kyvento.com/v1/customers
3. Antwort prüfen: Sie erhalten JSON mit einem data-Array und einem meta-Block für die Pagination.

Konventionen der API

• Versionierung: Alle Endpunkte liegen unter https://api.kyvento.com/v1/ – Änderungen innerhalb der Version bleiben abwärtskompatibel additiv.
• Antwortformat: JSON; Listen kommen als data + meta (Seitengröße, weitere Seiten, Cursor).
• Fehler: sprechende HTTP-Statuscodes plus ein maschinenlesbarer error_code im Body – bauen Sie Ihre Fehlerbehandlung auf den error_code, nicht auf Meldungstexte.
• Sprache: Token-Antworten sind konsequent englisch – ideal für Logging und stabile Auswertungen.
• Zeitangaben: Zeitstempel im ISO-8601-Format mit Zeitzonen-Offset; reine Kalenderdaten (etwa Rechnungsdatum) als Datum ohne Uhrzeit.

Empfohlener Einstiegspfad

1. Mit Lese-Endpunkten vertraut machen (Kunden, Abos, Rechnungen abrufen).
2. Webhooks einrichten, statt Änderungen per Dauerabfrage zu suchen – siehe „Webhooks konfigurieren".
3. Erst dann schreibende Operationen angehen – mit den Hinweisen aus „API-Rate-Limits und Best Practices".

Nächste Schritte

• Zugang und Berechtigungen – siehe „API-Zugang einrichten und API-Key erstellen"
• Limits, Idempotenz und Pagination – siehe „API-Rate-Limits und Best Practices"