## API URL Adresa URL používaná k odeslání požadavků HTTP: ```url https://portal.bulkgate.com/api/1.0/advanced/promotional ``` > [!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/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` ## Tabulka s parametry | NÁZEV PARAMETRU | HODNOTA | POVINNÝ | VÝCHOZÍ HODNOTA | |:------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------:|:---------------:| | application_id | [Aplikační identifikátor](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/administrace-api/) | **Ano** | - | | application_token | [Aplikační ověřovací token](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/api-tokeny/) | **Ano** | - | | number | Pole příjemců - [Hodnota number](#hodnota-number) | **Ano** nebo `admins` nebo `groups` | - | | groups | Pole čísel skupin v adresáři BulkGate. [Více zde](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-promotional-posilani-zprav-skupinam-z-adresare/) | **Ano** nebo `number` nebo `admins` | - | | admins | Pole čísel notifikačních administrátorů BulkGate. [Více zde](https://www.bulkgate.com/cs/dokumentace/advanced-api/advanced-promotional-posilani-propagacnich-zprav-administratorum/) | **Ano** nebo `number` nebo `groups` | - | | text | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování. | **Ano**, pokud je `number` zadán polem čísel nebo je použit parametr `groups` nebo `admin` | - | | unicode | `Yes`/`true`/`1` pro Unicode SMS, `no`/`false`/`0` pro 7bit SMS | Ne | `false` | | 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 | `null` | | 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 [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) nebo [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Podívejte se na níže uvedené příklady | Ne | Nyní | | duplicates_check | Zvolte možnost **`same_text`**, chcete-li zabránit odesílání duplicitních zpráv na stejné telefonní číslo. Zakažte možnost odeslat zprávu se stejným nebo jiným textem na stejné číslo s možností **`same_number`**. Pokud je aktivní **`null`**, žádné duplikáty nebudou odstraněny. Duplicity se odstraňují **jen v rámci jedné dávky**, ne napříč požadavky. | Ne | `null` | | tag | Označení zpráv pro následné dohledání uživatele | Ne | - | ### Hodnota `number` Hodnotu number lze zapsat dvěma způsoby: - Pole telefonních čísel ```json [ "420775123456", "420606123456", "44771447678" ] ``` - Asociativní pole se schématem `number`, `text` a `variables`, kde jediný povinný parametr je `number`. Pokud `number` není vyplněn zpráva se přeskočí. ```json [ {"number": "420775123456", "text": "test1 ", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 ", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ] ``` Do šablony parametru `text` je možné doplnit proměnné z pole `variables`. ### Typ ID odesílatele `sender_id` | HODNOTA | VÝZNAM | |:-----------|:------------------------------------------------------------------------| | `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` | [BulkGate Profil ID](https://www.bulkgate.com/cs/centrum-napovedy/sms/profil-odesilatele/) | | `` | BulkGate Profil ID | ## Příklady požadavků **Příklad úplného požadavku:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ {"number": "420775123456", "text": "test1 ", "variables": {"a": 5}}, {"number": "420606123456", "text": "test2 ", "variables": {"b": 5}}, {"number": "44771447678", "text": "test3 ", "variables": {"c": 3, "d": "abc"}} ], "unicode": true, "groups": [1, 2], "admins": [1, 4], "text": "Hello, ", "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" } ``` **Příklad požadavku zadání příjemců polem čísel a naplánování čas v unix timestamp:** ```http-json POST /api/1.0/advanced/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": [ "420775123456", "420606123456", "44771447678" ], "text": "Hello, ", "schedule": "1526992636" } ``` ## Odpověď **V případě úspěchu:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 1, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "sms_id": "idyrcmdd-0", "part_id": [ "idyrcmdd-0_1", "idyrcmdd-0" ], "number": "420775123456", "channel": "sms" }, { "status": "scheduled", "sms_id": "idyrcmdd-1", "part_id": [ "idyrcmdd-1_1", "idyrcmdd-1" ], "number": "420606123456", "channel": "sms" }, { "status": "invalid_number", "code": 400, "error": "Invalid phone number", "detail": null, "number": "44771447678", "channel": "sms" } ] } } ``` Kde: - **part_ID** je pole ID částí původní dlouhé zprávy, která byla rozdělena, protože nesplňovala limit 160 znaků pro jednu zprávu. Více info [zde.](https://www.bulkgate.com/cs/centrum-napovedy/sms/zretezeni-zprav/) **V případě 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** (popisek erroru) můžete vidět v [tabulce typů errorů](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) - **code** představuje http error - **detail** je dodatečná informace o erroru Všechny typy errorů pro Simple API a Advanced API můžete najít [zde.](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/)