Bestätigungscodes

Der Verify-Codes-Endpunkt ermöglicht das Versenden von Einmal-Verifizierungscodes (OTP) an Telefonnummern über mehrere Zustellungskanäle. Er unterstützt eine mehrstufige Routing-Strategie mit automatischem Fallback — wenn ein Kanal fehlschlägt oder eine Zeitüberschreitung auftritt, wird automatisch der nächste Kanal versucht.

• Erstellen einer Verifizierungscode-Anfrage mit flexibler Routing-Strategie
• Unterstützung für Telegram-, Sprach- (Text-to-Speech)- und SMS-Zustellungskanäle
• Automatischer Fallback zwischen Kanälen bei Fehler oder Zeitüberschreitung
• Abrufen von Verifizierungscode-Status, Zustellungsverlauf und Kosteninformationen
• Löschen von Verifizierungscodes aus dem Speicher nach der Zustellung aus Sicherheitsgründen

Funktionsweise

Beim Erstellen einer Verifizierungscode-Anfrage definieren Sie eine Routing-Strategie — eine geordnete Liste von Zustellungskanälen. Das System verarbeitet jeden Kanal in der angegebenen Reihenfolge:

1. Sendet den Verifizierungscode über den ersten Kanal (z.B. Telegram).
2. Telegram: wartet auf eine Zustellungsbestätigung von der Telegram-API innerhalb von timeout_sec. Sprache: führt einen Anrufversuch durch; Erfolg, wenn der Empfänger abnimmt. SMS: gilt als erfolgreich, sobald die Nachricht vom Mobilfunknetz akzeptiert wurde.
3. Wenn der Kanal fehlschlägt oder eine Zeitüberschreitung auftritt, wird automatisch auf den nächsten Kanal zurückgegriffen.
4. Wiederholt, bis ein Kanal erfolgreich ist oder alle Kanäle erschöpft sind.

Routing-Strategie

Jeder Schritt in der Routing-Strategie gibt einen channel und optionale Parameter an. Alle Parameter außer channel sind optional — es werden sinnvolle Standardwerte verwendet.

Kanal	Parameter	Erfolgs-Kriterium	Hinweise
telegram	timeout_sec	Zustellungsbestätigung von Telegram innerhalb von timeout_sec erhalten	timeout_sec: min 30, max 3600, Standard 30.
voice	sender_id, template	Empfänger hat das Telefonat angenommen	Text-to-Speech-Anruf. Es wird nur ein Anrufversuch unternommen. Die Vorlage wird automatisch in SSML <speak>-Tags eingebettet.
sms	sender_id, template	SMS wurde vom Netzwerk zur Zustellung akzeptiert	Standard-SMS-Zustellung. Kann nur der letzte Schritt in der Routing-Strategie sein.

Regeln:

• Mindestens ein Kanal ist erforderlich.
• Doppelte Kanäle sind nicht erlaubt.
• Der sms-Kanal kann nur der letzte Schritt sein (kein Fallback nach SMS).
• Der Parameter timeout_sec ist nur für den telegram-Kanal anwendbar.

Kostenoptimierung

Die Gesamtkosten einer Verifizierungscode-Anfrage ergeben sich aus der Summe aller gesendeten Nachrichten über alle Kanäle, die versucht wurden — auch wenn einige Kanäle fehlgeschlagen sind. Jeder Kanalversuch verursacht Kosten pro Nachricht.

Empfehlung: Ordnen Sie Ihre Routing-Strategie vom günstigsten zum teuersten Kanal. Platzieren Sie beispielsweise telegram zuerst (niedrigste Kosten), dann voice und sms zuletzt. Wenn der günstigere Kanal erfolgreich ist, vermeiden Sie die Kosten für die teureren.

Blockierung und Filterung

Vor dem Zustellversuch prüft das System die Telefonnummer des Empfängers gegen Ihre Konto-Einschränkungen:

• Blockierte Telefonnummern: Wenn sich die Empfängernummer in Ihrer Liste blockierter Nummern befindet, wird die Nachricht nicht gesendet.
• SMS-Filter: Wenn die Empfängernummer auf einen Ihrer SMS-Filter zutrifft, wird die Nachricht nicht gesendet.

Wenn eine Nachricht durch einen Filter oder eine blockierte Nummer blockiert wird, erhalten der Kanalschritt und die gesamte Aufgabe den Status 20 (Fehlgeschlagen). Ein Fallback auf den nächsten Kanal wird in diesem Fall nicht versucht.

Verifizierungscode

Der Verifizierungscode ist eine numerische Zeichenfolge (4–8 Ziffern), die an den Empfänger gesendet wird:

• Benutzerdefinierter Code: Geben Sie Ihren eigenen Code über die Eigenschaft code an (4–8 Zeichen).
• Automatisch generiert: Wenn code nicht angegeben ist, wird ein zufälliger numerischer Code generiert. Steuern Sie die Länge mit code_length (Standard: 4, Bereich: 4–8).

Verwenden Sie die Eigenschaft template pro Kanal, um den Nachrichtentext anzupassen. Der Platzhalter {{code}} wird durch den tatsächlichen Verifizierungscode ersetzt. Wenn keine Vorlage angegeben ist, wird eine standardmäßige übersetzte Nachricht basierend auf dem Feld lang verwendet.

Sicherheit: Code nach dem Versand löschen

Setzen Sie is_code_deleted auf true, um den Verifizierungscode nach dem Versand an den Empfänger automatisch aus dem LOX24-Speicher zu löschen. Dies stellt sicher, dass der Code nach der Zustellung nicht in der Datenbank verbleibt.

WICHTIG: Wenn is_code_deleted aktiv ist, fehlt das Feld code in nachfolgenden GET-Antworten, nachdem die Aufgabe abgeschlossen ist.

Statuscodes

Sowohl die gesamte Aufgabe als auch jeder einzelne Kanal verwenden dieselben Statuswerte, aber die Semantik unterscheidet sich:

Aufgabenstatus (status auf oberster Ebene):

Status	Bedeutung
0	Neu — Anfrage erstellt, noch nicht verarbeitet
5	In Bearbeitung — Zustellung läuft
10	Erfolg — Code über mindestens einen Kanal erfolgreich zugestellt
20	Fehlgeschlagen — Zustellung über alle Kanäle fehlgeschlagen
100	Fehler — Systemfehler

Kanalstatus (history[].status):

Status	Bedeutung
0	Neu — Kanalschritt erstellt, noch nicht verarbeitet
5	In Bearbeitung — Versand über diesen Kanal
10	Erfolg — Zustellung über diesen Kanal bestätigt
20	Fehlgeschlagen — Zustellung über diesen Kanal fehlgeschlagen
100	Fehler — Systemfehler auf diesem Kanal

Webhook-Benachrichtigungen

Verifizierungscode-Ereignisse können an Ihren Webhook-Endpunkt gesendet werden. Folgende Ereignisse sind verfügbar:

• verify_code.success — Code wurde erfolgreich zugestellt
• verify_code.failed — Zustellung über alle Kanäle fehlgeschlagen
• verify_code.channel.sent — Code über einen bestimmten Kanal versendet
• verify_code.channel.success — Kanal hat erfolgreiche Zustellung bestätigt
• verify_code.channel.failed — Kanal konnte nicht zustellen
• verify_code.channel.updated — Kanalstatus aktualisiert

Weitere Informationen zur Konfiguration von Webhook-Endpunkten finden Sie im Abschnitt Webhook-Benachrichtigungen.