> [!CAUTION] > Je ***prísne zakázané*** zneužívať [transakčné SMS](https://www.bulkgate.com/sk/centrum-pomoci/vseobecne-informacie/rozdiel-propagacna-transakcna-sprava/) na propagačné/marketingové účely. Smú sa používať len na notifikačné účely – ako SMS notifikácie. > [!NOTE] > Ak by ste chceli použiť transakčnú routu na odoslanie hromadnej notifikačnej správy, obráťte sa, prosím, na [našu podporu](https://www.bulkgate.com/sk/kontakt/). Na základe oprávneného dôvodu vám túto možnosť môžeme povoliť. ## API URL Adresa URL, na ktorú sa posielajú požiadavky HTTP: ```url https://portal.bulkgate.com/api/2.0/advanced/transactional ``` > [!NOTE] > Ak sa požiadavka nedostane do cieľa, 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/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tabuľka s parametrami | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------------------:|:-------------------------:| | application_id | [Identifikátor aplikácie](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) | **Áno** | - | | application_token | [Overovací token aplikácie](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/) | **Áno** | - | | number | Číslo príjemcu alebo pole čísel príjemcov – [Hodnota number](#hodnota-number) | **Áno** alebo `admin` | - | | admin | Číslo notifikačného admina BulkGate. [Viac tu](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-transactional-posielanie-notifikacnych-sprav-administratorom/) | **Áno** alebo `number` | - | | text | Text SMS správy (max. 612 znakov alebo 268 znakov, ak je aktivovaný Unicode), kódovanie UTF-8. Do šablóny je možné doplniť premenné z poľa `variables` (ďalší parameter) `Hello ....` | **Áno** | - | | variables | Asociatívne pole na doplnenie premenných do textu, napr.: `{"first_name": "John", "last_name": "Doe"}` | Nie | `[]` | | channel | Alternatívne kanály. Kanály sa skúšajú v kaskáde v poradí, v akom ich v objekte uvediete – ak sa správu nepodarí doručiť prvým kanálom, použije sa ďalší v poradí. SMS sa na koniec kaskády **nepridáva** automaticky; ak ju chcete ako poslednú záchranu, uveďte v kaskáde objekt `sms`. Keď nie je zadaný žiadny kanál, správa sa odošle ako SMS. | Nie | [SMS objekt](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-sms/) | | country | Zadajte čísla príjemcov v medzinárodnom formáte (s predvoľbou, napr. `420`) alebo pridajte [kód krajiny vo formáte ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420777777777`). Pozrite si príklad požiadavky s krajinou. Ak je hodnota **`null`**, použije sa krajina z vášho používateľského profilu. | Nie | `null` | | schedule | Naplánujte čas a dátum odoslania v [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) alebo [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Nie | Teraz | | duplicates_check | Zvoľte možnosť **`on`**, ak chcete zabrániť odosielaniu duplicitných správ na rovnaké telefónne číslo. Správy s rovnakým textom odoslané na rovnaké číslo sa odstránia, ak je časový odstup kratší ako 5 minút. Ak je aktívna možnosť **`off`**, žiadne duplicity sa neodstránia. | Nie | `off` | | tag | Označenie správ na ich neskoršie dohľadanie používateľom. | Nie | - | ### Hodnota `number` Hodnotu `number` je možné zapísať takto: - Pole telefónnych čísel ```json [ "420777777777", "420888888888", "420999999999" ] ``` ## Kanály Objekt `channel` určuje, ktorými kanálmi sa správa odošle a v akom poradí. **Poradie kľúčov v requeste je poradím kaskády** a SMS sa do nej nepridáva automaticky – pozrite [Kaskáda kanálov](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-kaskada/). | KĽÚČ | OBJEKT KANÁLA | |:-------------|:-----------------------------------------------------------------| | `sms` | [SMS](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-sms/) | | `viber` | [Viber – transakčný](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-viber-transakcne/) | | `rcs` | [RCS](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-rcs/) | | `whatsapp` | [WhatsApp](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-whatsapp/) | ## Príklad požiadavky ```http-json POST /api/2.0/advanced/transactional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": ["777777777", "777777778"], "text": "example text ", "variables": {"first_name": "John"}, "country": "cz", "schedule": "2023-08-14T18:30:00-01:00", "channel": { "whatsapp": { "sender": "420777777777", "expiration": 300, "message": { "text": "text" } }, "rcs": { "sender": "BulkGate", "expiration": 300, "message": { "text": "text" } }, "viber": { "sender": "BulkGate", "expiration": 100 }, "sms": { "sender_id": "gText", "sender_id_value": "Mr. Sender", "unicode": true } } } ``` ## Odpoveď **V prípade úspechu:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0, "duplicity_message": 0 } }, "response": [ { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-0", "part_id": [ "transactional-64afe5f28ffc2-0" ], "number": "420777777777", "channel": "viber" }, { "status": "scheduled", "message_id": "transactional-64afe5f28ffc2-1", "part_id": [ "transactional-64afe5f28ffc2-1" ], "number": "420777777778", "channel": "viber" } ] } } ``` Kde: - **part_ID** je pole ID častí pôvodnej dlhej správy, ktorá bola rozdelená, pretože prekročila limit 160 znakov pre jednu správu. Viac [tu](https://www.bulkgate.com/sk/centrum-pomoci/sms/zretazenie-sprav/). **V prípade chyby:** ```json { "type": "invalid_phone_number", "code": 400, "error": "Invalid phone number", "detail": null } ``` ```json { "type": "unknown_identity", "code": 401, "error": "Unknown identity / unauthorized / empty application_id", "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** predstavuje HTTP chybu - **detail** je doplňujúca informácia o chybe Všetky typy chýb pre Simple API a Advanced API nájdete [tu](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/).