## API URL Adresa URL používaná k odesílání požadavků HTTP: ```url https://portal.bulkgate.com/api/1.0/integration/transactional-bulk ``` > [!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`. ```http POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > Je **přísně zakázáno** využívat [transakční SMS](https://www.bulkgate.com/cs/centrum-napovedy/obecne-informace/rozdil-propagacni-transakcni-sms/) pro propagační/marketingové účely. Musí být použita pouze pro oznamovací účely - jako SMS oznámení. > [!NOTE] > Pokud chcete transakční routu použít k zasílání hromadných transkačních zpráv, obraťte se na [naši podporu.](https://www.bulkgate.com/cs/kontakt/) Tuto možnost můžeme z dobrých důvodů povolit. > [!WARNING] > Zprávu obdrží i příjemci, kteří se z odběru odhlásili (odhlášení odběru platí pouze pro promoční zprávy). > ### Tabulka s parametry | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:------------------|:------------------------------------------------|:-------:|:-------------------------------:| | application_id | [ID aplikace](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) | **Ano** | - | | application_token | [Ověřovací token aplikace](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-tokeny/) | **Ano** | - | | tag | Osobní identifikační značka | Ne | - | | messages | Pole zpráv | **Ano** | [Objekt zprávy](#objekt-zpravy) | ### Objekt zprávy | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:-------------------------------------------------:| | primary_channel | Primární kanál, který bude použit jako první v kaskádě | Ne | `sms` | | phone_number | Telefonní číslo příjemnce | **Ano** | - | | country | Poskytněte čísla příjemců v mezinárodním formátu (s prefixem, např. `420`) nebo přidejte [kód země](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Podívejte se na příklad požadavku země. Pokud je hodnota **`null,`** poté se použije vaše nastavená časová zóna pro doplnění informace | Ne | `null` | | schedule | Naplánujte čas a datum odesílání v [unixovém čase.](https://cs.wikipedia.org/wiki/Unixov%C3%BD_%C4%8Das) Podívejte se na níže uvedené příklady. | Ne | `null` | | channels | Asociativní pole objektů kanálů | **Ano** | [Objekt kanálu](#tabulka-parametru-viber-objektu) | ### Tabulka parametrů Viber objektu | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:-----------------|:----------------------------------------------------------------------------------------------------------------------------|:---------:|:----------------:| | sender | Jméno odesilatele | Ne | - | | expiration | Čas po kterém zprávě vyprší platnost | Ne | `3600` | | text | Text zprávy. Je možné doplnit proměnné do šablony z pole `variables` (další parametr) `Hello ....` | **Ano** | - | | variables | Asociativní pole pro doplnění proměnných do textu např: `{"first_name": "John", "last_name": "Doe"}` | Ne | `[]` | ### Tabulka parametrů SMS objektu | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:---------------:| | sender_id | ID odesílatele, viz [typ ID odesílatele](#typ-id-odesilatele-sender-id) | 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 | `''` | | unicode | `Yes`/`true`/`1` pro Unicode SMS, `no`/`false`/`0` pro 7bit SMS | Ne | `false` | | text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. Je možné doplnit proměnné do šablony z pole `variables` (další parametr) `Hello ....` | **Ano** | - | | variables | Asociativní pole pro doplnění proměnných do textu např: `{"first_name": "John", "last_name": "Doe"}` | Ne | `[]` | #### Typ ID odesílatele `sender_id` | HODNOTA | POPIS | |:-----------|:------------------------------------------------------------------------| | `gSystem` | Systémové číslo | | `gShort` | Short Code | | `gText` | Textový odesílatel | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/cs/centrum-napovedy/mobile-connect/instalace-aplikace-mobile-connect/) | | `gPush` | Mobile Connect push - Odešle notifikaci do vaší Mobile Connect aplikace | | `gOwn` | Vlastní číslo (vyžaduje ověření čísla) | | `gProfile` | [ID profilu odesílatele](https://www.bulkgate.com/cs/centrum-napovedy/sms/profil-odesilatele/) | | `` | ID profilu odesílatele | **Příklad úplného požadavku:** ```http-json POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## Odpověď na tento příkaz může být: **V případě úspěchu** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **V případě chyby:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "detail": null } ``` Kde: - **type** a **error** popis chyby nalezente v [tabulce typů chyb](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) - **code** představuje http chyba - **detail** je dodatečná informace o chybě Všechny typy chyb pro Simple API a Advanced API můžete najít [zde.](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/)