> [!WARNING]
> Zneužití [transakční SMS](https://www.bulkgate.com/cs/centrum-napovedy/obecne-informace/rozdil-propagacni-transakcni-sms/) pro propagační/marketingové účely je **přísně zakázáno!** Musí být použito pouze pro informační účely - jako informační SMS.

## API URL

Adresa URL používaná k odeslání požadavků HTTP:

```url
https://portal.bulkgate.com/api/1.0/simple/transactional
```

> [!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

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

Příklady pro každou z nich najdete v [metodách požadavku](https://www.bulkgate.com/cs/dokumentace/simple-api/simple-transactional-metody/).

## 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            | Číslo příjemce	                                                                                                                                                                                                                                                                                                                                                                    | **Ano** |        -        |
| text              | Text SMS zprávy (max. 612 znaků nebo 268 znaků, jestliže je aktivován Unicode), UTF-8 kódování	                                                                                                                                                                                                                                                                                    | **Ano** |        -        |
| 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    |      -        |
| country           | Poskytněte čísla příjemců v mezinárodním formátu (s prefixem, např. `420`) nebo přidejte [kód země ve formátu ISO 3166-1 alpha-2](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`**, je použita země z vašeho uživatelského profilu. |   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). Hodnota `now` odešle zprávu ihned, stejně jako když parametr vynecháte. |   Ne    |      Nyní       |
| duplicates_check  | Zvolte možnost **`on`**, chcete-li zabránit odesílání duplicitních zpráv na stejné telefonní číslo. Zprávy se stejným textem zaslaným na stejné číslo budou odstraněny, pokud je časový interval kratší než 5 minut. Pokud je aktivní možnost **`off`**, žádné duplikáty nebudou odstraněny.                                                                                      |   Ne    |      `off`      |
| tag               | Označení zpráv pro následné dohledání uživatele                                                                                                                                                                                                                                                                                                                                   |   Ne    |        -        |

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

## Příklad požadavku

```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"
}
```

## Odpověď

**V případě úspěchu:**

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

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