Mit der ALKM-API erstellen Sie Freischaltcodes und aktivieren Lizenzen für Konten. Diese Artikel richten sich an Entwickler von Shops, Vertriebssystemen und externen Lernanwendungen.
Den passenden Ablauf wählen
| Ziel | Schnittstelle |
|---|---|
| Codes für einen Verkauf erzeugen | POST /licence/manage/keys/create |
| Einen Code einem Edupool-Konto zuweisen | POST /user/manage/licence/activate |
| Einen Code in einer externen Anwendung prüfen | GET /licence/key/validate/{key} |
| Die Einlösung in einer externen Anwendung registrieren | GET /licence/key/enroll/{key} |
enroll erzeugt keine Lizenz im Edupool-Buchregal. Die Einlösung in der Edupool-Oberfläche ist außerdem ein anderer Ablauf als die hier beschriebenen ALKM-Aufrufe.
Zugang vorbereiten
Sie benötigen die vereinbarte API-Basisadresse und einen dafür freigeschalteten API-Schlüssel. Lassen Sie vor dem ersten Schreibzugriff eine Testumgebung und geeignete Testprodukte bestätigen. Ein Aufruf gegen die Produktivumgebung kann echte Codes und Konten erzeugen oder Lizenzen entziehen.
Für die Bash-Beispiele dieser Reihe setzen Sie:
export ALKM_BASE_URL='https://alkm-test.example.invalid'
read -r -s -p 'API-Schlüssel: ' ALKM_API_KEY
printf '\n'
export ALKM_API_KEY
Die Beispieladresse ist absichtlich nicht erreichbar. Ersetzen Sie sie durch die bestätigte Basisadresse ohne abschließenden Schrägstrich. Der Schlüssel wird verdeckt eingegeben und gehört weder in Quellcode noch in Tickets oder Screenshots. Verwenden Sie ihn nur serverseitig und ausschließlich über HTTPS.
Alle Aufrufe senden x-api-key. JSON-Anfragen senden zusätzlich Content-Type: application/json.
Berechtigungen unterscheiden
Management-Aufrufe benötigen einen Schlüssel vom Typ manager oder admin. Ein Manager-Schlüssel enthält bereits seinen Anbieter-Kontext. Bei einem Admin-Schlüssel muss für Management-Aufrufe zusätzlich der vereinbarte x-vendor-Header gesetzt werden. Die folgenden Beispiele setzen einen Manager-Schlüssel voraus.
Reseller ist eine zusätzliche Einschränkung des Schlüssels. Reseller können freigegebene Produkte abrufen und Codes erzeugen; Funktionen wie Code-Suche, CSV-Import oder globales Code-Löschen sind für sie gesperrt. Kontoauskünfte benötigen außerdem passende Auskunftsberechtigungen.
Für validate und enroll akzeptiert ALKM konfigurierte API-Schlüssel auch vom Typ reader. Der Name bedeutet hier nicht, dass alle damit erreichbaren Aufrufe nur lesen: enroll verändert den Aktivierungsstand. Guthabencodes benötigen einen Admin-Schlüssel und sind nicht Teil des Einstiegs.
Verbindung mit einem Leseaufruf prüfen
curl --silent --show-error --include \
-H "x-api-key: $ALKM_API_KEY" \
"$ALKM_BASE_URL/licence/manage/platforms"
Eine mögliche Antwort ist:
{"0":{"name":"Antares","type":"auto"}}
Die tatsächlichen IDs hängen vom Anbieter ab. auto bezeichnet automatisch erzeugte Codes. Andere konfigurierte Plattformtypen verwenden zuvor importierte Codes. Übernehmen Sie Plattform-IDs nicht aus fremden Integrationen.
Der Erfolgsbody von platforms ist JSON, der Handler setzt dafür aber keinen ausdrücklichen JSON-Content-Type. Ein Client sollte diesen bekannten Endpunkt auch ohne passenden Content-Type als JSON decodieren und die Struktur prüfen. Ungültige Bodies und HTTP-Fehler weiterhin als Fehler behandeln.
Antworten auswerten
Viele Endpunkte liefern code und message; Erfolg ist dort code: 1. Ein HTTP-Status 200 genügt nicht, denn Codeprüfungen melden auch fachliche Fehler mit HTTP 200. Einige Leseendpunkte liefern stattdessen direkt ein Array oder Objekt, etwa platforms und signatures.
Die Beispiele zeigen HTTP-Header mit --include, damit Status und JSON getrennt sichtbar sind. Für maschinelle Verarbeitung erfassen Sie HTTP-Status und Body getrennt und prüfen das jeweilige Antwortformat.
Wiederholen Sie fehlgeschlagene Schreibaufrufe nicht automatisch. Nach einem Timeout können bereits Codes oder Aktivierungen gespeichert sein. Eine Bestellnummer ist ein Suchmerkmal, kein Schutz vor doppelter Verarbeitung.
Anleitungen und Referenz
- Ersten Freischaltcode erzeugen: Ersten Freischaltcode per API erzeugen
- Mehrnutzer-Codes und Warenkörbe: Mehrnutzer-Codes und Warenkörbe erzeugen
- Konten und Buchregal verwalten: Konten und Buchregal per API verwalten
- Externe Anwendungen anbinden: Freischaltcodes in externen Anwendungen prüfen und einlösen
- Fehler erkennen und eingrenzen: ALKM-Antworten und fehlgeschlagene Aufrufe
- Feldnamen und Antwortformate nachschlagen: ALKM-Felder und Antwortformate