Dokumentation
Referenz

ALKM-Felder und Antwortformate

Vollständige Request- und Response-Strukturen für Codes, Konten und Playout: Datentypen, Defaults, Nullwerte, optionale Felder und JSON-Beispiele.

Auf dieser Seite

Diese Referenz beschreibt die JSON-Eingaben und -Antworten für Code-Erzeugung, Kontoaufrufe und externe Codeprüfung. Die Strukturdefinitionen sind in TypeScript geschrieben; sie beschreiben die übertragenen JSON-Daten, nicht die internen Go-Typen. Die Beispiele sind fiktiv.

Konventionen für Client-Implementierungen

  • Feldnamen und Groß-/Kleinschreibung genau übernehmen: ISBN, SchoolMECcode, Requirements und die Felder in activated_users sind absichtlich nicht durchgehend kleingeschrieben.
  • feld?: T bedeutet, dass das Feld fehlen kann. feld: T | null bedeutet, dass es vorhanden ist, aber null enthalten kann. Ein leerer String "" ist weder ein fehlendes Feld noch null.
  • Integer ist eine JSON-Zahl ohne Nachkommastellen. Senden Sie beispielsweise 1, nicht "1" oder 1.5. Bei den typisierten Integer-Eingaben wird auch die Schreibweise 1.0 nicht wie eine Integer-Literalzahl akzeptiert.
  • IDs wie content_identifier, identifier und user_id sind Strings. Numerisch aussehende Produktnummern nicht in Zahlen umwandeln; führende Nullen müssen erhalten bleiben.
  • JSON-Antworten enthalten echte Zahlen, auch für 64-Bit-Felder. JavaScript kann Ganzzahlen nur bis 9.007.199.254.740.991 exakt als number darstellen. Für größere Werte einen verlustfreien JSON-Parser verwenden. Die API liefert sie nicht automatisch als Strings.
  • Datumsfelder sind Strings, keine Zeitstempel. Neben YYYY-MM-DD kommen "" und "0000-00-00" vor. Diese Sonderwerte nicht an einen normalen Datumsparser übergeben. Datumsgrenzen und Laufzeitregeln stehen in den jeweiligen Anleitungen.
  • Unbekannte Antwortfelder ignorieren, damit Ergänzungen des Servers den Client nicht brechen. Unbekannte Eingabefelder werden umgekehrt oft ignoriert; ein Schreibfehler kann deshalb ohne Fehlermeldung bleiben.
type Integer = number; // Laufzeitprüfung: ganzzahlig, nicht als String senden
type Int64 = number;   // JSON-Zahl; große Werte verlustfrei parsen
type UInt64 = number;  // JSON-Zahl, nicht negativ; große Werte verlustfrei parsen
type DateText = string; // YYYY-MM-DD; Antworten ggf. "" oder "0000-00-00"
type UserId = string;   // lokale Konten: $/csu/<Ziffern>/bk
type JsonValue = null | boolean | number | string | JsonValue[]
  | { [key: string]: JsonValue };
type JsonObject = { [key: string]: JsonValue };

Integer-Felder sind serverseitig überwiegend Go-int; dessen technische Breite hängt vom Serverbuild ab. Ein fester fachlicher Maximalwert für Mengen und Laufzeiten wird hier nicht zugesagt. Verwenden Sie kleine, positive Mengen und vereinbarte Laufzeiten, statt die technischen Integer-Grenzen auszureizen. Int64 hat den technischen Bereich −9.223.372.036.854.775.808 bis 9.223.372.036.854.775.807, UInt64 0 bis 18.446.744.073.709.551.615. Datenbank und Fachlogik können diese Bereiche weiter einschränken.

Header, Parameter und Endpunktzuordnung

Alle Aufrufe benötigen x-api-key als String. Für JSON-Bodies Content-Type: application/json senden. Management-Aufrufe mit Admin-Schlüsseln benötigen zusätzlich den vereinbarten x-vendor-String. Manager-Schlüssel enthalten den Anbieter-Kontext bereits. Berechtigungen: Einstieg in die ALKM-API.

