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

## API-URL

URL zum Senden der HTTP-Anfragen:

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

> [!NOTE]
> Wenn die Anfrage ihr Ziel nicht erreicht, 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

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

Beispiele für jede Methode finden Sie unter [Anfragemethoden](https://www.bulkgate.com/de/dokumentation/simple-api/simple-transactional-methoden/).

## Parametertabelle

| PARAMETERNAME     | WERT                                                                                                                                                                                                                                                                                                                                                                          | PFLICHT | STANDARDWERT |
|:------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------:|:-------------:|
| application_id    | [Anwendungskennung](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**  |       -       |
| number            | Nummer des Empfängers 	                                                                                                                                                                                                                                                                                                                                                             |  **Ja**  |       -       |
| text              | Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei Unicode), Kodierung UTF-8                                                                                                                                                                                                                                                                               |  **Ja**  |       -       |
| unicode	           | `Yes`/`true`/`1` für Unicode-SMS, `no`/`false`/`0` für 7-Bit-SMS                                                                                                                                                                                                                                                                                                               |    Nein     |    `false`    |
| sender_id         | Absenderkennung, siehe [Absendertyp](#absendertyp-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     |      -        |
| country           | Geben Sie die Nummern der Empfänger im internationalen Format an (mit Vorwahl, z. B. `49`) oder ergänzen Sie den [Ländercode im Format ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`15112345678` + `DE` = `4915112345678`). Siehe die Beispielanfrage mit Land. Bei **`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). Der Wert `now` sendet die Nachricht sofort, genauso wie das Weglassen des Parameters. |    Nein     |      Jetzt      |
| 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     |       -       |

### Absendertyp `sender_id`

| WERT       | BESCHREIBUNG                                                          |
|:-----------|:---------------------------------------------------------------------|
| `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 (Verifizierung der Nummer erforderlich)                            | 
| `gProfile` | [BulkGate-Profil-ID](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/)                |

## Beispielanfrage

```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": "420777777777", 
    "text": "test_sms", 
    "unicode": true,
    "sender_id": "gText",
    "sender_id_value": "BulkGate",
    "country": "de"
}
```

## Antwort

**Im Erfolgsfall:**

```json
{
    "data": {
        "status": "accepted",
        "sms_id": "tmpde1bcd4b1d1",
        "part_id": [
            "tmpde1bcd4b1d1_1",
            "tmpde1bcd4b1d1_2",
            "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/).

**Im Fehlerfall:**

```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-Fehlercode
- **detail** enthält zusätzliche Informationen zum Fehler

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