## API-URL URL, an die HTTP-Anfragen gesendet werden: ```url https://portal.bulkgate.com/api/1.0/integration/transactional-bulk ``` > [!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`. ```http POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json ``` > [!CAUTION] > 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 zur Benachrichtigung verwendet werden – als SMS-Benachrichtigung. > [!NOTE] > Möchten Sie über die transaktionale Route Benachrichtigungen in großen Mengen senden, wenden Sie sich bitte an [unseren Support](https://www.bulkgate.com/de/kontaktieren-sie-uns/). Aus berechtigten Gründen können wir diese Option freischalten. > [!WARNING] > Auch Empfänger, die sich abgemeldet haben, erhalten die Nachricht (das Opt-out gilt nur für Werbenachrichten). ### Parametertabelle | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:------------------|:--------------------------------------------------------|:---------:|:---------------------------------:| | application_id | [Anwendungs-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** | - | | tag | Persönliches Identifikationslabel | Nein | - | | messages | Array von Nachrichten | **Ja** | [Nachrichtenobjekt](#nachrichtenobjekt) | ### Nachrichtenobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:----------------|:--------------------------------------------------------------------------------|:---------:|:---------------------------------------:| | primary_channel | Primärer Kanal, der in der Kaskade zuerst verwendet wird | Nein | `sms` | | phone_number | Telefonnummer des Empfängers | **Ja** | - | | 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 (`775123456` + `CZ` = `420775123456`). Siehe das Beispiel zur Länderangabe. Ist der Wert **`null`**, wird die Angabe anhand der von Ihnen eingestellten Zeitzone ergänzt | Nein | `null` | | schedule | Planen Sie Datum und Uhrzeit des Versands als [Unix-Zeitstempel.](https://en.wikipedia.org/wiki/Unix_time) Siehe Beispiele unten. | Nein | `null` | | channels | Assoziatives Array von Kanalobjekten | **Ja** | [Kanalobjekt](#viber-kanalobjekt) | ### Viber-Kanalobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:---------------|:---------------------------------------------------------------------------------|:---------:|:-------------:| | sender | Name des Absenders | Nein | - | | expiration | Zeit, nach der die Nachricht abläuft | Nein | `3600` | | text | Text der Nachricht. In die Vorlage können Variablen aus dem Array `variables` (weiterer Parameter) eingefügt werden: `Hello ....` | **Ja** | - | | variables | Assoziatives Array zum Einfügen von Variablen in den Text, z. B. `{"first_name": "John", "last_name": "Doe"}` | Nein | `[]` | ### SMS-Kanalobjekt | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:----------------|:---------------------------------------------------------------------------------|:---------:|:-------------:| | 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 | `''` | | unicode | `Yes`/`true`/`1` für Unicode-SMS, `no`/`false`/`0` für 7-Bit-SMS | Nein | `false` | | text | Text der SMS (max. 612 Zeichen bzw. 268 Zeichen bei aktiviertem Unicode), Kodierung UTF-8. In die Vorlage können Variablen aus dem Array `variables` (zusätzlicher Parameter) eingefügt werden: `Hello ....` | **Ja** | - | | variables | Assoziatives Array zum Einfügen von Variablen in den Text, z. B.: `{"first_name": "John", "last_name": "Doe"}` | Nein | `[]` | #### Typ der Absenderkennung `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 Ihre App Mobile Connect | | `gOwn` | Eigene Nummer (erfordert eine Verifizierung der Nummer) | | `gProfile` | [ID des Absenderprofils](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/) | | `` | ID des Absenderprofils | **Beispiel einer vollständigen Anfrage:** ```http-json POST /api/1.0/integration/transactional-bulk HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "tag": "", "messages": [ { "primary_channel": "sms", "phone_number": "420777777777", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } }, { "primary_channel": "sms", "phone_number": "420777777778", "country": "cz", "schedule": 1683101313, "channels": { "viber": { "sender": "BulkGate", "expiration": 3600, "text": "test ", "variables": { "variable_1": "name" } }, "sms": { "sender_id": "gSystem", "sender_id_value": "BulkGate", "unicode": false, "text": "test ", "variables": { "variable_1": "name" } } } } ] } ``` ## Mögliche Antworten auf diese Anfrage: **Bei Erfolg** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [ { "status": "scheduled", "message_id": "#############-0", "part_id": [ "#############-0" ], "number": "420777777777", "channel": "sms" }, { "status": "scheduled", "message_id": "#############-1", "part_id": [ "#############-1" ], "number": "420777777778", "channel": "sms" } ] } } ``` **Bei einem Fehler:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 0, "error": 0, "blacklisted": 0, "invalid_number": 0, "invalid_sender": 0 } }, "response": [] } } ``` ```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** ist der HTTP-Fehlercode - **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/).