Odoslanie One Time Password (OTP)

API URL

Adresa URL používaná na odosielanie HTTP požiadaviek:

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

Poznámka

Ak sa požiadavka nedostane k cieľu, zopakujte ju na záložnom serveri backup1.bulkgate.com.

Podporované HTTP metódy

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 ešte celkový limit 60 požiadaviek za minútu na účet. Po jeho prekročení vráti the_quota_of_send_per_minute_has_been_exceeded.

Tabuľka s parametrami

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
application_id	Application ID	Áno	-
application_token	Application token	Áno	-
number	Telefónne číslo, na ktoré sa kód odošle	Áno	-
country	Kód krajiny daného telefónneho čísla	nie	Hodnota sa preberá z profilu.
language	Jazyk textu správy, jeden zo 100 podporovaných ISO kódov. Neznámy kód požiadavku zamietne.	nie	`null`
code_type	Typ odoslaného kódu (`string`, `int` alebo `combined`)	nie	`int`
code_length	Dĺžka overovacieho kódu (4-100)	nie	6
request_quota_number	Počet požiadaviek za minútu pre identifikáciu `request_quota_identification`	nie	1
request_quota_identification	Identifikácia „používateľa/žiadateľa OTP“, na ktorého sa bude uplatňovať kvóta `request_quota_number` za minútu. Na túto identifikáciu odporúčame používať IP adresu.	Áno	-
trials_available_resend	Limit počtu preposlaní	nie	`null` - neobmedzené
trials_available_verification	Limit počtu overení	nie	`null` - neobmedzené
daily_limit	Limit počtu požiadaviek za deň. (Počíta počet požiadaviek za posledných 24 hodín a priebežne sa posúva)	nie	`null` - neobmedzené
daily_limit_country	Denný limit pre jednotlivé krajiny ako mapa `{"sk": 100, "cz": 50}`. Ak je vyplnený, sú povolené len uvedené krajiny — na ostatné požiadavka skončí chybou `country_is_disabled`.	nie	`null`
expiration	Expirácia OTP požiadavky v sekundách, po uplynutí tohto času už požiadavku nie je možné overiť. Hodnota nižšia ako `60` sa ignoruje a použije sa predvolená.	nie	`604800` - 7 dní
channel	Alternatívne kanály. Kanály sú zoradené v kaskáde, takže ak nie je možné doručiť správu cez prioritný kanál, použijú sa kanály nižšie v kaskáde. Ak správu nedokáže doručiť ani jeden z alternatívnych kanálov, použije sa SMS.	nie	SMS, Viber, RCS, WhatsApp alebo Text2Voice

Kanály

Objekt channel určuje, ktorými kanálmi sa kód odošle a v akom poradí. Poradie kľúčov v požiadavke je poradím kaskády — ak kód nedoručí prioritný kanál, skúsi sa ďalší v poradí. Ak ho nedoručí žiadny, použije sa SMS.

SMS objekt

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
sender_id	ID odosielateľa, pozrite typ odosielateľa	nie	`gSystem`
sender_id_value	Hodnota odosielateľa - `gOwn` (napr. „420 777 777 777“), `gText` (napr. „BulkGate“), `gProfile` (napr. „423“), `gMobile` alebo `gPush` (KEY)	nie	`null`
domain	URL webu, ktorý používa WebOTP na automatické vyplnenie prijatého kódu.	nie	`null`

Viber objekt

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
sender	Váš zaregistrovaný odosielateľ pre Viber	Áno	-
expiration	Čas v sekundách, po ktorom sa správa v prípade nedoručenia odošle ďalším kanálom v poradí.	nie	60
code_type	Typ kódu podľa požiadaviek Viberu, uvádza sa na schválenej OTP šablóne.	nie	`null`
code_reason	Dôvod odoslania kódu podľa požiadaviek Viberu.	nie	`null`
business_name	Názov firmy, ktorý sa zobrazí v správe.	nie	`null`

RCS objekt

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
sender	Textový odosielateľ pre RCS. Musí byť najprv zaregistrovaný — pre registráciu kontaktujte podporu.	Áno	-
expiration	Čas v sekundách, po ktorom sa správa v prípade nedoručenia odošle ďalším kanálom v poradí.	nie	60
use_card	Odošle kód ako kartu namiesto obyčajného textu.	nie	`false`

WhatsApp objekt

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
sender	Váš zaregistrovaný odosielateľ pre WhatsApp	Áno	-
template	Názov schválenej WhatsApp šablóny, ktorou sa kód odošle.	Nie	`verification_code`
language	Jazyk šablóny. Bez neho sa použije `language` z požiadavky.	Nie	`null`
expiration	Čas v sekundách, po ktorom sa správa v prípade nedoručenia odošle ďalším kanálom v poradí. Min. `60`.	Nie	`180`

Text2Voice objekt

Kód sa prečíta hlasom. Správu možno zopakovať, aby si ju príjemca stihol zapísať.

NÁZOV PARAMETRA	HODNOTA	POVINNÝ	PREDVOLENÁ HODNOTA
sender	Vaše zaregistrované číslo volajúceho.	Áno	-
language	Jazyk hlasu, jeden zo 47 podporovaných ISO kódov. Bez neho sa použije `language` z požiadavky.	Nie	`null`
prefer_gender	Preferovaný hlas - `male` alebo `female`.	Nie	`male`
safety_statement	Pridá na začiatok hovoru bezpečnostné upozornenie.	Nie	`true`
repeat	Koľkokrát sa kód v hovore zopakuje.	Nie	`1`
expiration	Čas v sekundách, po ktorom sa správa v prípade nedoručenia odošle ďalším kanálom v poradí. Min. `60`.	Nie	`180`

Príklad požiadavky

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": "sk", "language": "sk", "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 } } }

Odpoveď

V prípade úspechu:

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

V prípade 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) nájdete v tabuľke typov chýb
code je HTTP kód chyby
detail je doplňujúca informácia o chybe

Typy chýb OTP API

Popri všeobecných typoch vracia OTP API vlastné:

TYP	KEDY NASTANE
`the_quota_of_send_per_minute_has_been_exceeded`	Vyčerpaná kvóta odoslaní za minútu.
`the_quota_of_one_additional_resend_per_minute_has_been_exceeded`	Preposlanie skôr než 60 s od predchádzajúceho.
`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`	Krajina čísla nie je v `daily_limit_country`.
`country_daily_limit_exceeded`	Vyčerpaný denný limit pre danú krajinu.
`invalid_phone_number`	Číslo sa nepodarilo rozpoznať.
`invalid_code`	Overovaný kód nesúhlasí.
`unknown_channel`	V kaskáde je kanál, ktorý OTP API nepozná.
`request_can_not_be_created`	Požiadavku sa nepodarilo založiť.

Bola táto stránka užitočná?

Opýtať sa AI Skopírované