Odeslání One Time Password (OTP)

API URL

Adresa URL používaná k odeslání požadavků HTTP:

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

Poznámka

Nedostane-li se požadavek k cíli, zopakujte ho na záložním serveru backup1.bulkgate.com.

Podporované HTTP metody

POST - application/json

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

Důležité

Endpoint má nad rámec request_quota_number ještě celkový limit 60 požadavků za minutu na účet. Po jeho překročení vrátí the_quota_of_send_per_minute_has_been_exceeded.

Tabulka s parametry

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
application_id	Application ID	Ano	-
application_token	Application token	Ano	-
number	Telefonní číslo, na které bude kód odeslán	Ano	-
country	Kód země daného telefonního čísla	ne	Hodnota je brána z profilu.
language	Jazyk textu zprávy, jeden ze 100 podporovaných ISO kódů. Neznámý kód požadavek odmítne.	ne	`null`
code_type	Typ odeslaného kódu (`string`, `int`, or `combined`)	ne	`int`
code_length	Délka verifikačního kódu (4-100)	ne	6
request_quota_number	Počet požadavků za minutu pro identifikaci `request_quota_identification`	ne	1
request_quota_identification	Identifikace "uživatele/žadatele OTP", na kterého se bude uplatňovat kvóta `request_quota_number` za minutu. Doporučujeme pro tuto identifikaci používat IP adresu.	Ano	-
trials_available_resend	Limit počtu přeposlání	ne	`null` - neomezené
trials_available_verification	Limit počtu oveření	ne	`null` - neomezené
daily_limit	Limit počtu požadavků za den. (Počítá počet požadavků za posledních 24 hodin a postupně se posouvá)	ne	`null` - neomezené
daily_limit_country	Denní limit pro jednotlivé země jako mapa `{"cz": 100, "sk": 50}`. Je-li vyplněná, jsou povolené jen uvedené země — na ostatní požadavek skončí chybou `country_is_disabled`.	ne	`null`
expiration	Expirace OTP požadavku v sekundách, po uplynutí této doby není možné ověřit požadavek. Hodnota nižší než `60` se ignoruje a použije se výchozí.	ne	`604800` - 7 dní
channel	Alternativní kanály. Kanály jsou seřazeny v kaskádě, pokud tedy není možné doručit zprávu skrze prioritní kanál, budou použity kanály níže v kaskádě. Pokud ani jeden z alternativních kanálu nedokáže doručit zprávu bude použita SMS.	ne	SMS, Viber, RCS, WhatsApp nebo Text2Voice

Kanály

Objekt channel určuje, kterými kanály se kód odešle a v jakém pořadí. Pořadí klíčů v requestu je pořadím kaskády — nedoručí-li kód prioritní kanál, zkusí se další v pořadí. Nedoručí-li ho žádný, použije se SMS.

SMS objekt

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
sender_id	ID odesílatele, viz sender ID type	ne	`gSystem`
sender_id_value	Hodnota odesílatele - `gOwn` (např. "420 777 777 777"), `gText` (např. "BulkGate"), `gProfile` (např. "423"), `gMobile` or `gPush` (KEY)	ne	`null`
domain	URL webu, který používá WebOTP pro automatické vyplnění přijatého kódu.	ne	`null`

Viber objekt

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
sender	Váš zaregistrovaný odesilatel pro Viber	Ano	-
expiration	Doba v sekundách po které bude zpráva odeslána dalším kanálem v pořadí v případě nedoručení.	ne	60
code_type	Typ kódu podle požadavků Viberu, uvádí se na schválené OTP šabloně.	ne	`null`
code_reason	Důvod odeslání kódu podle požadavků Viberu.	ne	`null`
business_name	Název firmy, který se objeví ve zprávě.	ne	`null`

RCS objekt

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
sender	Textový odesílatel pro RCS. Musí být nejdříve registrován — pro registraci kontaktujte podporu.	Ano	-
expiration	Doba v sekundách po které bude zpráva odeslána dalším kanálem v pořadí v případě nedoručení.	ne	60
use_card	Odešle kód jako kartu místo prostého textu.	ne	`false`

WhatsApp objekt

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
sender	Váš zaregistrovaný odesílatel pro WhatsApp	Ano	-
template	Název schválené WhatsApp šablony, kterou se kód odešle.	Ne	`verification_code`
language	Jazyk šablony. Bez něj se použije `language` z požadavku.	Ne	`null`
expiration	Doba v sekundách, po které bude zpráva odeslána dalším kanálem v pořadí v případě nedoručení. Min. `60`.	Ne	`180`

Text2Voice objekt

Kód se přečte hlasem. Zprávu lze zopakovat, aby ji příjemce stihl zapsat.

JMÉNO PARAMETRU	HODNOTA	POVINNÉ	VÝCHOZÍ HODNOTA
sender	Vaše zaregistrované číslo volajícího.	Ano	-
language	Jazyk hlasu, jeden ze 47 podporovaných ISO kódů. Bez něj se použije `language` z požadavku.	Ne	`null`
prefer_gender	Preferovaný hlas - `male` nebo `female`.	Ne	`male`
safety_statement	Přidá na začátek hovoru bezpečnostní upozornění.	Ne	`true`
repeat	Kolikrát se kód v hovoru zopakuje.	Ne	`1`
expiration	Doba v sekundách, po které bude zpráva odeslána dalším kanálem v pořadí v případě nedoručení. Min. `60`.	Ne	`180`

Příklad požadavku

POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "420777777777", "country": "cz", "language": "cs", "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, "expiration": 3600, "channel": { "viber": { "sender": "Lt. Hagan", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Lt-Hagan", "unicode": true } } }

Odpověď

V případě úspěchu:

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

V případě chyby:

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

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

Kde:

type a error (popis chyby) najdete v tabulce typů chyb
code je HTTP kód chyby
detail je doplňující informace o chybě

Typy chyb OTP API

Vedle obecných typů vrací OTP API vlastní:

TYP	KDY NASTANE
`the_quota_of_send_per_minute_has_been_exceeded`	Vyčerpaná kvóta odeslání za minutu.
`the_quota_of_one_additional_resend_per_minute_has_been_exceeded`	Přeposlání dřív než 60 s od předchozího.
`the_quota_of_one_additional_resend_has_been_exceeded`	Vyčerpaný `trials_available_resend`.
`the_quota_of_one_additional_verification_has_been_exceeded`	Vyčerpaný `trials_available_verification`.
`daily_limit_reached`	Vyčerpaný `daily_limit`.
`country_is_disabled`	Země čísla není v `daily_limit_country`.
`country_daily_limit_exceeded`	Vyčerpaný denní limit pro danou zemi.
`invalid_phone_number`	Číslo se nepodařilo rozpoznat.
`invalid_code`	Ověřovaný kód nesouhlasí.
`unknown_channel`	V kaskádě je kanál, který OTP API nezná.
`request_can_not_be_created`	Požadavek se nepodařilo založit.

Byla tato stránka užitečná?

Zeptat se AI Zkopírováno