LINK Mobility Implementierungshandbuch REST API SMS
LINK Mobility bietet einen Dienst für Nachrichtenübermittlung, Mikrozahlungen und standortbasierte Dienste. Die Plattform fungiert als transparenter White-Label-Content-Acquirer und Transaktionsrouter zwischen Dienstanbietern und Betreibern.
LINK Mobility bietet eine RESTful-API, mit der auf LINK Mobility-Dienste zugegriffen werden kann, z. B. zum Senden von SMS. Diese API ist benutzerfreundlich und mit allen modernen Sprachen und Frameworks kompatibel. In der Sprache Ihrer Wahl kann Ihre Anwendung die Link Mobility REST-API verwenden, um leistungsstarke Messaging- und Zahlungsfunktionen zu implementieren.
© LINK Mobility, 10. März 2021
Rechtliche Hinweise
Die in diesem Dokument bereitgestellten Informationen sind das alleinige Eigentum von Netsize und unterliegen dem Urheberrecht. Sie sind vertraulich und dienen ausschließlich zu Informationszwecken. Sie sind nicht verbindlich und können ohne vorherige Ankündigung geändert werden. Jede unbefugte Weitergabe oder Verwendung gilt als rechtswidrig.
Netsize™ und linkmobility™ sind durch französische, EWG- und internationale Gesetze zum geistigen Eigentum geschützt.
Alle anderen zitierten Marken sind das alleinige Eigentum ihrer jeweiligen Inhaber.
Nichts hierin Enthaltenes darf als Erteilung einer Lizenz oder eines Rechts im Hinblick auf das Patent, Urheberrecht oder Warenzeichen von Netsize ausgelegt werden.
Netzgröße
Anonyme Gesellschaft mit einem Kapital von 5 Euro
Siège social :62, avenue Emile Zola92100 Boulogne – Frankreich
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Umfang des Dokuments
Dieses Dokument beschreibt, wie der Dienstanbieter die LINK Mobility REST API für SMS verwendet. Es richtet sich an technische Architekten und Designer, die die Dienste des Dienstanbieters implementieren.
1. Grundlegende Verwendung
Es ist sehr einfach, eine SMS zu senden. Sie senden eine HTTP-Anfrage an LINK Mobility, die mit nur einem web Browser.
2. Funktionales Overview
Das LINK Mobility-System bietet die folgenden grundlegenden Funktionen für SMS-Nachrichten:
Senden von Mobile Terminated (MT)-SMS-Nachrichten, wie etwa Text- oder Binärnachrichten (z. B. WAP-Push) mit Premium- und Standardtarif.
Empfangen von Zustellberichten für übermittelte MT-Nachrichten.
Empfangen von SMS-Nachrichten vom Mobiltelefon (MO), Premium- und Standardtarif.
Die SMS-REST-API ist für das Senden von MT-SMS-Nachrichten mit Standardtarif vorgesehen.
Die API sendet alle SMS-Nachrichten asynchron und ermöglicht Funktionen wie:
„Fire-and-forget“ – der Dienstanbieter möchte vorhersehbarere Reaktionszeiten haben und nicht auf das Ergebnis des Betreibers warten.
Wiederholungsfunktion – LINK Mobility sendet die Nachricht erneut, wenn der Betreiber vorübergehende Probleme hat.
2.1 Senden einer SMS-Nachricht
Dienstanbieter Netsize Verbraucher
- MT-Nachricht senden
- Antwortnachrichten-ID
- SMS-Nachricht senden
- Zustellbericht übermitteln
- Zustellbericht senden
Der grundlegende Ablauf zum Senden einer SMS-Nachricht wird wie folgt beschrieben:
Der Dienstanbieter stellt eine Anfrage zum Senden einer SMS-Nachricht an einen Empfänger über das LINK Mobility-System.
Eine Nachrichten-ID wird an den Dienstanbieter zurückgesendet. Diese ID kann beispielsweise verwendet werden, um die Nachricht dem richtigen Zustellbericht zuzuordnen.
LINK Mobility übernimmt das Routing und stellt die SMS-Nachricht dem adressierten Verbraucher zu.
Ein Zustellbericht wird ausgelöst, beispielsweise wenn die SMS-Nachricht an das Gerät des Verbrauchers zugestellt wird.
Der Zustellbericht wird an den Dienstanbieter gesendet. Der Bericht enthält dieselbe Nachrichten-ID wie die in Schritt 2 zurückgegebene.
Alternativer Ablauf: Ungültige Anfrage
Wenn die angegebenen Parameter oder Benutzeranmeldeinformationen in der Anforderung ungültig sind, wird ein Fehler an den Dienstanbieter zurückgegeben. Der Fehler gibt den Grund für die Ablehnung an und der Fluss wird beendet. Es werden keine Nachrichten-IDs zurückgegeben.
3. Endpunkt
Der Zugriff auf die SMS-Ressource erfolgt über den Pfad:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Aus Verbindungssicherheit ist die LINK Mobility REST API nur über HTTPS zugänglich.
Das Link Mobility-Serverzertifikat ist von der Thawte Server CA signiert.
4. Betrieb
Der SMS-Dienst ermöglicht die folgenden Vorgänge:
| Name | Weg |
| Schicken | /restapi/v1/sms/senden |
4.1 Senden
Der Sendevorgang dient dazu, eine SMS an einen einzelnen Empfänger zu versenden.
Diese Funktion ist sowohl für einfache als auch für fortgeschrittene Benutzer gedacht. Im einfachsten Fall werden zur Zustellung einer SMS nur die Zieladresse und der Nachrichtentext benötigt. LINK Mobility erkennt das Datencodierungsschema und führt bei Bedarf eine automatische Verkettung einer Nachricht in mehrere Nachrichtenteile durch.
Für eine erweiterte Nutzung kann der Dienstanbieter optionale Parameter zur vollständigen Kontrolle der Nachrichtenformatierung einschließlich des Benutzerdatenheaders verwenden.
Der Dienstanbieter kann verknüpfte Nachrichten senden, die Vorbereitung der Benutzerdaten und des Benutzerdatenheaders muss jedoch vom Dienstanbieter vorgenommen werden und die Nachricht muss mittels mehrerer Sendeanforderungen an LINK Mobility gesendet werden.
5. Authentifizierung
Benutzername und Passwort werden bei jeder Anfrage mithilfe des HTTP Basic Authentication Scheme übermittelt.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Anmeldeinformationen werden in einem Autorisierungsheader in der HTTP-Anforderung gesendet. Der Client erstellt das Headerfeld wie hier beschrieben:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Zum BeispielampWenn beispielsweise der Benutzername „John“ und „changeme“ das Kennwort ist, lautet der resultierende Autorisierungsheader:
Autorisierung: Basic am9objpjaGFuZ2VtZSA=
Als Fallback können Benutzername und Passwort als Anfrageparameter angegeben werden. Dies wird nur für Clients empfohlen, die Basic Auth nicht unterstützen.
6. Eine Anfrage einreichen
6.1 Abfragezeichenfolge
Anforderungsparameter werden als Abfragezeichenfolge übermittelt, die Name/Wert-Paare enthält. Die Abfragezeichenfolge wird mithilfe der Prozentkodierung kodiert (URL Codierung).
http://www.w3schools.com/tags/ref_urlencode.asp
Zum BeispielampAlso wird „Hallo Welt!“ als „Hallo+Welt%21“ kodiert.
6.2 Obligatorische Anfrageparameter
| Name | Maximale Länge | Beschreibung |
| Zieladresse | 40 | Die MSISDN, an die die SMS-Nachricht gesendet werden soll, beginnend mit der Landesvorwahl. Beispiel:ampDatei: 46123456789. Für einige Märkte (in denen die Consumer-MSISDN verschleiert werden muss) kann dieser Wert auch ein alphanumerischer Alias mit dem Präfix „#“ sein. |
| Nachrichtentext | 1600 | Der Inhalt der SMS-Nachricht. |
6.3 Optionale Anfrageparameter (für erweiterte Nutzung)
| Name | Maximale Länge | Beschreibung |
| Ursprungsadresse | 16 | Die Absenderadresse für die ausgehende SMS-Nachricht. Der Typ der Absenderadresse wird durch den Parameter originatorTON definiert. Die maximale Länge der Kurznummer beträgt 16. Der alphanumerische Absender ist auf das GSM-Standardalphabet mit einer maximalen Länge von 11 Zeichen beschränkt. Die maximale Länge des MSISDN-Absenders beträgt 15 (unter Verwendung des gleichen Formats wie das Zieladressenelement). Kann weggelassen werden, wenn originatingAddress und originatingTON vom System ausgewählt werden. Diese Funktion ist markt- und konfigurationsabhängig. Das Verhalten kann bei Operatorintegrationen variieren. |
| UrheberTON | 1 | Der Nummerntyp (TON) der Ursprungsadresse: 0 – Kurznummer 1 – Alphanumerisch (maximale Länge 11) 2 – MSISDN Kann weggelassen werden, wenn originatingAddress und originatingTON vom System ausgewählt werden. Diese Funktion ist markt- und konfigurationsabhängig. Das Verhalten kann bei Operatorintegrationen variieren. |
| Benutzerdatenheader | 280 | Der User Data Header kann zusammen mit den User Data bis zu 140 Oktette enthalten, d. h. 280 bei Hexadezimalcodierung. Dieser Parameter ist immer Hexadezimalcodiert. |
| DCS | 3 | Datencodierungsschema. Das Verhalten kann bei Operatorintegrationen variieren. |
| PID | 3 | Protokoll-ID. Das Verhalten kann bei Operatorintegrationen variieren. |
| relativeGültigkeitszeit | 6 | Relative Gültigkeitsdauer in Sekunden (relativ zur Zeit der Übermittlung an LINK Mobility). Der Maximalwert beträgt 604800 (7 Tage) und der Standardwert 48 Stunden. Das Verhalten kann bei Operatorintegrationen variieren. |
| Lieferzeit | 20 | Zeitamp wann die SMS-Nachricht zugestellt werden soll (verspätete Zustellungszeit). Siehe Abschnitt zum Datums-/Uhrzeitformat. |
| Statusberichtsflaggen | 1 | Berichtsanforderung übermitteln: 0 – Kein Zustellbericht (Standard) 1 – Zustellbericht angefordert 9 – Server-Zustellungsbericht angefordert (LINK Mobility leitet den Bericht nicht an den Dienstanbieter weiter, sondern stellt ihn in Berichten usw. zur Verfügung.) |
| campaignName | 50 | Die LINK Mobility-Transaktionen sind tagmit diesem Namen gruppiert. Es wird verwendet, um Transaktionen in Link Mobility-Berichten zu gruppieren. |
| maxVerketteteNachrichten | 1 | Ein Wert zwischen 1 und 10, der definiert, wie viele zusammenhängende Nachrichten zulässig sind. Der Standardwert ist 3. |
| Korrelations-ID | 100 | Vom Dienstanbieter bereitgestellte ID, die im Zustellbericht angezeigt wird. |
| Benutzername | 100 | Wird als Alternative zur HTTP-Basisauthentifizierung bereitgestellt. |
| Passwort | 100 | Wird als Alternative zur HTTP-Basisauthentifizierung bereitgestellt. |
6.4 HTTP-Anforderungsmethoden
Für maximale Interoperabilität unterstützt die API sowohl HTTP GET- als auch POST-Anforderungsmethoden. Andere HTTP-Methoden sind nicht zulässig.
6.4.1 GET
Die kodierte Abfragezeichenfolge wird an die URL.
ERHALTEN
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hallo+Welt%21
Autorisierung: Basic am9objpjaGFuZ2VtZSA=
6.4.2 BEITRÄGE
Die codierte Abfragezeichenfolge wird im Nachrichtentext der HTTP-Anforderung übermittelt. Content-Type ist application/x-www-form-urlcodiert.
POST https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Inhaltstyp: application / x-www-form-urlcodiert
Autorisierung: Basic am9objpjaGFuZ2VtZSA=
Inhaltslänge: 57
Zieladresse=46123456789&Nachrichtentext=Hallo+Welt%21
6.5 Datum und Uhrzeit
Parameter in der REST-API, die Datum und Uhrzeit darstellen, sind immer in der UTC-Zeitzone (koordinierte Weltzeit) angegeben. Timestamps werden als Zeichenfolge mit genau diesem Format dargestellt:
2017-04-25T23:20:50Z
Dies entspricht 20 Minuten und 50 Sekunden nach der 23. Stunde des 25. April 2017 in UTC.
7. Antwortnachricht
Nach dem Empfang und der Interpretation einer Anforderungsnachricht antwortet die API mit einer HTTP-Antwortnachricht.
7.1 HTTP-Statuscode
Die REST-API gibt für verarbeitete Anfragen immer den HTTP-Statuscode 200 OK zurück. Der Nachrichtentext enthält einen Parameter responseCode, der verwendet wird, um das genaue Ergebnis zu bestimmen.
7.2 Nachrichtentext
Der Nachrichtentext besteht aus JSON, das das Ergebnis der Anfrage beschreibt.
http://json.org/
Link Mobility JSON entspricht dem Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Antwortparameter
| Name | Maximale Länge | Beschreibung |
| Antwortcode | 3 | 0 zeigt eine erfolgreiche Transaktion an. |
| Antwortnachricht | 255 | Textbeschreibung der Antwort, z. B. Fehlertext. |
| Zeitamp | 20 | Datum und Uhrzeit, zu der LINK Mobility die Anfrage verarbeitet hat. (Siehe Abschnitt zum Datums-/Uhrzeitformat). |
| Trace-ID | 36 | Interne Kennung von Link Mobility. Wird für Support und Fehlerbehebung verwendet. |
| Nachrichten-IDs | 10 x 36 | Array eindeutiger LINK Mobility-Nachrichten-IDs für jede erfolgreiche Nachricht (bei einer Verkettung der Nachrichten werden mehrere Nachrichten-IDs zurückgegeben). Wird im Fehlerfall weggelassen. |
7.4 Exampdie Antworten
Erfolg
HTTP/1.1 200 OK
Inhaltstyp: application/json
Inhaltslänge: 144
Datum: Do, 15. September 2016 13:20:31 GMT
{„Antwortcode“:0“, „Antwortnachricht“:“Erfolg“, „Zeitpunktamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hier ist derselbe JSON-Code, der zur besseren Lesbarkeit formatiert wurde:
{
“Antwortcode„:0,
“Antwortnachricht":"Erfolg",
“Zeitamp“:”2016-0915T13:20:31Z”,
“Trace-ID“:”f678d30879fd4adc25f2”,
“Nachrichten-IDs“:[“1-4850879008”] }
Versagen
HTTP/1.1 200 OK
Inhaltstyp: application/json
Inhaltslänge: 148
Datum: Do, 15. September 2016 13:20:31 GMT
{„responseCode“:1, „responseMessage“: „Ungültiger Login oder nicht autorisierte API-Nutzung“, „timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Erfolg
HTTP/1.1 200 OK
Inhaltstyp: application/json
Inhaltslänge: 144
Datum: Do, 15. September 2016 13:20:31 GMT
{„Antwortcode“:0“, „Antwortnachricht“:“Erfolg“, „Zeitpunktamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hier ist derselbe JSON-Code, der zur besseren Lesbarkeit formatiert wurde:
{
“Antwortcode„:0,
“Antwortnachricht":"Erfolg",
“Zeitamp“:”2016-0915T13:20:31Z”,
“Trace-ID“:”f678d30879fd4adc25f2”,
“Nachrichten-IDs“:[“1-4850879008”] }
Versagen
HTTP/1.1 200 OK
Inhaltstyp: application/json
Inhaltslänge: 148
Datum: Do, 15. September 2016 13:20:31 GMT
{„responseCode“:1, „responseMessage“: „Ungültiger Login oder nicht autorisierte API-Nutzung“, „timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Antwortcodes
Die folgenden Antwortcodes können in der Sendeantwort zurückgegeben werden:
| Code | Text | Beschreibung |
| 0 | Erfolg | Erfolgreich ausgeführt. |
| 1 | Ungültiger Login oder nicht autorisierte API-Nutzung | Ein falscher Benutzername oder ein falsches Passwort bzw. der Dienstanbieter wird von LINK Mobility gesperrt. |
| 2 | Der Verbraucher wird von Link Mobility blockiert | Der Verbraucher wird von LINK Mobility gesperrt. |
| 3 | Der Betrieb wird nicht von LINK Mobility bereitgestellt | Der Vorgang ist für den Dienstanbieter gesperrt. |
| 4 | Der Verbraucher ist LINK Mobility unbekannt | Der Verbraucher ist LINK Mobility unbekannt. Oder wenn in der Anfrage ein Alias verwendet wurde: Alias nicht gefunden. |
| 5 | Der Verbraucher hat diesen Dienst in LINK Mobility blockiert | Der Verbraucher hat diesen Dienst bei LINK Mobility blockiert. |
| 6 | Die Absenderadresse wird nicht unterstützt | Die Absenderadresse wird nicht unterstützt. |
| 7 | Alpha-Absenderadresse wird vom Konto nicht unterstützt | Die alphanumerische Absenderadresse wird vom Konto nicht unterstützt. |
| 8 | MSISDN-Ursprungsadresse wird nicht unterstützt | Die MSISDN-Ursprungsadresse wird nicht unterstützt. |
| 9 | GSM erweitert wird nicht unterstützt | GSM erweitert wird nicht unterstützt. |
| 10 | Unicode wird nicht unterstützt | Unicode wird nicht unterstützt. |
| 11 | Statusbericht wird nicht unterstützt | Statusbericht wird nicht unterstützt. |
| 12 | Erforderliche Funktion wird nicht unterstützt | Die zum Senden der Nachricht erforderliche Funktion (außer der oben genannten) wird nicht unterstützt. |
| 13 | Die maximale Drosselungsrate des Inhaltsanbieters wurde überschritten | Der Dienstanbieter sendet die SMS-Nachrichten zu schnell an LINK Mobility. |
| 14 | Protokoll-ID wird vom Konto nicht unterstützt | Protokoll-ID wird nicht unterstützt. |
| 15 | Grenzwert für Nachrichtenverkettung überschritten | Die Anzahl der verknüpften Nachrichten überschreitet die angeforderte Höchstzahl. |
| 16 | Nachricht kann nicht weitergeleitet werden. | LINK Mobility konnte die Nachricht nicht weiterleiten. |
| 17 | Verbotener Zeitraum | Während des Zeitraums ist das Senden von Nachrichten nicht gestattet. |
| 18 | Zu geringes Guthaben auf dem Konto des Dienstanbieters | Dienstanbieter ist wegen zu geringem Guthaben gesperrt |
| 50 | Teilerfolg | Teilerfolg beim Senden einer SMS-Nachricht an mehrere Empfänger. |
| 99 | Interner Serverfehler | Anderer Link Mobility-Fehler. Wenden Sie sich für weitere Informationen an den LINK Mobility-Support. |
| 100 | Ungültige Zieladresse | Die Zieladresse (MSISDN oder Alias) ist ungültig. |
| 102 | Ungültige referenzierte (verlinkte) ID | Die Referenz-ID ist ungültig. Möglicherweise wird die Referenz-ID bereits verwendet, ist zu alt oder unbekannt. |
| 103 | Ungültiger Kontoname | Der Kontoname ist ungültig. |
| 105 | Ungültige Service-Metadaten | Die Service-Metadaten sind ungültig. |
| 106 | Ungültige Absenderadresse | Die Absenderadresse ist ungültig. |
| 107 | Ungültige alphanumerische Absenderadresse | Die alphanumerische Absenderadresse ist ungültig. |
| 108 | Ungültige Gültigkeitszeit | Die Gültigkeitszeit ist ungültig. |
| 109 | Ungültige Lieferzeit | Die Lieferzeit ist ungültig. |
| 110 | Ungültiger Nachrichteninhalt/ungültige Benutzerdaten | Die Benutzerdaten bzw. die SMS-Nachricht sind ungültig. |
| 111 | Ungültige Nachrichtenlänge | Die Länge der SMS-Nachricht ist ungültig. |
| 112 | Ungültiger Benutzerdatenheader | Der Benutzerdatenheader ist ungültig. |
| 113 | Ungültiges Datencodierungsschema | Das DCS ist ungültig. |
| 114 | Ungültige Protokoll-ID | Die PID ist ungültig. |
| 115 | Ungültige Statusberichtsflags | Die Statusberichtsflags sind ungültig. |
| 116 | Ungültige TON | Der TON des Absenders ist ungültig. |
| 117 | Ungültiges campaign-Name | Das campaign-Name ist ungültig. |
| 120 | Ungültiger Grenzwert für die maximale Anzahl an verknüpften Nachrichten | Die maximale Anzahl an verketteten Nachrichten ist ungültig. |
| 121 | Ungültige MSISDN-Ursprungsadresse | Die MSISDN-Ursprungsadresse ist ungültig. |
| 122 | Ungültige Korrelations-ID | Die Korrelations-ID ist ungültig. |
8. Optionale Funktionen
8.1 MSISDN-Korrektur
Die MSISDN-Korrektur ist eine optionale Funktion, die auf Anfrage vom LINK Mobility-Support aktiviert werden kann.
Diese Funktion korrigiert Zieladressen und richtet sie an das erforderliche E.164-Format aus. Zusätzlich zur Formatkorrektur kann das System auch marktspezifische Funktionen ausführen, wie z. B. die Übersetzung internationaler französischer Nummern in korrekte DOM-TOM-Nummern (Départements et Territoires d'outre-mer), sofern zutreffend.
Nachfolgend finden Sie eine Reihe von BeispielenampKorrekturen:
| Übermittelte Zieladresse | Korrigierte Zieladresse |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Französische Nummer übersetzt in eine DOM-TOM-Nummer) |
Darüber hinaus ist es möglich, nationale Telefonnummern für einen ausgewählten Markt zuzulassen. Wenn diese Funktion aktiviert ist, müssen alle internationalen Nummern für andere Märkte mit einem „+“-Zeichen am Anfang gesendet werden, um sie vom ausgewählten Markt zu unterscheiden.
Nachfolgend finden Sie einige BeispieleampAnzahl der vorgenommenen Korrekturen bei Verwendung von Schweden (Ländervorwahl 46) als Standardmarkt für nationale Nummern.
| Übermittelte Zieladresse | Korrigierte Zieladresse |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Ungültig, da das '+' Zeichen fehlt |
Beachten Sie, dass die korrigierte MSISDN von LINK Mobility verwendet und in den Zustellberichten zurückgegeben wird.
Für weitere Informationen wenden Sie sich bitte an den LINK Mobility-Support.
8.2 Zeichenersetzung
Der Zeichenersatz ist eine optionale Funktion, die auf Anfrage vom LINK Mobility-Support aktiviert werden kann.
Diese Funktion übersetzt Nicht-GSM-Alphabetzeichen in den Benutzerdaten (SMS-Text) in entsprechende GSM-Alphabetzeichen, wenn DCS auf „GSM“ eingestellt ist (17). Zum BeispielampDie „Seqüência de teste em Português“ wird in „Seqüencia de teste em Portugues“ übersetzt.
9. Lieferberichte
Der Dienstanbieter kann, sofern vorgesehen, SMS-Zustellungsberichte oder Zustellbenachrichtigungen für die gesendeten MT-Nachrichten anfordern. Diese Berichte werden im SMSC des Betreibers ausgelöst, wenn die MT-Nachricht entweder an den Zielverbraucher zugestellt oder gelöscht wurde, z. B. abgelaufen ist oder aus irgendeinem Grund nicht weitergeleitet werden kann.
Dem Dienstanbieter wird nur der endgültige Status der SMS-Nachricht gemeldet, d. h. zugestellt oder gelöscht. Es wird nur ein Bericht pro MT-Nachricht generiert. Beim gelöschten Status kann ein Ursachencode gelten. Dieser Ursachencode gibt den Grund dafür an, dass die SMS-Nachricht nicht zugestellt werden konnte.
Die Berichte werden über LINK Mobility weitergeleitet und mithilfe des HTTP-Protokolls an den Dienstanbieter gesendet.
Um Berichte zu erhalten, muss der Dienstanbieter beispielsweise Folgendes implementieren:ample ein Java-Servlet oder eine ASP.NET-Seite. Beide empfangen HTTP-GET- oder POST-Anfragen.
Parameter
Die Anfrage umfasst folgende Parameter:
| Parameter | Typ | M/O/I* | Standardwert | Maximale Länge | Beschreibung |
| Nachrichten ID | Schnur | M | – | 22 | Die Nachrichten-ID der MT-Nachricht, zu der dieser Bericht gehört. |
| Zieladresse | Schnur | M | – | 40 | Die MSISDN des Verbrauchers, also die Zieladresse der ursprünglichen MT-Nachricht. |
| StatusCode | ganze Zahl | M | 1 | Der Statuscode gibt den Status der MT-Nachricht an. Gültige Statuscodes sind: 0 – Geliefert 2 – Gelöscht (Grundcode trifft zu) |
|
| ZeitStamp | Schnur | M | – | 20 | Zeitpunkt, zu dem der Zustellbericht bei LINK Mobility eingegangen ist. Die Zeitzone der Zeitamp ist MEZ bzw. MESZ (mit Sommerzeit wie in der EU definiert). Format: jjjjMMtt HH:mm:ss. |
| Operator | Schnur | M | – | 100 | Der beim Senden der SMS-Nachricht verwendete Name des Betreibers oder der beim Senden der SMS-Nachricht verwendete Kontoname. Eine Liste der verfügbaren Betreiber wird vom LINK Mobility-Support bereitgestellt. |
| Ursachencode | ganze Zahl | O | – | 3 | Der Grundcode gibt an, warum die Nachricht den Status „gelöscht“ erhalten hat. Mögliche Begründungscodes sind: 100 – Abgelaufen 101 – Abgelehnt 102 – Formatfehler 103 – Sonstiger Fehler 110 – Abonnent unbekannt 111 – Teilnehmer gesperrt 112 – Abonnent nicht bereitgestellt 113 – Teilnehmer nicht erreichbar 120 – SMSC-Fehler 121 – SMSC-Überlastung 122 – SMSC-Roaming 130 – Mobilteilfehler 131 – Mobilteilspeicher überschritten Das Verhalten kann bei Operator-Integrationen variieren. |
| OperatorTimeStamp | Schnur | O | – | 20 | Zeitpunkt, zu dem die Meldung im SMSC des Betreibers ausgelöst wurde (sofern vom Betreiber angegeben). Die Zeitzone der Zeitamp ist MEZ bzw. MESZ (mit Sommerzeit wie in der EU definiert). Format: jjjjMMtt HH:mm:ss. |
| StatusText | Schnur | O | – | 255 | Platzhalter für zusätzliche Informationen vom Betreiber, z. B. eine Klartextbeschreibung des Status/Grundes. Das Verhalten kann bei Betreiberintegrationen variieren. |
| Korrelations-ID | Schnur | O | – | 100 | Die im SendRequest oder SendTextRequest bereitgestellte Korrelations-ID. |
| BetreiberNetzwerkCode | ganze Zahl | O | – | 6 | Der Mobile Network Code (MCC + MNC) des Betreibers. |
* M = Obligatorisch, O = Optional, I = Ignoriert.
Der Dienstleister muss LINK Mobility die Zielvorgaben mitteilen. URL für Zustellberichte (optional einschließlich Anmeldeinformationen für die HTTP-Basisauthentifizierung). Der Dienstanbieter kann wählen, welche bevorzugte HTTP-Methode verwendet werden soll:
HTTP POST (empfohlen)
HTTP GET.
ExampDatei per HTTP GET (erfolgreich übermittelt):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
ExampDatei per HTTP GET (nicht zugestellt, der Betreiber hat timestamp für die Veranstaltung):
Die Parameter sind URL kodiert.
Zeichenkodierung:
Der Dienstanbieter kann wählen, welche bevorzugte Zeichenkodierung verwendet werden soll:
UTF-8 (empfohlen)
ISO-8859-1.
9.1 Bestätigung des Dienstanbieters
Der Dienstanbieter sollte jeden Zustellbericht bestätigen. Die Bestätigung kann positiv sein, d. h. der Zustellbericht wurde erfolgreich empfangen, oder negativ, d. h. ein Fehler.
Bitte beachten Sie: LINK Mobility hat ein Lese-Timeout für Bestätigungen von 30 Sekunden für Zustellberichte. Ein Timeout löst einen erneuten Zustellversuch (wenn Wiederholung aktiviert ist) oder einen Abbruch der Zustellung (wenn Wiederholung deaktiviert ist) aus. Dies bedeutet, dass die Service-Provider-Anwendung schnelle Reaktionszeiten sicherstellen muss, insbesondere bei hoher Auslastung.
Es wird dringend empfohlen, den Zustellbericht gegenüber LINK Mobility vor der Bearbeitung zu bestätigen.
Die Regel für positive und negative Bestätigung wird wie folgt beschrieben:
Positive Empfangsbestätigung, ACK, Zustellbericht zugestellt:
HTTP 200-Bereichsantwortcode in Kombination mit dem folgenden XML-formatierten Inhalt:
Negative Empfangsbestätigung, NAK, Zustellbericht nicht zugestellt:
Jede Antwort außer einer positiven Bestätigung, z. B.ampEine negative Bestätigung wird durch einen beliebigen HTTP-Fehlercode oder den folgenden XML-Inhalt ausgelöst:
Der XML-Inhalt kann zur Steuerung des LINK Mobility-Wiederholungsmechanismus verwendet werden. Ein NAK führt zu einem Wiederholungsversuch, sofern aktiviert. Für Dienstanbieter, die nicht für den Wiederholungsmechanismus konfiguriert sind, ist der XML-Inhalt optional.
Unten sehen Sie eine HTTP-POST-Anforderung und -Antwort (Beispiel)ampDatei eines an einen Dienstanbieter übermittelten Zustellberichts:
HTTP-Anfrage:
POST /Kontext/App HTTP/1.1
Inhaltstyp: application / x-www-form-urlcodiert;Zeichensatz=utf-8
Host: Server:Port
Inhaltslänge: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-Antwort:
HTTP/1.1 200 OK
Inhaltstyp: Text/Plain
9.2 Wiederholung
Das LINK Mobility-System kann für fehlgeschlagene, d. h. nicht bestätigte Zustellungen von Zustellberichten Wiederholungsversuche durchführen. Der Dienstanbieter kann das bevorzugte Wiederholungsverhalten auswählen:
Kein Wiederholungsversuch (Standard) – Die Nachricht wird verworfen, wenn der Verbindungsversuch fehlschlägt, das Lesetimeout überschritten wird oder ein HTTP-Fehlercode auftritt.
Wiederholen – Bei Verbindungsproblemen aller Art, Lese-Timeouts oder negativen Bestätigungen wird die Nachricht erneut gesendet.
Wenn die Wiederholung für NAK aktiviert ist, ist es wichtig zu verstehen, welche Szenarien einen Wiederholungsversuch von LINK Mobility generieren und wie die Wiederholung funktioniert. Jeder Dienstanbieter hat seine eigene Wiederholungswarteschlange, in der Nachrichten nach der Nachrichtenzeit sortiert werden.amp. Link Mobility versucht immer, ältere Nachrichten zuerst zuzustellen, obwohl die Reihenfolge der an den Dienstanbieter zugestellten Nachrichten nicht garantiert ist. Der Hauptgrund dafür, dass Nachrichten aus der Wiederholungswarteschlange verworfen werden, ist einer von zwei Gründen: Entweder läuft die TTL der Nachricht ab oder (theoretisch) die Wiederholungswarteschlange ist voll. Die TTL ist betreiber- und kontoabhängig, d. h. sie kann je nach Betreiber und/oder Nachrichtentyp variieren, z. B. Premium-SMS oder SMS-Nachricht zum Standardtarif.
Ein Dienstanbieter mit aktivierter Wiederholungsfunktion muss die eindeutige ID der MT-Nachricht überprüfen, um sicherzustellen, dass die Nachricht nicht bereits empfangen wurde.
Für den Dienstanbieter ist es wichtig, diese einfachen Regeln einzuhalten, wenn bei der Verarbeitung eines Zustellberichts ein Fehler auftritt. Wenn der Grund für den Fehler vorübergehend ist (z. B. Datenbank nicht verfügbar), sollte ein NAK zurückgegeben werden. LINK Mobility sendet die Nachricht erneut.
Permanent und ein erneuter Versuch verursachen wahrscheinlich die gleiche Art von Problem, es sollte ein ACK zurückgegeben werden. Zum Beispielample, wenn die Nachricht nicht richtig analysiert werden konnte oder einen unerwarteten Laufzeitfehler verursachte.
Durch entsprechendes Vorgehen wird sichergestellt, dass es zu keinen Blockierungen oder Durchsatzeinbußen aufgrund der wiederholten Übermittlung eines Zustellberichts kommt.
10. Tipps zur Umsetzung
1. Es ist möglich, Ihre web Browser, um Anfragen an die API zu senden. Dies macht es sehr einfach, die Dienste ohne Entwicklungstools zu erkunden und auszuwerten.
2. Empfohlen werden Chrome oder Firefox sowie eine Erweiterung wie JSONView um schön formatiertes JSON anzuzeigen.
3. Wir haben SoapUI zum Testen von POST, der grundlegenden Authentifizierung und zum Überprüfen der unverarbeiteten HTTP-Anforderungs- und Antwortnachrichten verwendet.
4. Das cURL Das Tool ist nützlich, um POST-Anfragen mit Basisauthentifizierung zu senden. Siehe Beispielampsiehe unten.
curl POST \
-H „Inhaltstyp: application/x-www-form-urlcodiert” \
-H „Autorisierung: Basic am9objpjaGFuZ2VtZSA=“ \
https://europe.ipx.com/restapi/v1/sms/send \
–Daten „Zieladresse=46123456789&MessageText=Hallo+Welt%21“
_______________
Transformation personalisierter Kommunikation
Dokumente / Ressourcen
 |
LINK Mobility Implementierungshandbuch REST API SMS [pdf] Benutzerhandbuch Mobilität Implementierungshandbuch REST API SMS, Mobilität, Implementierungshandbuch REST API SMS, REST API SMS, API SMS, SMS |
