> [!WARNING]
> Zneužitie [transakčných SMS](https://www.bulkgate.com/sk/centrum-pomoci/vseobecne-informacie/rozdiel-propagacna-transakcna-sprava/) na propagačné/marketingové účely je **prísne zakázané!** Smú sa používať len na informačné účely – ako informačné SMS.

## API URL

Adresa URL, na ktorú sa posielajú požiadavky HTTP:

```url
https://portal.bulkgate.com/api/1.0/simple/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

- `GET`
- `POST` - `application/x-www-form-urlencoded`
- `POST` - `application/json`

Príklady pre každú z nich nájdete v [metódach požiadavky](https://www.bulkgate.com/sk/dokumentacia/simple-api/simple-transactional-metody/).

## 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	                                                                                                                                                                                                                                                                                                                                                                    | **Áno** |        -        |
| text              | Text SMS správy (max. 612 znakov alebo 268 znakov, ak je aktivovaný Unicode), kódovanie UTF-8	                                                                                                                                                                                                                                                                                    | **Áno** |        -        |
| unicode	           | `Yes`/`true`/`1` pre Unicode SMS, `no`/`false`/`0` pre 7-bitové SMS                                                                                                                                                                                                                                                                                                                   |   Nie    |     `false`     |
| 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    |      -        |
| 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` = `420775123456`). 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). Hodnota `now` odošle správu okamžite, rovnako ako keď parameter vynecháte. |   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    |        -        |

### 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/)                    |

## Príklad požiadavky

```http-json
POST /api/1.0/simple/transactional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
    "application_id": 451, 
    "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", 
    "number": "777777777", 
    "text": "test_sms", 
    "unicode": true,
    "sender_id": "gText",
    "sender_id_value": "BulkGate",
    "country": "cz"
}
```

## Odpoveď

**V prípade úspechu:**

```json
{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1_2",
            "tmpde1bcd4b1d1"
        ],
        "number": "420777777777"
    }
}
```

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 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/).