Zkrátí cílovou URL na krátký odkaz, který pak můžete použít v textu zprávy nebo v portálu BulkGate.

## API URL

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

```url
https://portal.bulkgate.com/api/1.0/shortener/shorten
```

> [!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/shortener/shorten HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

> [!NOTE]
> API má nastavenou kvótu na `20` požadavků za minutu.

## 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** | -               |
| target_url        | Url ke zkrácení	                                         | **Ano** | -               |
| url_type          | Doména krátkého odkazu, viz [Podporované domény](#podporovane-domeny)   | Ne      | `ur7.wf`        |

### Podporované domény

Hodnoty `url_type` jsou konfigurace instance a mění se — aktuální seznam pro váš účet vrací [endpoint `domains`](https://www.bulkgate.com/cs/dokumentace/zkracovac/zkracovac-dostupne-domeny/). K datu psaní:

| DOMÉNA              | OMEZENÍ CÍLOVÉ ADRESY                                    |
|:--------------------|:----------------------------------------------------------|
| `ur7.wf`            | Bez omezení. Výchozí hodnota.                             |
| `ms6.fr`            | Bez omezení.                                              |
| `ur7.yt`            | Jen cílové domény na whitelistu.                          |
| `ur7.tf`            | Jen cílové domény na whitelistu.                          |
| `ms6.wf`            | Jen cílové domény na whitelistu.                          |
| `ms6.tf`            | Jen cílové domény na whitelistu.                          |
| `track-message.com` | Jen cílové domény na whitelistu.                          |

U domén s omezením musí cílová adresa být na whitelistu vašeho účtu, jinak požadavek skončí chybou `domain_is_not_white_listed`. Několik veřejných služeb (Google, YouTube, Facebook, GitHub a další) je na whitelistu vždy.

## Příklad požadavku

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

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "target_url": "www.bulkgate.com",
  "url_type": "ur7.wf"
}
```

## Odpověď

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

```json
{
    "data": {
        "short_url": "http://ur7.wf/W",
        "target_url": "http://www.bulkgate.com/",
        "final_url": "http://www.bulkgate.com",
        "title": "SMS & other channels for business communication | BulkGate",
        "expiration": "2026-10-10T09:00:00+02:00"
    }
}
```

Odkazy vytvořené přes API mají platnost **30 dní** — `expiration` nese datum vypršení v ISO 8601.

Tři URL pole v odpovědi neznamenají totéž:

| POLE         | HODNOTA                                                                                                 |
|:-------------|:----------------------------------------------------------------------------------------------------------|
| `short_url`  | Samotný zkrácený odkaz, složený z `url_type` a vygenerovaného klíče                                     |
| `target_url` | Adresa tak, jak byla uložena — doplní se chybějící schéma a URL se normalizuje, takže z `www.bulkgate.com` je `http://www.bulkgate.com/` |
| `final_url`  | Adresa, kterou jste poslali, jen s doplněným schématem. **Přesměrování se nesledují**, takže tohle není stránka, kam návštěvník doputuje |
| `title`      | Titulek načtený z cílové stránky                                                                        |


**V případě chyby:**

```json
{
    "type": "url_is_not_valid",
    "code": 400,
    "error": "Url is not valid",
    "detail": null
}
```

```json
{
    "type": "the_per_minute_quota_has_been_exceeded",
    "code": 400,
    "error": "The per minute quota has been exceeded",
    "detail": null
}
```

Kde:

- **type** a **error** (popis chyby) najdete v [tabulce typů chyb](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/)
- **code** je HTTP kód chyby
- **detail** je doplňující informace o chybě

### Typy chyb Shortener API

Vedle [obecných typů](https://www.bulkgate.com/cs/dokumentace/api-administrace-a-tokeny/typy-chyb-api/) vrací Shortener API vlastní:

| TYP                                     | KDY NASTANE                                                           |
|:----------------------------------------|:-----------------------------------------------------------------------|
| `url_is_not_valid`                      | `target_url` se nepodařilo rozparsovat.                                |
| `url_type_is_incorrect`                 | `url_type` není v seznamu domén účtu.                                  |
| `domain_is_not_white_listed`            | Cílová doména není na whitelistu (u domén s omezením).                 |
| `url_is_not_allowed`                    | Cílová adresa míří na lokální/interní adresu.                          |
| `url_can_not_be_redirected_out_of_target_domain` | Cílová adresa přesměrovává mimo svou doménu.                  |
| `url_can_not_be_created`                | Odkaz se nepodařilo založit.                                           |
| `the_per_minute_quota_has_been_exceeded`| Vyčerpaná kvóta 20 požadavků za minutu.                                |