## API URL Adresa URL používaná na odosielanie HTTP požiadaviek: ```url https://portal.bulkgate.com/api/1.0/otp/send ``` > [!NOTE] > Ak sa požiadavka nedostane k cieľu, zopakujte ju na [záložnom serveri](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/zalozny-server/) `backup1.bulkgate.com`. ## Podporované HTTP metódy - `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` 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](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) | **Áno** | - | | application_token | [Application token](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/) | **Á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í](https://www.bulkgate.com/sk/dokumentacia/otp-api/preposlanie-jednorazoveho-hesla/) | nie | `null` - neobmedzené | | trials_available_verification | Limit počtu [overení](https://www.bulkgate.com/sk/dokumentacia/otp-api/overenie-jednorazoveho-hesla/) | 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](#sms-objekt), [Viber](#viber-objekt), [RCS](#rcs-objekt), [WhatsApp](#whatsapp-objekt) alebo [Text2Voice](#text2voice-objekt) | ## 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](https://www.bulkgate.com/sk/dokumentacia/simple-api/simple-transactional/) | nie | `gSystem` | | sender_id_value | Hodnota odosielateľa - `gOwn` (napr. „420 777 777 777“), `gText` (napr. „BulkGate“), `gProfile` (napr. „423“), `gMobile` alebo `gPush` [(KEY)](https://www.bulkgate.com/sk/centrum-pomoci/mobile-connect/instalacia-aplikacie-mobile-connect/) | nie | `null` | | domain | URL webu, ktorý používa [WebOTP](https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API) na automatické vyplnenie prijatého kódu. | nie | `null` | ### Viber objekt | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:----------------|:---------------------------------------------------------------------------------------------|:--------|:----------------| | sender | Váš zaregistrovaný [odosielateľ pre Viber](https://www.bulkgate.com/sk/centrum-pomoci/viber/registracia-viber-odosielatela/) | **Á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](https://www.bulkgate.com/sk/kontakt/). | **Á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](https://www.bulkgate.com/sk/centrum-pomoci/whatsapp/registracia-whatsapp-odosielatela/) | **Á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 ```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": "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:** ```json { "data": { "id": "otp-65cca8b4b6a6a2.24308291", "message": { "status": "accepted", "message_id": "cascade-xjyjzh7thor3", "part_id": [ "cascade-xjyjzh7thor3" ], "number": "420777777777", "channel": "whatsapp" } } } ``` **V prípade 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) nájdete v [tabuľke typov chýb](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/) - **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](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/) 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ť. |