## API URL
Adresa URL používaná na odosielanie HTTP požiadaviek:
```url
https://portal.bulkgate.com/api/1.0/advanced/promotional
```
> [!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/advanced/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 | [Aplikačný identifikátor](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/) | **Áno** | - |
| application_token | [Aplikačný overovací token](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/) | **Áno** | - |
| number | Pole príjemcov - [Hodnota number](#hodnota-number) | **Áno** alebo `admins` alebo `groups` | - |
| groups | Pole čísel skupín v adresári BulkGate. [Viac tu](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional-posielanie-sprav-skupinam-z-adresara/) | **Áno** alebo `number` alebo `admins` | - |
| admins | Pole čísel notifikačných administrátorov BulkGate. [Viac tu](https://www.bulkgate.com/sk/dokumentacia/advanced-api/advanced-promotional-posielanie-propagacnych-sprav-administratorom/) | **Áno** alebo `number` alebo `groups` | - |
| text | Text SMS správy (max. 612 znakov alebo 268 znakov, ak je aktivovaný Unicode), kódovanie UTF-8. | **Áno**, ak je `number` zadaný poľom čísel alebo je použitý parameter `groups` alebo `admin` | - |
| unicode | `Yes`/`true`/`1` pre Unicode SMS, `no`/`false`/`0` pre 7bit SMS | Nie | `false` |
| sender_id | ID odosielateľa, pozri [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 | `null` |
| country | Uveďte čí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 [unix timestamp,](https://en.wikipedia.org/wiki/Unix_time) alebo [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Pozrite si príklady uvedené nižšie | Nie | Teraz |
| duplicates_check | Zvoľte možnosť **`same_text`**, ak chcete zabrániť odosielaniu duplicitných správ na rovnaké telefónne číslo. Možnosťou **`same_number`** zakážete odoslanie správy s rovnakým alebo iným textom na rovnaké číslo. Ak je aktívna hodnota **`null`**, žiadne duplicity sa neodstránia. Duplicity sa odstraňujú **len v rámci jednej dávky**, nie naprieč požiadavkami. | Nie | `null` |
| tag | Označenie správ na ich neskoršie dohľadanie používateľom | Nie | - |
### Hodnota `number`
Hodnotu number je možné zapísať dvoma spôsobmi:
- Pole telefónnych čísel
```json
[
"420775123456",
"420606123456",
"44771447678"
]
```
- Asociatívne pole so schémou `number`, `text` a `variables`, kde jediný povinný parameter je `number`. Ak `number` nie je vyplnený, správa sa preskočí.
```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 šablóny parametra `text` je možné doplniť premenné z poľa `variables`.
### Typ ID odosielateľa `sender_id`
| HODNOTA | VÝZNAM |
|:-----------|:------------------------------------------------------------------------|
| `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` | [BulkGate Profil ID](https://www.bulkgate.com/sk/centrum-pomoci/sms/profil-odosielatela/) |
| `` | BulkGate Profil ID |
## Príklady požiadaviek
**Príklad úplnej požiadavky:**
```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"
}
```
**Príklad požiadavky so zadaním príjemcov poľom čísel a naplánovaním času 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"
}
```
## Odpoveď
**V prípade úspechu:**
```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 častí pôvodnej dlhej správy, ktorá bola rozdelená, pretože nespĺňala limit 160 znakov pre jednu správu. Viac informácií [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/).