Bei validate und enroll gehört die stabile externe Benutzerkennung in den Header x-user-id, nicht in einen JSON-Body. Der Header ist technisch nicht als Pflichtfeld erzwungen; für nutzerbezogene Integration immer setzen. Fehlende Kennungen verändern das Prüfverhalten und dürfen nicht als gemeinsamer anonymer Nutzer verwendet werden. {key} ist der URL-kodierte Freischaltcode als einzelnes Pfadsegment.

Die folgenden Typnamen werden weiter unten vollständig definiert. Fehler werden separat als ApiError ausgewertet.

Methode und Pfad Eingabe Erfolgsbody
GET /licence/manage/platforms Kein Body PlatformsResponse
GET /licence/manage/signatures Kein Body SignaturesResponse
POST /licence/manage/keys/create CreateCodeBody LicencesResponse
POST /licence/manage/keys/create/xlsx CreateCodeBody LicencesResponse
POST /licence/manage/keys/create/sxlsx CreateCodeBody LicencesResponse
POST /licence/manage/keys/create/lti CreateCodeBody LicencesResponse
POST /user/manage/create CreateUserRequest CreateUserResponse
POST /user/manage/info UserInfoRequest UserData direkt, ohne Statushülle
POST /user/manage/update UpdateUserRequest ApiSuccess
POST /user/manage/licence/activate UserLicenceRequest ApiSuccess
POST /user/manage/licence/active ActiveLicencesRequest LicencesResponse
POST /user/manage/licence/revoke UserLicenceRequest ApiSuccess
GET /licence/key/info/{key} Pfadparameter key, kein Body ValidationResponse
GET /licence/key/validate/{key} key und x-user-id, kein Body ValidationResponse
GET /licence/key/enroll/{key} key und x-user-id, kein Body ValidationResponse

enroll schreibt trotz GET-Methode Aktivierungen. info benötigt Management-Rechte und passenden Anbieter-Kontext. Es liefert Daten, prüft aber nicht die aktuelle Gültigkeit des Codes. Die Typen der XLSX-/LTI-Varianten sind hier enthalten; ihre weiterführenden Betriebsabläufe sowie CSV, Suche, Statistiken und Guthabencodes sind nicht Gegenstand dieser Referenz.

Gemeinsame Status- und Fehlerantworten

interface ApiSuccess {
  code: 1;
  message: string; // derzeit "OK"
}

interface ApiError {
  code: Integer; // bekannte Fehler: 0, -1 bis -4, -101 bis -107
  message: string;
  // Bei Fehlern wird kein licence- oder licences-Feld mitgeliefert.
}

Beispiel einer Fehlerantwort:

{"code":-2,"message":"licence expired"}

Prüfen Sie erst den HTTP-Status und bei Statushüllen zusätzlich code === 1. Eine reine Prüfung auf negative Werte ist falsch: 0 ist ebenfalls ein Fehler. ApiError.code ist absichtlich keine abgeschlossene Enum, damit ein Client neue Fehlercodes verarbeiten kann. Die Bedeutung der bekannten Codes steht in ALKM-Antworten und fehlgeschlagene Aufrufe.

Fachliche Fehler von validate und enroll können mit HTTP 200 kommen; Kontoaktivierungsfehler können HTTP 500 verwenden. Authentifizierung schlägt typischerweise mit HTTP 403 fehl. Kontoanlage mit bereits verwendeter E-Mail liefert HTTP 404 und code: -105. Netzwerkfehler oder Fehler eines vorgeschalteten Proxys müssen keinen JSON-Body haben. Nicht-JSON daher als Transport-/Protokollfehler behandeln.

Weitere endpunktspezifische Antworten:

Aufruf und Fehlerfall HTTP-Status JSON-Code und Meldung
GET /licence/key/info/{key}: Code nicht vorhanden 200 -1, invalid licence
Derselbe Aufruf: Anbieter-Kontext passt nicht 403 -106, not allowed
POST /user/manage/licence/revoke: Fehler aus der Speicherlogik, etwa unbekannter Code oder fehlende Produktberechtigung 500 0, unexpected error

