Einmalpasswort (OTP) senden

API-URL

URL, an die HTTP-Anfragen gesendet werden:

https://portal.bulkgate.com/api/1.0/otp/send

Hinweis

Wenn die Anfrage ihr Ziel nicht erreicht, wiederholen Sie sie auf dem Backup-Server backup1.bulkgate.com.

Unterstützte HTTP-Methoden

POST - application/json

POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json

Wichtig

Zusätzlich zu request_quota_number gilt für den Endpunkt ein kontoweites Limit von 60 Anfragen pro Minute. Bei Überschreitung wird the_quota_of_send_per_minute_has_been_exceeded zurückgegeben.

Parametertabelle

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
application_id	Anwendungs-ID	Ja	-
application_token	Anwendungstoken	Ja	-
number	Telefonnummer, an die der Verifizierungscode gesendet wird	Ja	-
country	Ländercode der Telefonnummer	nein	Der Wert wird aus dem Profil übernommen.
language	Sprache des Nachrichtentextes, einer der 100 unterstützten ISO-Codes. Ein unbekannter Code führt zur Ablehnung der Anfrage. Ohne Angabe wird die Sprache anhand der Telefonnummer ermittelt.	nein	`null`
code_type	Typ des Codes. (`string`, `int` oder `combined`)	nein	`int`
code_length	Länge des Verifizierungscodes (4–100).	nein	6
request_quota_number	Anzahl der Anfragen pro Minute für `request_quota_identification`	nein	1
request_quota_identification	Identifikation des „OTP-Nutzers / Anfragenden“, für den das Kontingent `request_quota_number` pro Minute gilt. Wir empfehlen, dafür eine IP-Adresse zu verwenden.	Ja	-
trials_available_resend	Limit der verfügbaren erneuten Sendungen	nein	`null` - unbegrenzt
trials_available_verification	Limit der verfügbaren Verifizierungen	nein	`null` - unbegrenzt
daily_limit	Limit der verfügbaren Anfragen pro Tag (gleitend über die letzten 24 Stunden)	nein	`null` - unbegrenzt
daily_limit_country	Tageslimit pro Land als Map `{"cz": 100, "sk": 50}`. Ist es ausgefüllt, sind nur die aufgeführten Länder erlaubt — jedes andere Land schlägt mit `country_is_disabled` fehl.	nein	`null` - unbegrenzt
expiration	Ablaufzeit der OTP-Anfrage in Sekunden; nach Ablauf dieser Zeit ist die Anfrage nicht mehr möglich. Ein Wert unter `60` wird ignoriert und der Standardwert verwendet.	nein	`604800` - 7 Tage
channel	Alternative Kanäle. Die Kanäle sind in einer Kaskade angeordnet: Kann Ihre Nachricht nicht über den Kanal mit der höchsten Priorität zugestellt werden, werden die weiter unten in der Kaskade aufgeführten Kanäle verwendet. Gelingt die Zustellung über keinen von ihnen, wird stattdessen SMS verwendet.	nein	SMS, Viber, RCS, WhatsApp oder Text2Voice

Kanäle

Das Objekt channel legt fest, über welche Kanäle der Code zugestellt wird und in welcher Reihenfolge. Die Reihenfolge der Schlüssel in der Anfrage ist die Reihenfolge der Kaskade — kann der erste Kanal den Code nicht zustellen, wird der nächste versucht. Gelingt es keinem von ihnen, wird SMS verwendet.

SMS-Objekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender_id	Absenderkennung, siehe Typ der Absenderkennung	nein	`gSystem`
sender_id_value	Wert des Absenders - `gOwn` (z. B. „420 777 777 777“), `gText` (z. B. „BulkGate“), `gProfile` (z. B. „423“), `gMobile` oder `gPush` (KEY)	nein	`null`
domain	URL einer Website, die WebOTP für die automatische Eingabe des empfangenen Codes nutzt.	nein	`null`

Viber-Objekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Name Ihres registrierten Absenders für Viber	Ja	-
expiration	Sekunden, die gewartet wird, bevor ein anderer Kanal versucht wird	nein	60
code_type	Von Viber verlangter Codetyp, angegeben in der genehmigten OTP-Vorlage.	nein	`null`
code_reason	Grund für das Senden des Codes, von Viber verlangt.	nein	`null`
business_name	In der Nachricht angezeigter Firmenname.	nein	`null`

