## API-URL Die URL, an die die HTTP-Anfragen gesendet werden: ```url https://portal.bulkgate.com/api/1.0/simple/promotional ``` > [!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 - `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-promotional-methoden/). ## Parametertabelle | PARAMETERNAME | WERT | PFLICHT | STANDARDWERT | |:------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------|:--------------| | application_id | [Kennung der Anwendung](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 | Nummern der Empfänger, getrennt durch `;` (Semikolon) | **Ja** | - | | text | Text der SMS-Nachricht (max. 612 Zeichen bzw. 268 Zeichen bei Verwendung von 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 [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/) | | | | country | Geben Sie die Nummern der Empfänger im internationalen Format an (mit Vorwahl, z. B. `49`) oder ergänzen Sie den [Ländercode](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 | Planung des Sendezeitpunkts als [Unix-Zeitstempel](https://en.wikipedia.org/wiki/Unix_time) oder im Format [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Siehe die Beispiele unten. Der Wert `now` sendet die Nachricht sofort, genauso als würden Sie den Parameter weglassen. | Nein | Sofort | | duplicates_check | Mit **`on`** verhindern Sie das Senden doppelter Nachrichten an dieselbe Telefonnummer. Nachrichten mit gleichem Text an dieselbe Nummer werden entfernt. Bei **`off`** werden keine Duplikate entfernt. Duplikate werden **nur innerhalb eines einzelnen Stapels** entfernt, nicht über mehrere Anfragen hinweg. | Nein | `off` | | tag | Kennzeichnung der Nachricht, über die Sie sie später abrufen können. | 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 die App Mobile Connect | | `gOwn` | Eigene Nummer (Verifizierung der Nummer erforderlich) | | `gProfile` | [BulkGate Profil-ID](https://www.bulkgate.com/de/hilfe-center/sms/absenderprofil/) | | `` | BulkGate Profil-ID | ## Beispiele für Anfragen **Beispiel einer vollständigen Anfrage:** ```url https://portal.bulkgate.com/api/1.0/simple/promotional ?application_id=451 &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj &number=420777777777;420775123456;606123456 &text=test_sms &unicode=yes &sender_id=gText &sender_id_value=BulkGate &country=cz &schedule=2018-05-14T18:30:00-01:00 ``` **Beispiel einer Anfrage mit Land:** ```url https://portal.bulkgate.com/api/1.0/simple/promotional ?application_id=451 &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj &number=606123456;420777777777 &text=test_sms &country=cz ``` **Beispiel einer Anfrage mit ISO 8601:** ```url https://portal.bulkgate.com/api/1.0/simple/promotional ?application_id=451 &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj &number=420775123456;420606123456 &text=test_sms &schedule=2018-05-14T18:30:00-01:00 ``` **Beispiel einer Anfrage mit Unix-Zeitstempel:** ```url https://portal.bulkgate.com/api/1.0/simple/promotional ?application_id=451 &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj &number=420775123456;420606123456 &text=test_sms &schedule=1526992636 ``` **Beispiel einer POST-JSON-Anfrage:** ```http-json POST /api/1.0/simple/promotional HTTP/1.1 Host: portal.bulkgate.com Content-Type: application/json { "application_id": 451, "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj", "number": "420777777777;420775123456;606123456", "text": "test_sms", "unicode": true, "sender_id": "gText", "sender_id_value": "BulkGate", "country": "cz", "schedule": "2018-05-14T18:30:00-01:00" } ``` ## Antwort **Bei Erfolg:** ```json { "data": { "total": { "status": { "sent": 0, "accepted": 0, "scheduled": 2, "error": 1 } }, "response": [ { "status": "scheduled", "sms_id": "idfkvqrp-0", "part_id": [ "idfkvqrp-0_1", "idfkvqrp-0_2", "idfkvqrp-0" ], "number": "420775123456" }, { "status": "scheduled", "sms_id": "idfkvqrp-1", "part_id": [ "idfkvqrp-1_1", "idfkvqrp-1_2", "idfkvqrp-1" ], "number": "420606123456" }, { "status": "error", "code": 9, "error": "Invalid phone number", "number": "44771447678" } ] } } ``` 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** ist der HTTP-Fehlercode - **detail** enthält zusätzliche Informationen zum Fehler Alle Fehlertypen der Simple API und der Advanced API finden Sie [hier](https://www.bulkgate.com/de/dokumentation/api-verwaltung-und-tokens/api-fehlertypen/).