API-Dokumentation und Beispiele

Überblick

Die Referenz der Kyvento-REST-API wird direkt aus dem Quellcode der API generiert. Bis zu ihrer Veröffentlichung sind die Endpunkte in diesem Artikel und in den hier verlinkten Artikeln beschrieben. Dieser Artikel gibt Orientierung, was die Referenz enthält und wie Sie am schnellsten zur ersten erfolgreichen Anfrage kommen.

Was die Referenz 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, mit der sich die komplette API in Werkzeuge wie Postman oder Insomnia importieren oder Client-Code für Ihre Programmiersprache generieren lässt.

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://app.kyvento.com/api/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://app.kyvento.com/api/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