Beim Kontoentzug werden diese Ursachen nicht als unterschiedliche fachliche Fehlercodes ausgegeben. Den Code 0 deshalb nicht automatisch als gefahrlos wiederholbaren technischen Fehler behandeln.

Code-Erzeugung: vollständige Eingabestruktur

interface CreateCodeRequest {
  content_identifier: string;
  amount: Integer;
  duration: Integer;
  system?: Integer;
  totalstudents?: Integer;
  totalteachers?: Integer;
  validfrom?: DateText;
  validto?: DateText;
  ISBN?: string;
  title?: string;
  internal_order_number?: string;
  restrictions?: JsonObject | null;
  number_of_transfers?: Integer;
  gp_number?: Integer;
  licence_type?: string;
  country?: string;
  state?: string;
  promo_code?: string;
  purchase_reference?: string;
  retail_order?: boolean;
  licence_policy?: Integer;
  lizinfo?: string;
  autoclaim?: boolean;
  claim_token?: string;
}

type CreateCodeBody = CreateCodeRequest | CreateCodeRequest[];

Die nicht optional markierten Felder sind die fachlichen Mindestangaben für einen sinnvollen Integrationsauftrag, keine Zusage einer vollständigen serverseitigen Pflichtfeldprüfung. Zusätzlich muss für einen normalen nutzbaren Code eine positive Anzahl in totalstudents oder totalteachers stehen. Der Server decodiert fehlende skalare Felder zunächst mit ihrem Nullwert und erzwingt diese Bedingungen nicht durchgehend.

Feld Bei Weglassen Fachliche Verwendung und Einschränkung
content_identifier "" Immer eine freigegebene Produktnummer senden
amount 0 Positive Codeanzahl senden; kein Default von 1
duration 0 Positive, vereinbarte Laufzeit in Tagen senden
system 0 Bestätigte Plattform-ID; unbekannte IDs können auf Antares-Codeerzeugung zurückfallen statt einen Fehler auszulösen
totalstudents 0 Nutzerplätze pro Code, bei Einzelnutzer 1
totalteachers 0 Alternative Lehrerplätze; bei automatischer Erzeugung werden gleichzeitig positive Schüler- und Lehrerzahlen abgelehnt
validfrom "" Gültigkeitsbeginn; für ein definiertes Fenster explizit setzen
validto intern "0000-00-00" Einlöseende; auch "" wird auf diesen Sonderwert umgesetzt
ISBN "" Produktzuordnung für das externe Zielsystem, falls dort benötigt
title "" Optionaler Titel
internal_order_number "" Eigene Bestellzuordnung, kein Idempotenzschlüssel
restrictions null Schlüssel und JSON-Werte mit dem Zielsystem vereinbaren; keine universelle Unterstruktur
number_of_transfers 0 Keine Zusage einer allgemeinen Übertragungsfunktion
gp_number 0 Optionale GP-Nummer
licence_type "" Freies Informationsfeld, keine global erzwungene Enum
country, state jeweils "" Informationsfelder; keine erzwungene ISO-Code-Prüfung
promo_code "" Optionales Informationsfeld
purchase_reference "" Zusätzliche Zuordnung, kein Idempotenzschlüssel
retail_order false Kann zusätzliche Handels-/Mailabläufe auslösen
licence_policy 0 Nur nach Abstimmung des konkreten Einlösewegs verwenden
lizinfo "" Freie Lizenzinformation
autoclaim false Automatische Einlösung nur für eingerichtete Integrationen
claim_token "" Bei autoclaim: true ein gültiges, vereinbartes signiertes Token senden; geheim halten

