> [!CAUTION]
> Es ist **strengstens untersagt**, SMS-Benachrichtigungen für Werbe- oder Marketingzwecke zu missbrauchen. Sie dürfen ausschließlich zur Benachrichtigung verwendet werden – als [transaktionale SMS](https://www.bulkgate.com/de/hilfe-center/allgemeine-informationen/unterschied-werbliche-transaktionale-nachrichten/).

## API-URL

URL zum Senden von HTTP-Anfragen:

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

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

## Parametertabelle

| PARAMETERNAME     | WERT | PFLICHT | STANDARDWERT |
|:------------------|:-----|:-------:|:------------:|
| application_id    | [Anwendungs-ID](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-verwaltung/) | **Ja** | - |
| application_token | [Anwendungstoken](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-tokens/) | **Ja** | - |
| number            | Nummer des Empfängers | **Ja** oder `admin` | - |
| admin             | Nummer des BulkGate-Administrators, der die Benachrichtigung erhält. [Mehr Informationen](https://www.bulkgate.com/de/dokumentation/advanced-api/advanced-transactional-benachrichtigungen-an-administratoren/) | **Ja** oder `number` | - |
| text              | Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei aktiviertem Unicode), UTF-8-Kodierung. In die Vorlage können Variablen aus dem Array `variables` (weiterer Parameter) eingefügt werden: `Hello <first_name> <last_name> ....` | **Ja** | - |
| variables         | Assoziatives Array zum Einfügen von Variablen in den Text, z. B.: `{"first_name": "John", "last_name": "Doe"}` | Nein | `[]` |
| unicode           | `Yes`/`true`/`1` für Unicode-SMS, `no`/`false`/`0` für 7-Bit-SMS | Nein | `false` |
| sender_id         | Absenderkennung, siehe [Typ der Absenderkennung](#typ-der-absenderkennung-sender-id) | Nein | `gSystem` |
| sender_id_value   | Wert des Absenders – `gOwn` (z. B. „420 777 777 777“), `gText` (z. B. „BulkGate“), `gProfile` (z. B. „423“), `gMobile` oder `gPush` [(KEY)](https://www.bulkgate.com/de/hilfe-center/mobile-connect/mobile-connect-installation/) | Nein | `null` |
| country           | Geben Sie die Empfängernummern im internationalen Format an (mit Vorwahl, z. B. `420`) oder fügen Sie den [Ländercode](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) hinzu (`777777777` + `CZ` = `420777777777`). Siehe das Beispiel für die Länderangabe. Ist der Wert **`null`**, wird die Angabe anhand der eingestellten Zeitzone ergänzt. | Nein | `null` |
| schedule          | Planen Sie Datum und Uhrzeit des Versands als [Unix-Zeitstempel](https://en.wikipedia.org/wiki/Unix_time) oder im Format [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601). | Nein | Sofort |
| duplicates_check  | Wählen Sie **`on`**, um den Versand doppelter Nachrichten an dieselbe Telefonnummer zu verhindern. Nachrichten mit demselben Text an dieselbe Nummer werden entfernt, wenn zwischen ihnen weniger als 5 Minuten liegen. Bei **`off`** werden keine Duplikate entfernt. | Nein | `off` |
| tag               | Kennzeichnung der Nachricht, über die der Benutzer sie später wiederfinden kann. | Nein | - |

### Typ der Absenderkennung `sender_id`

| WERT | BEDEUTUNG |
|:--- |:---|
|`gSystem` |Systemnummer|
|`gShort`|Short Code|
|`gText` |Textabsender|
|`gMobile`|[Mobile Connect](https://www.bulkgate.com/de/hilfe-center/mobile-connect/mobile-connect-installation/)|
|`gPush`|Mobile Connect Push – sendet eine Benachrichtigung an die Mobile Connect App|
|`gOwn` |Eigene Nummer (erfordert eine Verifizierung der Nummer)|
|`gProfile`|[BulkGate-Profil-ID](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/)|
| `<int>` |BulkGate-Profil-ID|

## Beispielanfrage

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

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",  	
	"number": "420777777777",
	"unicode": true,
	"text": "Hallo, <first_name> <last_name>",
	"variables": {"first_name": "John", "last_name": "Doe"},
	"sender_id": "gText",
	"sender_id_value": "BulkGate",
	"country": "cz",
	"schedule": "2018-05-14T18:30:00-01:00"
}
```

## Antwort

**Bei Erfolg:**

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

Dabei gilt:

- **part_ID** ist das Array der IDs der Teile der ursprünglichen langen Nachricht, die aufgeteilt wurde, weil sie das Limit von 160 Zeichen für eine einzelne Nachricht überschritten hat. Mehr Informationen [hier](https://www.bulkgate.com/de/hilfe-center/sms/nachrichtenverkettung/).

**Bei einem Fehler:**

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

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** steht für den HTTP-Fehler
- **detail** enthält zusätzliche Informationen zum Fehler

Alle Fehlertypen für die Simple API und die Advanced API finden Sie [hier](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).