Kürzt eine Ziel-URL zu einem Kurzlink, den Sie anschließend im Text einer Nachricht oder im BulkGate Portal verwenden können.

## API-URL

Die URL, an die die HTTP-Anfragen gesendet werden:

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

> [!NOTE]
> Erreicht die Anfrage ihr Ziel nicht, wiederholen Sie sie auf dem [Backup-Server](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/backup-server/) `backup1.bulkgate.com`.

## Unterstützte HTTP-Methoden

- `POST` - `application/json`

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

> [!NOTE]
> Für die API gilt ein Kontingent von `20` Anfragen pro Minute.

## Parametertabelle

| PARAMETERNAME     | WERT                                                                            | PFLICHT   | STANDARDWERT  |
|:------------------|:--------------------------------------------------------------------------------|:----------|:--------------|
| application_id    | [Application ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/)                                   | **Ja**    | -             | 
| application_token | [Authentifizierungstoken der Anwendung](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/)	                  | **Ja**    | -             |
| target_url        | URL, die gekürzt werden soll	                                                   | **Ja**    | -             |
| url_type          | Domain des Kurzlinks, siehe [Unterstützte Domains](#unterstuetzte-domains)      | Nein      | `ur7.wf`      |

### Unterstützte Domains

Die Werte von `url_type` sind Konfiguration der Instanz und ändern sich — die aktuelle Liste für Ihr Konto liefert der [Endpoint `domains`](https://www.bulkgate.com/de/dokumentation/url-kuerzer/url-kuerzer-verfuegbare-domains/). Zum Zeitpunkt der Erstellung dieser Seite:

| DOMAIN              | EINSCHRÄNKUNG DER ZIELADRESSE                             |
|:--------------------|:----------------------------------------------------------|
| `ur7.wf`            | Keine Einschränkung. Standardwert.                        |
| `ms6.fr`            | Keine Einschränkung.                                      |
| `ur7.yt`            | Nur Zieldomains auf der Whitelist.                        |
| `ur7.tf`            | Nur Zieldomains auf der Whitelist.                        |
| `ms6.wf`            | Nur Zieldomains auf der Whitelist.                        |
| `ms6.tf`            | Nur Zieldomains auf der Whitelist.                        |
| `track-message.com` | Nur Zieldomains auf der Whitelist.                        |

Bei den eingeschränkten Domains muss die Zieladresse auf der Whitelist Ihres Kontos stehen, sonst schlägt die Anfrage mit `domain_is_not_white_listed` fehl. Einige öffentliche Dienste (Google, YouTube, Facebook, GitHub und weitere) stehen immer auf der Whitelist.

## Beispielanfrage

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

## Antwort

**Im Erfolgsfall:**

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

Über die API erstellte Links sind **30 Tage** gültig — `expiration` enthält das Ablaufdatum im Format ISO 8601.

Die drei URL-Felder bedeuten nicht dasselbe:

| FELD         | WERT                                                                                                   |
|:-------------|:---------------------------------------------------------------------------------------------------------|
| `short_url`  | Der Kurzlink selbst, zusammengesetzt aus `url_type` und dem generierten Schlüssel                      |
| `target_url` | Die Adresse, wie sie gespeichert wurde — ein fehlendes Schema wird ergänzt und die URL normalisiert, aus `www.bulkgate.com` wird also `http://www.bulkgate.com/` |
| `final_url`  | Die Adresse, die Sie gesendet haben, lediglich um das Schema ergänzt. **Weiterleitungen werden nicht verfolgt**, es handelt sich also nicht um die Seite, auf der der Besucher letztlich landet |
| `title`      | Titel, der von der Zielseite ausgelesen wurde                                                          |


**Im Fehlerfall:**

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

Dabei gilt:

- **type** und **error** (Beschreibung des Fehlers) finden Sie in der [Tabelle der Fehlertypen](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/)
- **code** ist der HTTP-Fehlercode
- **detail** enthält zusätzliche Informationen zum Fehler

### Fehlertypen der Shortener API

Neben den [allgemeinen Typen](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/) gibt die Shortener API eigene Fehlertypen zurück:

| TYP                                     | WANN ER AUFTRITT                                                       |
|:----------------------------------------|:-----------------------------------------------------------------------|
| `url_is_not_valid`                      | `target_url` konnte nicht verarbeitet werden.                          |
| `url_type_is_incorrect`                 | `url_type` steht nicht in der Domainliste des Kontos.                  |
| `domain_is_not_white_listed`            | Die Zieldomain steht nicht auf der Whitelist (bei eingeschränkten Domains). |
| `url_is_not_allowed`                    | Die Zieladresse verweist auf eine lokale/interne Adresse.              |
| `url_can_not_be_redirected_out_of_target_domain` | Die Zieladresse leitet außerhalb ihrer eigenen Domain weiter. |
| `url_can_not_be_created`                | Der Link konnte nicht erstellt werden.                                 |
| `the_per_minute_quota_has_been_exceeded`| Das Kontingent von 20 Anfragen pro Minute ist aufgebraucht.            |