Bei diesen typisierten Eingaben wird null für skalare Felder beim Decodieren wie deren Nullwert behandelt. Das macht null nicht zu einer fachlich gültigen Produktnummer, Menge oder Laufzeit. Senden Sie skalare Werte im angegebenen Typ; nutzen Sie null nur dort, wo der Clienttyp es ausdrücklich vorsieht. Zahlen als Strings und falsche Objekttypen können mit invalid data abgelehnt werden. Die Datumstrings werden bei der Erzeugung nicht umfassend auf Kalendergültigkeit geprüft.

Ein einzelnes Objekt fordert eine Position an. Ein nichtleeres Array fordert zusätzlich einen gemeinsamen Warenkorb-Code an, auch bei nur einer Position. Kein leeres Array und keinen null-Body senden. Die Erstellung liest höchstens 65.536 Bytes; halten Sie Bodies deutlich darunter. Es gibt keinen zugesicherten atomaren Gesamtauftrag und keinen Schutz gegen doppelte Bestellungen.

system_id, expires, expired, entry_date, token und Aktivierungslisten sind keine unterstützten Erzeugungsparameter. Die Eingabe heißt system, die Antwort system_id. entry_date wird auf den Erstellungstag, expires zunächst auf "0000-00-00" gesetzt. Vollständiger Ablauf: Ersten Freischaltcode per API erzeugen, Warenkörbe: Mehrnutzer-Codes und Warenkörbe erzeugen.

Code-Erzeugung und aktive Liste: Antwortstruktur

interface LicencesResponse extends ApiSuccess {
  licences: Licence[] | null;
  xlsx_download: string;
  lti: LtiData;
}

interface LtiData {
  consumer_key: string;
  consumer_secret: string;
}

interface Licence {
  token: string;
  code_prefix: string;
  internal_order_number: string;
  content_identifier: string;
  ISBN: string;
  system_name: string;
  system_id: Integer;
  title: string;
  entry_date: DateText;
  validfrom: DateText;
  validto: DateText;
  expires: DateText;
  totalstudents: Integer;
  totalteachers: Integer;
  number_of_transfers: Integer;
  activation_count: Integer;
  gp_number: Integer;
  licence_type: string;
  country: string;
  state: string;
  promo_code: string;
  purchase_reference: string;
  duration: Integer;
  reference?: UInt64;
  SchoolMECcode?: Integer;
  retail_order: boolean;
  licence_policy: Integer;
  cart_number: string;
  lizinfo: string;
  billed: Integer;
  fully_billed: string;
  partner_billed: string;
  views: Int64;
  discount: string;
  reseller: string;
  claimed_by: string;
  restrictions: JsonObject | null;
  activated_user_ids: string[] | null;
  blocked_user_ids: string[] | null;
  Requirements: string | null;
}

Alle nicht mit ? markierten Felder werden im aktuellen Modell ausgegeben, auch wenn sie leer oder nullwertig sind. reference und SchoolMECcode fehlen bei numerischem Wert 0; negative Werte wie SchoolMECcode: -1 werden ausgegeben. cart_number ist im JSON ein String, außerhalb eines Warenkorbs gewöhnlich "", nicht SQL-NULL. Requirements ist ein nullable String und ausdrücklich kein strukturiertes Objekt.

token ist der einzulösende Code. content_identifier: "cart" kennzeichnet den zusätzlichen Warenkorb-Code, cart_number verbindet seine Positionen. activation_count und activated_user_ids nicht als garantierten aktuellen Belegungsstand über alle Einlösewege hinweg verwenden. Abrechnung, Reseller, Zuordnung und sonstige Informationsfelder dürfen für einen einfachen Client zunächst ignoriert werden. In restrictions können beliebige gültige JSON-Werte vorkommen; ihre fachliche Bedeutung ist zielsystemspezifisch.

licences kann null oder [] sein. Bei Reseller-Filterung und begrenztem Vorrat kann auch bei code: 1 weniger als bestellt zurückkommen. Der Client muss Menge und Produkte prüfen. Ohne XLSX-Ausgabe ist xlsx_download leer. Ohne LTI-Ausgabe ist lti trotzdem vorhanden und enthält zwei leere Strings. LTI-Geheimnisse nicht protokollieren.

