Vertrags-API
Mit der Vertrags-API buchst und verwaltest du deine Verträge im Kundenportal aus deinen eigenen Programmen heraus: Verträge buchen, Domains einer KI-Website setzen, Add-ons dazubuchen, kündigen, sperren und einem Projekt zuordnen. Die Vertrags-Befehle stehen Geschäftskunden zur Verfügung.
API-Key erstellen
- Melde dich im Kundenportal an und öffne Mein Konto › Anmeldung und Sicherheit.
- Erstelle auf der Karte API-Keys einen neuen Key und kopiere ihn sofort. Das Portal zeigt ihn nur dieses eine Mal.
- Jeder Benutzer hat je Kunde einen Key. Er beginnt mit deiner Kundennummer, läuft nicht ab und hat dieselben Rechte wie dein Benutzer bei diesem Kunden.
Du widerrufst deinen Key jederzeit auf derselben Karte. Der Hauptbenutzer widerruft jeden Key eures Kundenkontos. Schaltet er API-Keys in den Stammdaten aus, sind alle Keys des Kunden widerrufen.
Anfragen stellen
Alle Pfade beginnen mit dieser Basis-URL:
https://kundenportal.baebeca.de/api/v1/
- Anmeldung im Header
Authorizationmit dem WertBearer <dein API-Key> - Daten als JSON in UTF-8 (
Content-Type: application/json), Datumsangaben alsJJJJ-MM-TT, Preise als Zahl in Euro.
Ein Beispiel, das alle Verträge abruft:
curl -H "Authorization: Bearer <dein API-Key>" https://kundenportal.baebeca.de/api/v1/contracts
Was du per API erledigst
- Verträge abrufen: alle Verträge oder einen Vertrag mit dem Stand der Bereitstellung.
- Vertrag buchen: wie im Bestellformular, z. B. eine KI-Website mit Domain. Die Domain bringst du mit, registrierst sie neu (eine .de ist inklusive) oder ziehst sie mit Auth-Code um.
- Domains einer KI-Website: Domainliste setzen, fehlende DNS-Einträge abrufen und den TXT-Nachweis prüfen lassen.
- Add-ons zu einem laufenden Vertrag buchen.
- Kündigen zum Ende der laufenden Laufzeit (Add-ons zum selben Tag) und eine Kündigung vor dem Vertragsende zurücknehmen.
- Sperre eines Vertrags setzen oder aufheben.
- Projekt: einen Vertrag auf die Sammelrechnung oder ein Projekt legen.
- Aktionen an einem Vertrag ausführen, z. B. das Root-Passwort neu setzen.
Befehle laufen im Hintergrund. Die Antwort enthält den Vertrag. Solange ein Auftrag läuft, antwortet die API mit Status 202, und das Feld openJob ist gefüllt. Der Befehl ist durch, sobald openJob am Vertrag und an jedem Add-on null ist.
Alle Endpunkte mit Feldern und Beispielen stehen in der API-Doku. Sie ist ohne Anmeldung erreichbar.
Aktionen ausführen
Mit POST /api/v1/contracts/{vertrag}/actions/{aktion} führst du eine Aktion an einem Vertrag aus. Welche Aktionen ein Vertrag hat, steht im Feld actions der Antwort von GET /api/v1/contracts/{vertrag}. Aktionen sind kostenlos.
reset-password: setzt das Root-Passwort eines Linux-V-Servers oder des Servers deines KI-Studios neu. Der Server startet dafür neu. Je nach System bekommt er neue SSH-Host-Keys, dein SSH-Programm warnt dann beim nächsten Verbinden. Bei einer übernommenen VM und bei einem Server ohne Installation gibt es diese Aktion nicht.mailbox-password: setzt das Passwort eines Postfachs in Hosted Exchange neu. Danach fragen Outlook und Smartphone nach dem neuen Passwort.
Ein Beispiel:
curl -X POST -H "Authorization: Bearer <dein API-Key>" https://kundenportal.baebeca.de/api/v1/contracts/<vertrag>/actions/reset-password
Die Antwort enthält den Vertrag. Solange der Auftrag läuft, kommt sie mit Status 202, und openJob nennt Aktion und Stand. Das neue Passwort liefert die API nicht aus. Du siehst es im Kundenportal am Vertrag unter Root-Passwort anzeigen oder Postfach-Passwort anzeigen. Ein Postfach-Passwort zeigt das Portal höchstens 7 Tage lang, und nicht mehr, sobald du es selbst geändert hast.
Fehlermeldungen
Ein Fehler kommt als JSON mit error (Text), code und bei falschen Eingaben fields je Feld.
- 401: Der Key fehlt, ist ungültig oder widerrufen.
- 403: Die Aktion ist für dein Konto nicht erlaubt, z. B. Vertrags-Befehle für Privatkunden.
- 404: Der Vertrag gehört nicht zu deinem Kundenkonto, oder der Pfad ist unbekannt.
- 409: Der Vorgang passt nicht zum Stand des Vertrags, z. B. weil gerade ein Auftrag läuft, die Aktion für diesen Vertrag fehlt oder die Domain schon bei uns läuft. Warte, bis
openJobleer ist, und versuche es erneut. - 422: Eine Eingabe ist ungültig.
fieldsnennt das Feld, bei einer Domain auch die passende Art (mode). - 429: Zu viele Anfragen. Der Header
Retry-Afternennt die Sekunden bis zum nächsten Versuch. - 503: Ein angebundenes System ist gerade nicht erreichbar. Versuche es später erneut.
Grenzen
- Höchstens 120 Anfragen je Minute und Key.
- Mehr als 300 Anfragen in einer Minute oder 10 unbekannte Keys in 10 Minuten von einer IP-Adresse sperren diese IP-Adresse für 15 Minuten.
- Höchstens 200 geprüfte Domains je Stunde und Kunde.
Fragen zur API beantworten wir dir unter support@baebeca.de oder unter 02261-81616-0.