## API URL Adresa URL, na ktorú sa posielajú požiadavky HTTP: ```url https://portal.bulkgate.com/api/1.0/integration/promotional ``` > [!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`. ```http POST /api/1.0/integration/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ### Tabuľka s parametrami | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:------------------|:------------------------------------------------|:-------:|:-------------------------------:| | application_id | [ID 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** | - | | tag | Vlastná identifikačná značka | Nie | - | | messages | Pole správ | **Áno** | [Objekt správy](#objekt-spravy) | ### Objekt správy | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:-----------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:-------------------------------------------------:| | primary_channel | Primárny kanál, ktorý sa v kaskáde použije ako prvý | Nie | `sms` | | phone_number | Telefónne číslo príjemcu | **Áno** | - | | country | Zadajte čísla príjemcov v medzinárodnom formáte (s predvoľbou, napr. `420`) alebo pridajte [kód krajiny](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Pozrite si príklad požiadavky s krajinou. Ak je hodnota **`null`**, na doplnenie informácie sa použije vaše nastavené časové pásmo | Nie | `null` | | schedule | Naplánujte čas a dátum odoslania v [unixovom čase.](https://cs.wikipedia.org/wiki/Unixov%C3%BD_%C4%8Das) Pozrite si príklady uvedené nižšie. | Nie | `null` | | channels | Asociatívne pole objektov kanálov | **Áno** | [Objekt kanála](#tabulka-parametrov-objektu-viber) | ### Tabuľka parametrov objektu Viber | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:-----------------|:----------------------------------------------------------------------------------------------------------------------------|:---------:|:----------------:| | sender | Meno odosielateľa | Nie | - | | expiration | Čas, po ktorom platnosť správy vyprší | Nie | `3600` | | button_caption | Text tlačidla | Nie | `OK` | | button_url | URL tlačidla | Nie | `#` | | image | URL obrázka obsiahnutého v správe | Nie | `null` | | image_zoom | Či sa dá obrázok zväčšiť | Nie | `false` | | text | Text správy. 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 | `[]` | ### Tabuľka parametrov objektu SMS | NÁZOV PARAMETRA | HODNOTA | POVINNÝ | PREDVOLENÁ HODNOTA | |:----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|:---------------:| | sender_id | ID odosielateľa, pozrite [typ ID odosielateľa](#typ-id-odosielatela-sender-id) | 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 | `''` | | unicode | `Yes`/`true`/`1` pre Unicode SMS, `no`/`false`/`0` pre 7-bitové SMS | Nie | `false` | | 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 | `[]` | #### Typ ID odosielateľa `sender_id` | HODNOTA | POPIS | |:-----------|:------------------------------------------------------------------------| | `gSystem` | Systémové číslo | | `gShort` | Short Code | | `gText` | Textový odosielateľ | | `gMobile` | [Mobile Connect](https://www.bulkgate.com/sk/centrum-pomoci/mobile-connect/instalacia-aplikacie-mobile-connect/) | | `gPush` | Mobile Connect push – odošle notifikáciu do vašej aplikácie Mobile Connect | | `gOwn` | Vlastné číslo (vyžaduje overenie čísla) | | `gProfile` | [ID profilu odosielateľa](https://www.bulkgate.com/sk/centrum-pomoci/sms/profil-odosielatela/) | | `` | ID profilu odosielateľa | **Príklad úplnej požiadavky:** ```http-json POST /api/1.0/integration/promotional 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", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "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", "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "button_caption": "OK", "button_url": "#", "image": "", "image_zoom": false, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## Odpoveď na tento príkaz môže byť: **V prípade úspechu** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 2, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "accepted", "message_id": "############-0", "part_id": [ "############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "accepted", "message_id": "############-1", "part_id": [ "############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **V prípade 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) 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/).