XLSX: einzelne Positionen statt Warenkorbexport

Für /keys/create/xlsx und /keys/create/sxlsx einzelne Request-Objekte verwenden. Arrays werden technisch angenommen, erzeugen aber keinen gemeinsamen Gesamtexport:

  • Für jede Array-Position wird eine eigene Datei erzeugt. xlsx_download wird überschrieben und verweist am Ende nur auf die letzte Position.
  • Sobald eine Position mindestens 100 Codes liefert, wird die gesamte bis dahin angesammelte JSON-Lizenzliste geleert. Spätere Positionen können sie wieder befüllen; eine nichtleere Liste belegt daher keine Vollständigkeit.
  • Der zusätzliche Warenkorb-Code wird erst nach den Dateien erzeugt. Er steht nicht in den XLSX-Dateien, kann aber anschließend im JSON erscheinen.

Bei zwei Positionen mit je 100 Codes kann die Antwort deshalb nur den Download der zweiten Position und den Warenkorb-Code im JSON enthalten. Antwort und Download sind in diesem Fall kein vollständiges Ergebnis aller erzeugten Codes. Für Warenkörbe die einfache /keys/create-Route verwenden.

Die Downloadlinks sind für zeitnahe Verarbeitung gedacht. ALKM fordert beim Downloaddienst eine Laufzeit von 5 Minuten für /xlsx beziehungsweise 14 Tagen für /sxlsx an. Die tatsächliche Durchsetzung liegt beim Downloaddienst. Dateien rechtzeitig herunterladen und geschützt speichern; den Link nicht als dauerhafte Ablage verwenden.

Aktive Liste: Metadaten und Versionsstand

Mit der Metadatenkorrektur vom 15.10.2026 liest die aktive Liste licence_policy, lizinfo, reseller, claimed_by und Requirements aus dem gespeicherten Datensatz. SQL-NULL wird für licence_policy zu 0, für die drei Textfelder zu ""; Requirements bleibt nullable.

Vor dieser Korrektur erschienen diese Felder unabhängig vom gespeicherten Wert nur als 0, "" oder null. Vor einer Synchronisation den ausgerollten Serverstand bestätigen; alte Leerwerte dürfen keine vorhandenen Metadaten überschreiben. reference wird durch diesen Leseweg weiterhin nicht geladen und fehlt in der aktiven Liste. Es ist dort kein verlässliches Zuordnungsmerkmal.

Minimale Erfolgsantwort ohne gefundene aktive Zuordnung:

{
  "code": 1,
  "message": "OK",
  "licences": null,
  "xlsx_download": "",
  "lti": {"consumer_key":"","consumer_secret":""}
}

Vollständiger fiktiver Licence-Datensatz, einschließlich der beiden optionalen Zahlenfelder:

{
  "token": "BEISPIEL-CODE",
  "code_prefix": "admin/demo",
  "internal_order_number": "TEST-001",
  "content_identifier": "DEMO-PRODUKT-1",
  "ISBN": "",
  "system_name": "Antares",
  "system_id": 0,
  "title": "Testprodukt",
  "entry_date": "2026-10-15",
  "validfrom": "2026-10-01",
  "validto": "2027-10-01",
  "expires": "0000-00-00",
  "totalstudents": 1,
  "totalteachers": 0,
  "number_of_transfers": 0,
  "activation_count": 0,
  "gp_number": 0,
  "licence_type": "",
  "country": "",
  "state": "",
  "promo_code": "",
  "purchase_reference": "",
  "duration": 365,
  "reference": 123,
  "SchoolMECcode": -1,
  "retail_order": false,
  "licence_policy": 0,
  "cart_number": "",
  "lizinfo": "",
  "billed": 0,
  "fully_billed": "",
  "partner_billed": "",
  "views": 0,
  "discount": "",
  "reseller": "",
  "claimed_by": "",
  "restrictions": null,
  "activated_user_ids": null,
  "blocked_user_ids": null,
  "Requirements": null
}

