Dokumentation
Anleitung

Ersten Freischaltcode per API erzeugen

Produkt auswählen, einen Einzelcode erzeugen und das Ergebnis prüfen.

Auf dieser Seite

Diese Anleitung erzeugt einen Freischaltcode für eine Person. Sie benötigen einen Manager-Schlüssel, die bestätigte Testadresse und ein für Ihren Zugang freigegebenes Testprodukt. Setzen Sie ALKM_BASE_URL und ALKM_API_KEY wie im Einstieg beschrieben.

1. Produktnummer ermitteln

curl --silent --show-error --include \
  -H "x-api-key: $ALKM_API_KEY" \
  "$ALKM_BASE_URL/licence/manage/signatures"

Die Antwort ist ein JSON-Array mit Produktnummern, beispielsweise:

["DEMO-PRODUKT-1","DEMO-PRODUKT-2"]

Die Werte hier sind Platzhalter. Verwenden Sie eine Nummer aus Ihrer tatsächlichen Antwort. Bei Reseller-Zugängen ist die Liste auf freigegebene Produkte eingeschränkt.

2. Einen Code erzeugen

Ersetzen Sie die Produktnummer und passen Sie das Einlösefenster an. Das Beispiel verwendet die Antares-Plattform 0; prüfen Sie vorher die Plattformliste Ihres Zugangs.

curl --silent --show-error --include \
  -H "x-api-key: $ALKM_API_KEY" \
  -H 'Content-Type: application/json' \
  "$ALKM_BASE_URL/licence/manage/keys/create" \
  --data-binary @- <<'JSON'
{
  "content_identifier": "DEMO-PRODUKT-1",
  "internal_order_number": "TEST-BESTELLUNG-001",
  "system": 0,
  "totalstudents": 1,
  "validfrom": "2026-10-01",
  "validto": "2027-10-01",
  "duration": 365,
  "amount": 1
}
JSON

Der Body ist ein einzelnes Objekt. Ein Array würde zusätzlich einen Warenkorb-Code anfordern.

Feld Bedeutung im Beispiel
content_identifier Produktnummer als String, auch wenn sie nur Ziffern enthält
internal_order_number Eigene Zuordnung zur Bestellung; verhindert keine Duplikate
system Zielplattform; nicht system_id senden
totalstudents Nutzerplätze pro Code
validfrom, validto Beginn und Ende des Einlösefensters
duration Laufzeit in Tagen; nicht mit dem Einlösefenster verwechseln
amount Anzahl zu erzeugender Codes

Verwenden Sie positive Werte für amount, Laufzeit und Nutzerplätze. validto ist kein Versprechen einer Gültigkeit bis zum Tagesende. Für Abläufe an einer Datumsgrenze müssen Zeitzone und Aktivierungsweg vorab abgestimmt werden.

3. Ergebnis kontrollieren und speichern

Eine erfolgreiche Antwort enthält die erzeugten Codes unter licences. Gekürztes, fiktives Beispiel:

{
  "code": 1,
  "message": "OK",
  "licences": [{
    "token": "BEISPIEL-CODE",
    "content_identifier": "DEMO-PRODUKT-1",
    "system_id": 0,
    "totalstudents": 1,
    "duration": 365
  }],
  "xlsx_download": "",
  "lti": {"consumer_key":"","consumer_secret":""}
}

Prüfen Sie code, Anzahl und Produktnummern der zurückgegebenen Datensätze. Speichern Sie den token zusammen mit Ihrer Bestellzuordnung. Die Codes ermöglichen eine Einlösung und sollten entsprechend geschützt werden.

code: 1 garantiert nicht, dass die gewünschte Menge geliefert wurde: Nicht freigegebene Reseller-Produkte können herausgefiltert werden. Bei vorgenerierten Codes kann der Vorrat kleiner sein als die bestellte Menge. Eine leere Liste oder licences: null ist deshalb kein erfolgreich erfüllter Auftrag.

Häufige Fehler vermeiden

  • content_identifier und ISBN sind unterschiedliche Felder. Für Antares kann ISBN entfallen; externe Zielsysteme können sie zur Produktzuordnung benötigen.
  • expires und entry_date werden bei diesem Aufruf nicht als Eingabe unterstützt. Sie gehören zu den Ergebnisdaten.
  • totalstudents und totalteachers nicht gleichzeitig positiv setzen. Für einen Lehrercode verwenden Sie den vorgesehenen Lehrertyp und dessen Plattformkonfiguration.
  • Nach Timeout oder HTTP 500 zuerst klären, ob Codes angelegt wurden. Ein erneuter Aufruf kann weitere Codes erzeugen.

Zugang einrichten: Einstieg in die ALKM-API. Mehrere Produkte bündeln: Mehrnutzer-Codes und Warenkörbe erzeugen. Den Code für ein Konto aktivieren: Konten und Buchregal per API verwalten. Fehlerbehebung: ALKM-Antworten und fehlgeschlagene Aufrufe.