RCS-Objekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Textabsender für RCS. Er muss zuerst registriert werden — wenden Sie sich zur Registrierung an unseren Support.	Ja	-
expiration	Sekunden, die gewartet wird, bevor ein anderer Kanal versucht wird	nein	60
use_card	Sendet den Code als Karte statt als reinen Text.	nein	`false`

WhatsApp-Objekt

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Ihr registrierter WhatsApp-Absender	Ja	-
template	Name der genehmigten WhatsApp-Vorlage, über die der Code zugestellt wird.	Nein	`verification_code`
language	Sprache der Vorlage. Ohne Angabe wird `language` aus der Anfrage verwendet.	Nein	`null`
expiration	Sekunden, die gewartet wird, bevor ein anderer Kanal der Kaskade versucht wird. Minimum `60`.	Nein	`180`

Text2Voice-Objekt

Der Code wird vorgelesen. Die Nachricht kann wiederholt werden, damit der Empfänger ihn notieren kann.

PARAMETERNAME	WERT	PFLICHT	STANDARDWERT
sender	Ihre registrierte Anrufernummer.	Ja	-
language	Sprache der Stimme, einer der 47 unterstützten ISO-Codes. Ohne Angabe wird `language` aus der Anfrage verwendet.	Nein	`null`
prefer_gender	Bevorzugte Stimme - `male` oder `female`.	Nein	`male`
safety_statement	Stellt dem Anruf einen Sicherheitshinweis voran.	Nein	`true`
repeat	Wie oft der Code während des Anrufs wiederholt wird.	Nein	`1`
expiration	Sekunden, die gewartet wird, bevor ein anderer Kanal der Kaskade versucht wird. Minimum `60`.	Nein	`180`

Beispielanfrage

{ "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "420777777777", "country": "de", "language": "de", "code_type": "string", "code_length": 7, "request_quota_number": 1, "request_quota_identification": "127.0.0.1", "trials_available_resend": 2, "trials_available_verification": 5, "daily_limit": 100, "daily_limit_country": {"cz": 150, "sk": 50}, "expiration": 3600, "channel": { "rcs": { "sender": "Lt. Hagan", "expiration": 100 }, "viber": { "sender": "Lt. Hagan", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true } } }

Antwort

Bei Erfolg:

{ "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } }

Bei einem Fehler:

{ "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null }

{ "type": "invalid_input_parameters", "code": 400, "error": "Invalid input parameters", "detail": null }

Dabei gilt:

type und error (Beschreibung des Fehlers) finden Sie in der Tabelle der Fehlertypen
code steht für den HTTP-Fehler
detail enthält zusätzliche Informationen zum Fehler

Fehlertypen der OTP API

Zusätzlich zu den allgemeinen Typen gibt die OTP API eigene Typen zurück:

TYP	WANN ER AUFTRITT
`the_quota_of_send_per_minute_has_been_exceeded`	Das Sendekontingent pro Minute ist ausgeschöpft.
`the_quota_of_one_additional_resend_per_minute_has_been_exceeded`	Erneutes Senden früher als 60 s nach dem vorherigen.
`the_quota_of_one_additional_resend_has_been_exceeded`	`trials_available_resend` ist ausgeschöpft.
`the_quota_of_one_additional_verification_has_been_exceeded`	`trials_available_verification` ist ausgeschöpft.
`daily_limit_reached`	`daily_limit` ist ausgeschöpft.
`country_is_disabled`	Das Land der Nummer ist in `daily_limit_country` nicht aufgeführt.
`country_daily_limit_exceeded`	Das Tageslimit für dieses Land ist ausgeschöpft.
`invalid_phone_number`	Die Nummer konnte nicht erkannt werden.
`invalid_code`	Der verifizierte Code stimmt nicht überein.
`unknown_channel`	Die Kaskade enthält einen Kanal, den die OTP API nicht kennt.
`request_can_not_be_created`	Die Anfrage konnte nicht erstellt werden.

War diese Seite hilfreich?

KI fragen Kopiert