Konten anlegen

interface CreateUserRequest {
  email: string;
  password: string;
  surname?: string | null;
  name?: string | null;
  street?: string | null;
  city?: string | null;
  institution?: boolean;
}

interface CreateUserResponse extends ApiSuccess {
  user_id: UserId;
  institution_id: Int64;
}
Feld Bei Weglassen Regel für die Integration
email "" E-Mail-Adresse des anzulegenden Kontos senden
password "" Eigenes sicheres Passwort senden; nicht protokollieren
surname, name, street, city jeweils null Optional; null und "" bleiben unterschiedliche Werte
institution false false für Einzelkonto, true für Institutionskonto

E-Mail und Passwort sind im Clienttyp fachlich erforderlich. Der API-Handler erzwingt aber keine vollständige Prüfung auf Nichtleere, E-Mail-Syntax oder Passwortstärke. Bei String-/Boolean-Feldern wird JSON-null vom Decoder wie der Nullwert behandelt; das ist keine Empfehlung, diese Werte zu senden. Für die vier nullable Textfelder sind nur Strings oder null vorgesehen. Eine eigene identifier-Vorgabe ist für die Anlage nicht vorgesehen; die ID wird erzeugt.

{"code":1,"message":"OK","user_id":"$/csu/123/bk","institution_id":456}

user_id unverändert speichern. Die Zahl institution_id ist keine Alternative zum String in späteren Kontoaufrufen. Kontoanlage kann je nach Zugang E-Mails auslösen und ist nicht als beliebig wiederholbarer Aufruf zu behandeln. Ablauf: Konten und Buchregal per API verwalten.

Kontoauskunft

type UserInfoRequest =
  | { identifier: UserId; email?: string }
  | { email: string; identifier?: UserId };

interface UserData {
  identifier: UserId;
  email: string;
  surname: string | null;
  name: string | null;
  street: string | null;
  city: string | null;
  institution: boolean;
}

Mindestens ein nichtleerer Suchwert ist erforderlich. Die lokale ID hat das Format $/csu/<Ziffern>/bk; der numerische Anteil muss als vorzeichenbehaftete 64-Bit-Zahl lesbar sein. Verwenden Sie tatsächlich zurückgegebene Konto-IDs. Bei einer normalen, nichtnulligen Konto-ID hat identifier Vorrang vor email, wenn beide gesetzt sind. Senden Sie bevorzugt genau ein Suchkriterium.

Ohne Suchwert oder ohne sichtbaren Treffer antwortet der Endpunkt mit HTTP 404 und code: -104; ein ungültiges ID-Format mit HTTP 400 und code: -4. Die Sichtbarkeit hängt von den Auskunftskontexten des Schlüssels ab.

Der Erfolgsbody enthält direkt UserData, kein code-Feld und kein Passwort:

{
  "identifier": "$/csu/123/bk",
  "email": "testkonto@example.invalid",
  "surname": "Muster",
  "name": "Alex",
  "street": null,
  "city": "",
  "institution": false
}

Kontodaten ändern

interface UpdateUserRequest {
  user_id: UserId;
  email?: string;
  surname?: string | null;
  name?: string | null;
  street?: string | null;
  city?: string | null;
}

user_id und mindestens ein änderbares Feld senden. Weggelassene Änderungsfelder bleiben unverändert. "" setzt ein Textfeld auf einen leeren String. null wird bei übergebenen Änderungsfeldern als Datenbank-NULL weitergereicht; ob die konkrete Spalte es akzeptiert, wird nicht im Handler abgesichert. Verwenden Sie null bei optionalen Textfeldern nur für einen abgestimmten Löschvorgang und prüfen Sie anschließend die Auskunft. Für die E-Mail-Adresse einen nichtleeren String senden, kein null.

