Connector-API v1
Der Connector überträgt Spielserver-Vorgänge per signierten HTTPS-Anfragen an das MDT. Er liest oder schreibt keine MDT-Datenbanktabellen.
#Transport und Signatur
Die Basisadresse kommt aus der freigegebenen Integration. Der Pfad lautet /api/connector/v1/; alle Endpunkte verwenden POST und Content-Type: application/json, UTF-8, höchstens 32 KB Rumpf.
| Kopf | Inhalt |
|---|---|
X-HS-Integration | Öffentliche Integrationskennung |
X-HS-Zeit | Aktuelle Sendezeit, Unix-Sekunden; höchstens 300 Sekunden Abweichung |
X-HS-Schluessel | UUID v4 je fachlichem Vorgang |
X-HS-Signatur | v1= plus hexadezimale HMAC-SHA256-Signatur |
Die bestehenden Kopfbezeichnungen sind technische Kompatibilitätsnamen und werden nicht umbenannt.
v1\nPOST\n<pfad>\n<sendezeit>\n<uuid>\n<sha256-des-exakten-rumpfs>Die kanonische Zeichenkette enthält echte Zeilenumbrüche, keinen abschließenden Umbruch und den Pfad ohne Host oder Query. Das Geheimnis wird als UTF-8-Zeichenkette für HMAC verwendet; nicht eigenständig Base64-dekodieren.
#Beispiel für die Signaturbildung
Das Beispiel sendet keine Anfrage. integrationSecret wird ausschließlich serverseitig aus der geschützten Konfiguration geladen.
import { createHash, createHmac, randomUUID } from 'node:crypto';
const path = '/api/connector/v1/ping';
const body = '{}';
const sentAt = String(Math.floor(Date.now() / 1000));
const key = randomUUID();
const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');
const canonical = ['v1', 'POST', path, sentAt, key, bodyHash].join('\n');
const signature = 'v1=' + createHmac('sha256', integrationSecret)
.update(canonical, 'utf8').digest('hex');Beim Versand dieselben body-Bytes verwenden. Bei Wiederholung Rumpf und Idempotenzschlüssel beibehalten, Sendezeit und Signatur erneuern.
#Dokumentierte Endpunkte
| Endpunkt | Rumpf und Zweck |
|---|---|
ping | {}; Kontakt, Mandant, Umgebung und Version; höchstens alle fünf Minuten |
identitaet/verknuepfen | identifier, code, optional charakter; Profilcode einlösen |
identitaet/abfragen | identifier; aktive Mitgliedschaften des Integrationsmandanten |
dienst/melden | identifier, behoerde, aktion (an/ab), optional zeitpunkt, ort |
dienst/stand | behoerde; Dienstnummern und Beginn, keine Namen |
sitzung/ticket | identifier, behoerde; einmaliger Schnelllogin, 60 Sekunden gültig |
druck/offen | identifier, behoerde, drucker; sichtbare abholbereite Aufträge |
druck/ausgeben | Zusätzlich auftrag, pruefcode; idempotente Ausgabe |
Druck benötigt das aktive Druckmodul. Ist es inaktiv, liefern die Endpunkte 404 unbekannt.
Synthetisches Beispiel einer Dienstmeldung:
{"identifier":"license:synthetischer-testwert","behoerde":"polizei-test","aktion":"an"}Kennungen beim Test durch gültige synthetische Fixtures ersetzen. Namen, Token und vollständige Nutzlasten nicht protokollieren.
#Antworten und Fehler
{"ok":true,"daten":{}}{"ok":false,"fehler":{"code":"nicht_verknuepft","text":"Keine Verknüpfung vorhanden."}}| HTTP / Code | Behandlung |
|---|---|
400 format, 422 feld | Eingabe korrigieren; fehler.feld auswerten |
401 signatur, 401 integration | Integration und Signatur prüfen; nicht blind wiederholen |
401 zeit | Uhr korrigieren; Dienstmeldung im Puffer behalten |
403 | Verknüpfung, Sperren, Recht oder Modul prüfen |
404 | Behörden-/Druckerkennung und API-Version prüfen |
409 schluessel_konflikt | Gleicher Schlüssel, anderer Rumpf; nicht wiederholen |
409 in_arbeit | Retry-After: 2 beachten |
423 pausiert | Dienstmeldung puffern; interaktiv verständlich abbrechen |
423 umgebung | Zielumgebung korrigieren |
429 | Retry-After beachten, Parallelaufrufe begrenzen |
503 | Wartung; kontrolliert wiederholen |
#Idempotenz, Puffer und Limits
Gleicher Schlüssel und Rumpf liefern innerhalb von 24 Stunden die gespeicherte Antwort mit X-HS-Wiederholt: 1. Dienstereignisse werden in Reihenfolge mit ursprünglichem zeitpunkt gepuffert; Pufferalter höchstens 23 Stunden. Der Zeitkopf bleibt die aktuelle Sendezeit.
Bei Netzfehlern, 429, 502, 503, 504: 2, 5, 15 und 60 Sekunden, danach fünf Minuten warten. Andere 4xx außer 408, 425, 429 nicht automatisch erneut senden; die dokumentierten Sonderfälle in_arbeit, pausiert und zeit beachten.
Interaktive Identitäts-, Ticket- und Druckaufrufe niemals dauerhaft puffern. Nur im Speicher nach 2 und 5 Sekunden wiederholen, dann Spieler informieren. Tickets: höchstens zehn pro Kennung in fünf Minuten. Ein globales numerisches API-Limit ist nicht angegeben.
#Geplant für v1.1
sync/jobs, sync/fahrzeuge, ereignisse/abholen und platzierungen/stand sind im Vertrag als v1.1 geplant gekennzeichnet. Nicht aufrufen und keine produktive Bedienung dafür anbieten. Steuerungsendpunkte zur Rechtspublikation gehören zu einem anderen Vertrag.
#Wer darf das?
Entwickler implementieren den Transport serverseitig. Systemleitung richtet die Integration ein; das MDT prüft jede Fachberechtigung unabhängig vom Spielserver.
Unklare Stellen oder fehlende Schritte meldest du im LexoNET-Discord oder als Ticket im Kundenbereich.