Allgemeines
Unsere API bietet die Möglichkeit, automatisierte SMS-Benachrichtigungen direkt aus jeder Software, Anwendung oder CRM zu konfigurieren.
Für die Kommunikation mit dem API-Server wird das HTTP-Protokoll verwendet, die Möglichkeit der sicheren SSL-Verschlüsselung besteht ebenfalls. Für die Übermittlung der Anfragen werden die Funktionen GET und POST verwendet. Der Server liefert die Antworten auf Anfragen in einem der beiden Formate Ihrer Wahl: XML oder JSON. Mehr zu dem Thema, wie man die API anbindet und Anfragen erstellt, steht weiter unten.
API-Integration
Um Anfragen an die API machen zu können, ist es notwendig, diese Funktion im Control Panel von Mobizon einzuschalten und richtig zu konfigurieren.
- Gehen Sie im Control Panel zu den Einstellungen der API:
- Aktivieren Sie die Option Zugang zur API einschalten:
- Geben Sie die IP-Adressen an, von denen die Anfragen an die API aus verschickt werden sollen.
Sobald Sie den Zugang aktiviert haben, sehen Sie Ihren API-Schlüssel. Nutzen Sie diesen Schlüssel in Ihrer Anwendung, um Anfragen an die API zu verschicken.
Der Schlüssel ist geheim, schreiben Sie Ihn weder auf, noch geben Sie ihn an niemanden grundlos weiter, denn die Person, die den Schlüssel hat, hat somit uneingeschränkten Zugang zu Ihrem API-Account und kann alle möglichen Aktion durchführen.
Um für Ihre eigene Sicherheit zu sorgen, empfehlen wir Ihnen, eine Liste mit IP-Adressen anzugeben, von denen aus der Zugang zu der API mit Ihrem Schlüssel erlaubt ist. Geben Sie in das Feld IP-Adressen mit erlaubtem Zugang
die IP-Adressen Ihrer Server an. Es können auch mehrere Adressen sein, in dem Fall müssen Sie die Adressen mit Kommas voneinander trennen. Zum Beispiel: 192.12.34.56,23.45.67.89,123.123.123.123.
Sollten Sie das Feld unausgefüllt lassen, ist die API von jeder IP-Adresse zugänglich, was nicht sicher ist.
Sie können Ihren API-Schlüssel auswechseln, indem Sie auf den Knopf „Auswechseln“ klicken, Sie finden Ihn neben Ihrem Schlüssel. In dem Fall, werden alle Anwendungen, die den vorigen Schlüssel benutzt haben, keinen Zugang mehr zur API haben. Um den Zugang wieder zu ermöglichen, müssen Sie in den Einstellungen Ihrer Anwendung den alten Schlüssel durch den neuen Schlüssel ersetzen.
Anleitung zur Nutzung der API
Zugangspunkt zur API
Alle Anfragen zur API werden über die folgende Adresse übermittelt: https://api.mobizon.gmbh/service/
Sie können die Anfragen mittels HTTP oder HTTPS abschicken. Für eine sicherere Kommunikation Ihrer Anwendung mit der API von Mobizon, empfehlen wir Ihnen, alle Anfragen mittels HTTPS zu machen, falls Ihre Anwendung jedoch keine Möglichkeit anbietet, sichere HTTPS-Anfragen zu erstellen, können Sie immer noch Anfragen mit gewöhnlichem HTTP ohne Verschlüsselung machen, in dem Fall würde die API-Adresse für Sie folgendermaßen aussehen: http://api.mobizon.gmbh/service/.
Notwendige Angaben
Eine minimale Anfrage an die API enthält die Bezeichnung des Moduls, der Funktion und den API-Schlüssel:
https://api.mobizon.gmbh/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
wo:
- user - API-Modul,
- getownbalance — API-Funktion,
und weitere Angaben nach dem Fragezeichen folgen, in diesem Fall, der apiKey.
Wichtig ist, dass vor dem Fragezeichen kein Schrägstrich (Slash) sein darf, solch eine Anfrage wäre fehlerhaft:
https://api.mobizon.gmbh/service/user/getownbalance/?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
Optionale Angaben
- output — Format, in dem die Antwort vom Server geliefert wird.
Im Moment werden zwei Antwort-Formate des API-Servers unterstützt:
- json — die Antwort wird im json-Format als Zeile zurückgeliefert (default)
- xml — die Antwort wird als xml-Dokument zurückgeliefert
Beispiel einer Anfrage:
https://api.mobizon.gmbh/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
- api — API-Version.
Die aktuelle Version ist API — v1, diese Bezeichnung wird standardmäßig benutzt.
Beispiel einer Anfrage:
https://api.mobizon.gmbh/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
- Weitere Angaben.
Allen weiteren Angaben, unter anderem auch Angaben von Funktionen, können als GET- oder POST-Daten überliefert werden. Man sollte auch auf die maximale Länge der GET-Anfragen achten und dass die Antwort möglicherweise durch die dazwischenliegenden Netzwerkknoten zwischengespeichert wird, aus dem Grund empfehlen wir Ihnen, alle Anfragen an die API mit den POST-Funktionen zu realisieren.
Jedes Zeichen, das in den API-Angaben verwendet wird, muss im Format url-encoded vorliegen. Wie sie das mit der jeweiligen Programmiersprache oder dem System, das Sie nutzen, bewerkstelligen, können Sie in den jeweiligen Dokumentationen zu der Programmiersprache oder dem System nachlesen.
Antwort-Format des API-Servers
Die Antwort des Servers besteht aus einer Zeile, die in einem der beiden von Ihnen gewählten Formate (XML oder JSON) ist. Diese beinhaltet ein Objekt, welches aus drei Elementen besteht: code, data, message. Beispiel einer Antwort im JSON-Format:
{
"code":0,
"data":{
"balance":"4043.0656",
"currency":"EUR"
},
"message":""
}
Im XML-Format würde die Antwort folgendermaßen aussehen:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<code>0</code>
<data>
<balance>123.4567</balance>
<currency>EUR</currency>
</data>
<message></message>
</root>
wo:
- code — API-Statuscodes, sehen Sie die API-Statuscodes in der Dokumentation ein,
- data — die zurückgelieferten Daten, die in einem Format vorliegen, welches von der ausgeführten API-Funktion vorgesehenen ist, im Falle eines eingetretenen Fehlers ist es auch möglich, dass Daten zurückgeliefert werden, die auf die Ursache des Fehlers schließen lassen
(zum Beispiel eine Liste mit fehlerhaften Feldern und eine Beschreibung dieser Fehler im Falle einer fehlerhaften Validierung),
- message — Statustext, der normalerweise einen (falls vorhanden) Fehler im Allgemeinen beschreibt.
API-Statuscodes
Eine zurückgelieferte Antwort enthält immer ein Feld code, welches einen Zahlenwert enthält, der darauf deutet, ob die Anfrage erfolgreich bearbeitet wurde oder nicht:
- 0 — Antwort erfolgreich.
- 100 — die Antwort ist nicht fehlerhaft, die Aktion wird noch ausgeführt. In diesem Fall enthält das Feld data die ID der Aktion, den Fortschritt und den Status, die man mit Hilfe einer Anfrage an die API mit taskqueue/getstatus nachverfolgen kann.
- Jeder andere Antwort-Statuscode — ein Fehler beim Ausführen der Aktion. Sie können die Fehlercodes auf dieser Seite der Dokumentation einsehen.
Client-Bibliotheken in PHP
Sie können den offiziellen Client MobizonApi in PHP nutzen. Beispiele zur Nutzung. Beispiele zur Nutzung.
Außerdem, gibt es die Möglichkeit, dieses Modul mit Hilfe von Composeranzuschließen.
Beispiele zur Nutzung des Client-Moduls der API in PHP
Wenn Sie eigene Beispiele zur Benutzung haben, würden wir sie mit Freuden auf unserer Website anbringen. Schicken Sie uns einfach den Link und Ihr Beispiel mit dem Code an die Adresse support@mobizon.gmbh
Beispiele zur Nutzung der GET-Anfragen
Um Nachrichten aus Ihrer Anwendung verschicken zu können (falls Ihre Anwendung keine Möglichkeit anbietet, POST-Anfragen zu realisieren), können Sie die GET-Anfragen folgendermaßen nutzen:
https://api.mobizon.gmbh/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
wo:
- NNN...NNN - Telefonnummer des Empfängers im internationalen Nummernformat (ohne das „+“ Symbol),
zum Beispiel
4915750919944.
- PPP...PPP - Absendererkennung (alphaname). Die Absendererkennung muss nicht angeben werden, in dem Fall wird die allgemeine Systemsignatur oder Ihre Standardsignatur (wenn Sie eine besitzen) benutzt werden.
- Message+text+here%21 - Der Text Ihrer SMS-Nachricht im Format url-encoded string: Message text here!.
- KKK...KKK - Ihr API-Schlüssel, den Sie im Control Panel erhalten müssen.