Die Änderung wird als freie JSON-Map verarbeitet und nicht so streng typgeprüft wie die Kontoanlage. Die obige Struktur ist daher die empfohlene Eingabe, keine Zusage einer serverseitigen Schema-Validierung. Nicht aufgeführte Felder, insbesondere password und institution, werden nicht geändert. Ein Aufruf ohne Änderungsfelder ist kein zugesicherter No-op.

Erfolg ist ApiSuccess. Der Aufruf prüft nicht, ob tatsächlich eine Zeile geändert wurde. Eine unpassende ID oder Reseller-Anlagekennung kann somit code: 1 ohne Änderung ergeben. Immer über info nachlesen.

Kontoaktivierung, aktive Liste und Kontoentzug

interface UserLicenceRequest {
  user_id: UserId;
  activation_code: string;
}

interface ActiveLicencesRequest {
  user_id: UserId;
}

Beide Felder von UserLicenceRequest sind fachlich erforderlich und dürfen nicht leer sein. activation_code ist der token aus der Codeantwort, kein Produkt-Identifier. Für die aktive Liste ist user_id erforderlich. Die Handler lesen die Werte über einen permissiven JSON-Zugriff; verlassen Sie sich nicht darauf, dass falsche Typen oder fehlende Felder einheitlich als HTTP 400 abgelehnt werden. Senden Sie immer JSON-Objekte mit Strings wie oben.

Aktivierung und Kontoentzug liefern ApiSuccess oder ApiError. Die aktive Liste liefert LicencesResponse; ohne Treffer ist licences üblicherweise null. Sie listet aktive Codezuordnungen innerhalb der Berechtigungen, prüft aber nicht sämtliche zeitlichen Gültigkeitsbedingungen. Aktivierung kann Warenkorbpositionen auflösen. Kontoentzug garantiert weder globales Sperren des Codes noch spätere Wiederaktivierbarkeit.

{"user_id":"$/csu/123/bk","activation_code":"BEISPIEL-CODE"}

Code-Info, Validate und Enroll

Die Antwort dieser drei Endpunkte enthält einen reduzierten Lizenzdatensatz, nicht das vollständige Licence-Objekt. Insbesondere enthält er kein content_identifier und keine system_id. Vereinbaren Sie die Produktzuordnung für externe Systeme, beispielsweise über ISBN.

interface ValidationResponse extends ApiSuccess {
  licence: PlayoutLicence;
}

interface PlayoutLicence {
  token: string;
  title: string;
  ISBN?: string;
  validfrom?: DateText;
  validto?: DateText;
  expires?: DateText;
  totalstudents?: Integer;
  totalteachers?: Integer;
  SchoolMECcode?: Integer;
  number_of_transfers?: Integer;
  activated_users?: ActivatedUser[];
}

interface ActivatedUser {
  UserID: string;
  Created: string;
  LicenceStart: string | null;
  LicenceEnd: string | null;
}

token und title werden immer ausgegeben. Die optionalen Strings fehlen bei "", die optionalen Zahlen bei 0. "0000-00-00" ist ein nichtleerer String und wird daher ausgegeben; -1 ist eine von 0 verschiedene Zahl und wird ebenfalls ausgegeben. Fehlende Zahlenfelder nicht mit einem Übertragungsfehler verwechseln.

activated_users wird nur durch info befüllt und bei leerer Liste weggelassen. validate und enroll liefern diese Liste nicht mit. Wenn die Liste vorhanden ist, enthält jeder Eintrag alle vier Felder mit exakt der gezeigten Großschreibung. Created ist ein Datenbank-Zeitstring, typischerweise YYYY-MM-DD HH:mm:ss, ohne zugesicherten UTC-Offset. LicenceStart und LicenceEnd sind Datenbank-Datumstrings oder null; keine zugehörige Kontolizenz bedeutet nicht zwingend, dass die externe Aktivierung fehlt. Diese Werte nicht ungeprüft als RFC-3339-Zeitstempel parsen.

Fiktive info-Antwort:

