## API URL Adresa URL používaná k odeslání požadavků HTTP: ```url https://portal.bulkgate.com/api/1.0/otp/send ``` > [!NOTE] > Nedostane-li se požadavek k cíli, zopakujte ho na [záložním serveru](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/zalozni-server/) `backup1.bulkgate.com`. ## Podporované HTTP metody - `POST` - `application/json` ```http POST /api/1.0/otp/send HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!IMPORTANT] > 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](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) | **Ano** | - | | application_token | [Application token](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-tokeny/) | **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í](https://www.bulkgate.com/cs/dokumentace/otp-api/preposlani-jednorazoveho-hesla/) | ne | `null` - neomezené | | trials_available_verification | Limit počtu [oveření](https://www.bulkgate.com/cs/dokumentace/otp-api/overeni-jednorazoveho-hesla/) | 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](#sms-objekt), [Viber](#viber-objekt), [RCS](#rcs-objekt), [WhatsApp](#whatsapp-objekt) nebo [Text2Voice](#text2voice-objekt) | ## 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](https://www.bulkgate.com/cs/dokumentace/simple-api/simple-transactional/) | ne | `gSystem` | | sender_id_value | Hodnota odesílatele - `gOwn` (např. "420 777 777 777"), `gText` (např. "BulkGate"), `gProfile` (např. "423"), `gMobile` or `gPush` [(KEY)](https://www.bulkgate.com/cs/centrum-napovedy/mobile-connect/instalace-aplikace-mobile-connect/) | ne | `null` | | domain | URL webu, který používá [WebOTP](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API) 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](https://www.bulkgate.com/cs/centrum-napovedy/viber/registrace-viber-odesilatele/) | **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](https://www.bulkgate.com/cs/kontakt/). | **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](https://www.bulkgate.com/cs/centrum-napovedy/whatsapp/registrace-whatsapp-odesilatele/) | **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 ```http-json 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:** ```json { "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } } ``` **V případě chyby:** ```json { "type": "unknown_identity", "code": 400, "error": "Unknown identity", "detail": null } ``` ```json { "type": "invalid_input_parameters", "code": 400, "error": "Invalid input parameters", "detail": null } ``` Kde: - **type** a **error** (popis chyby) najdete v [tabulce typů chyb](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) - **code** je HTTP kód chyby - **detail** je doplňující informace o chybě ### Typy chyb OTP API Vedle [obecných typů](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) 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. |