Externe Lernanwendungen können einen Freischaltcode zunächst prüfen und danach seine Nutzung für eine Person registrieren. ALKM übernimmt dabei nicht die Anmeldung der Person in Ihrer Anwendung.
Voraussetzungen sind ein für die Anbindung bereitgestellter API-Schlüssel, ein passender Testcode und eine stabile Benutzerkennung aus Ihrem System. Halten Sie den Schlüssel auf dem Server. Der Browser des Endnutzers darf ihn nicht erhalten.
1. Code prüfen
Setzen Sie die Basisadresse und den API-Schlüssel wie im Einstieg. Die folgenden Werte sind Platzhalter:
export ALKM_CODE='BEISPIEL-CODE'
export ALKM_EXTERNAL_USER='test-user-001'
curl --silent --show-error --include \
-H "x-api-key: $ALKM_API_KEY" \
-H "x-user-id: $ALKM_EXTERNAL_USER" \
"$ALKM_BASE_URL/licence/key/validate/$ALKM_CODE"
Die Benutzerkennung muss für dieselbe Person bei späteren Aufrufen exakt gleich bleiben. Nutzen Sie keine E-Mail-Adresse als technische Kennung, wenn sie sich ändern kann. Ihre Anwendung muss sicherstellen, dass ein angemeldeter Nutzer nicht die Kennung einer anderen Person übermittelt.
Die Kennung muss außerdem über alle Anwendungen hinweg kollisionsfrei sein, die dieselben Codes verwenden können. ALKM ergänzt keinen Anwendungspräfix und nimmt den API-Schlüssel nicht in die Benutzeridentität auf. Vereinbaren Sie einen stabilen Namensraum wie lernapp-a:user-123, statt in zwei unabhängigen Anwendungen jeweils nur 123 für verschiedene Personen zu verwenden.
Bei Erfolg liefert ALKM code: 1 und ein licence-Objekt. Gekürztes, fiktives Beispiel:
{
"code": 1,
"message": "OK",
"licence": {
"token": "BEISPIEL-CODE",
"ISBN": "DEMO-ISBN",
"title": "Testinhalt",
"validfrom": "2026-10-01",
"validto": "2027-10-01",
"expires": "2027-10-15",
"totalstudents": 1
}
}
Prüfen Sie anschließend, ob Ihre Anwendung das zugeordnete Produkt tatsächlich bereitstellen kann. Die Produktzuordnung, etwa über ISBN, muss mit dem Anbieter vereinbart sein. Unbekannte Produkte dürfen nicht allein wegen code: 1 freigeschaltet werden.
validate reserviert keinen Platz. Sein Erfolg garantiert deshalb nicht, dass ein späteres enroll ebenfalls erfolgreich ist. Ein zurückgegebenes Ablaufdatum kann bei bislang nicht aktivierten Codes berechnet sein; die Prüfung allein speichert keine Einlösung.
2. Einlösung registrieren
Erst nach erfolgreicher Produktprüfung rufen Sie mit derselben Benutzerkennung auf:
curl --silent --show-error --include \
-H "x-api-key: $ALKM_API_KEY" \
-H "x-user-id: $ALKM_EXTERNAL_USER" \
"$ALKM_BASE_URL/licence/key/enroll/$ALKM_CODE"
Dieser GET-Aufruf schreibt Daten. Er gehört nicht in einen normalen Link, einen Browser-Prefetch oder eine Überwachung, die URLs automatisch aufruft. Verwenden Sie ihn gezielt serverseitig; lassen Sie solche Antworten nicht von einem gemeinsamen Cache bedienen.
Prüfen Sie HTTP-Status und JSON erneut. Erst bei code: 1 gewähren Sie Zugriff nach den vereinbarten Lizenzregeln. ALKM registriert die Aktivierung, erzeugt über diesen Endpunkt aber keine Lizenz im Edupool-Buchregal.
Datumsprüfung und Fehler
enroll prüft das Einlöseende validto und das Ablaufdatum expires. validate mit gesetzter Benutzerkennung prüft dagegen das Ablaufdatum, aber nicht validto. Ohne Benutzerkennung prüft validate beide Enddaten. Verwenden Sie die Varianten nicht austauschbar.
Beide Wege prüfen außerdem den Gültigkeitsbeginn, die verfügbare Nutzerzahl und gesperrte Kennungen. Datumswerte sind YYYY-MM-DD; die Endprüfung erfolgt gegen Mitternacht UTC, nicht gegen das Ende des angegebenen Tages.
Typische fachliche Fehler kommen mit HTTP 200:
code |
Bedeutung |
|---|---|
-1 |
Code ungültig oder Benutzer gesperrt |
-2 |
Lizenz beziehungsweise Einlösefenster abgelaufen |
-3 |
Keine freien Nutzerplätze |
-103 |
Noch nicht gültig |
Leiten Sie aus einer einmal erfolgreichen Prüfung kein dauerhaftes Zugriffsrecht ab. Vereinbaren Sie, wann die Anwendung erneut validiert. Warenkorb-Codes sind für diese Endpunkte nicht geeignet; ihre Auflösung erfolgt über die Kontoaktivierung.
Zugang einrichten: Einstieg in die ALKM-API. Kontoaktivierung statt externer Einlösung: Konten und Buchregal per API verwalten. Fehlerbehebung: ALKM-Antworten und fehlgeschlagene Aufrufe.