{
  "code": 1,
  "message": "OK",
  "licence": {
    "token": "BEISPIEL-CODE",
    "title": "Testprodukt",
    "ISBN": "DEMO-ISBN",
    "validfrom": "2026-10-01",
    "validto": "2027-10-01",
    "expires": "2027-10-15",
    "totalstudents": 1,
    "activated_users": [{
      "UserID": "test-user-001",
      "Created": "2026-10-15 10:00:00",
      "LicenceStart": null,
      "LicenceEnd": null
    }]
  }
}

Bei validate und enroll hat die Antwort dieselbe Hülle, aber ohne activated_users. Bei Fehlern entfällt das gesamte licence-Feld, statt null zu enthalten. Ein von info oder validate zurückgegebenes expires kann für einen noch nicht aktivierten Code berechnet sein; es beweist keine gespeicherte Aktivierung. Prüfregeln und Einlöseablauf: Freischaltcodes in externen Anwendungen prüfen und einlösen.

Die in x-user-id übergebene Kennung muss über alle Anwendungen hinweg kollisionsfrei sein, die dieselben Codes verwenden können. ALKM ergänzt weder den API-Schlüssel noch einen Anwendungspräfix zur Kennung. Vereinbaren Sie einen stabilen Namensraum, beispielsweise lernapp-a:user-123. Zwei unabhängige Anwendungen sollten nicht jeweils nur 123 für verschiedene Personen senden.

Plattformen und Produktnummern

interface Platform {
  name: string;
  type: string;
}

type PlatformsResponse = { [id: string]: Platform } | null;
type SignaturesResponse = string[] | null;

platforms liefert ein Objekt mit numerischen Plattform-IDs als JSON-Objektschlüsseln, also Strings wie "0". Beim Senden von system die gewählte ID als Integer übergeben. type: "auto" bezeichnet automatische Erzeugung, andere konfigurierte Typen verwenden vorgenerierte Codes. Die Menge der IDs und Namen ist anbieterabhängig. Ohne konfigurierten Eintrag kann der Erfolgsbody null sein; das ist kein Anlass, fremde Plattform-IDs zu übernehmen.

signatures liefert ein Array von Produktnummern als Strings, bei leerem Ergebnis gegebenenfalls null. Es gibt keine Statushülle. Auch hier muss der Client Fehlerobjekte mit code und message sowie HTTP-Fehler getrennt behandeln.

Transportausnahme: Der Handler von platforms schreibt JSON, setzt aber keinen ausdrücklichen Content-Type: application/json. Für diesen Endpunkt den erwarteten Erfolgsbody auch unabhängig von diesem Header als JSON decodieren und strukturell prüfen. Das bedeutet nicht, dass HTML-Fehlerseiten oder andere ungültige Bodies akzeptiert werden dürfen.

{"0":{"name":"Antares","type":"auto"}}
["DEMO-PRODUKT-1","DEMO-PRODUKT-2"]

Checkliste für den Client

  1. Vor dem Senden fachlich benötigte Felder, Typen und nichtleere Werte selbst validieren.
  2. HTTP-Status und Body getrennt erfassen; erst JSON parsen, wenn ein geeigneter Body vorliegt.
  3. Bei Statushüllen nur code: 1 als Erfolg behandeln. Direkte Listen und Kontoobjekte anhand der Endpunktzuordnung decodieren.
  4. null, fehlende Felder und leere Werte nach den jeweiligen Strukturen behandeln, nicht global gleichsetzen.
  5. Nach Code-Erzeugung die tatsächlichen Produkte und Mengen prüfen; nach Kontoänderung erneut auslesen.
  6. Bei Schreibfehlern nicht blind wiederholen: Teilverarbeitung und doppelte Codes sind möglich.

Einstieg und Zugang: Einstieg in die ALKM-API. Einzelcode: Ersten Freischaltcode per API erzeugen. Warenkorb: Mehrnutzer-Codes und Warenkörbe erzeugen. Konten: Konten und Buchregal per API verwalten. Externe Anwendung: Freischaltcodes in externen Anwendungen prüfen und einlösen. Fehlercodes: ALKM-Antworten und fehlgeschlagene Aufrufe.