1

SMS FUNKTIONALITÄT KUNDENPORTAL VS. API

DOKUMENTATION Version 2.0, Stand Februar 2019

Inhaltsverzeichnis 1 Allgemeine Information ........................................................................................................................... 2

2 Kundenportal ............................................................................................................................................... 3

2.1 Überblick ............................................................................................................................................... 3

2.2 Administration ..................................................................................................................................... 4

2.3 SMS versenden .................................................................................................................................... 5

2.4 Weiterleitung / Forwarding ............................................................................................................ 6

2.5 Monatliche SMS Limits ..................................................................................................................... 7

2.6 Aufladen ................................................................................................................................................ 8

3 API ................................................................................................................................................................... 9

3.1 Angepasste API Nutzung................................................................................................................. 9

3.2 AutheNtifizierung ............................................................................................................................ 13

3.2.1 Anfrage: ...................................................................................................................................... 14

3.2.2 Rückmeldung:........................................................................................................................... 14

4 Senden einer SMS aus einer externen Umgebung mit API ..................................................... 15

4.1 SMS von einer Anwendung zu einer SIM (alias MT SMS) ................................................ 15

4.1.1 Anfrage: ...................................................................................................................................... 15

4.1.2 Zustellungsbericht: ................................................................................................................. 16

4.2 SMS von einer SIM zu einer Anwendung (alias MO SMS) ............................................... 17

4.2.1 Client (Sender) .......................................................................................................................... 17

4.2.2 Server ........................................................................................................................................... 17

2

1 ALLGEMEINE INFORMATION

Die 1NCE Lifetime Fee beinhaltet 250 SMS. Die SMS kann sowohl als so genannte Mobile

Terminated (MT) oder Mobile Originated (MO) SMS versendet werden. SMS-Nachrichten,

die von einem Endgerät an ein anderes Endgerät gesendet werden, werden nicht unterstützt.

Dies wird auch in den folgenden Abbildungen verdeutlicht:

Textnachrichten sind jedoch für Weckmeldungen von der IoT-Anwendung (anwendungsorientierte SMS) zum Endpunkt (mobile terminated) relevant. Daher wird das Senden und Empfangen von Textnachrichten zwischen SIM-Kartengeräten und Server unterstützt.

Nicht genutzte SMS-Nachrichten verfallen am Ende des Aktivierungszeitraums, es sei denn, der Aktivierungszeitraum wurde verlängert.

3

2 KUNDENPORTAL

2.1 ÜBERBLICK

Das Kundenportal bietet auf zwei Arten eine Übersicht über alle bestellten SIM-Karten: Eine allgemeine Übersicht aller verwendeten Karten über das Dashboard, und eine spezielle Ansicht pro SIM-Karte. Die Dashboard-Ansicht zeigt und ermöglicht:

• Die Anzahl der SIM-Karten mit ausreichendem SMS-Volumen. • Die Anzahl der SIM-Karten mit einem SMS-Volumen unter 20%. • Alle SIM-Karten, bei denen kein SMS-Volumen mehr vorhanden ist. • Innerhalb der Anzeige von geringem oder keinem SMS-Volumen kann der Kunde das

Volumen direkt mit einem neuen Paket von 250 SMS aufladen. • Die gesamte SMS-Nutzung der letzten sechs Monate

Die Ansicht "Meine SIMs" gibt einen detaillierten Überblick über alle SIM-Karten. Diese Übersicht kann geöffnet werden, bereits gefiltert nach bereits verbrauchtem Volumen, indem Sie eine der "VIEW"-Tasten auf dem Dashboard drücken.

Für jede SIM-Karte sind Angaben zum Aktivierungsstatus, IMSI-, ICCID- und MSISDN-Nummer sowie zum Label- und Datenverbrauchsstatus ersichtlich.

4

2.2 ADMINISTRATION

Durch Anklicken einer der angezeigten SIM-Karten öffnet sich eine Detailansicht mit Informationen über

• ICCID / IMSI / MSISDN / Name der SIM-Karte (editierbar) • Lebensdauer / Verstrichene Zeit / Verbleibende Zeit / Enddatum • IP-Adresse / IMEI / Sitzungsstatus / Standort / Netzwerk

Hier wird auch eine Liste der Events einer jeweiligen SIM-Karte in chronologischer Reihenfolge angezeigt.

Aus administrativer Sicht können Sie jede einzelne SIM-Karte deaktivieren/aktivieren. Um die Funktionalität Ihrer SIM-Karte zu überprüfen, können Sie die Verbindung unterbrechen, um die Wiedereinwahl Ihres Geräts in das Mobilfunknetz zu erzwingen.

5

2.3 SMS VERSENDEN

In der Ansicht "SMS" dieser Administrationsoption können Sie eine SMS (MT) direkt aus dem 1NCE Kundenportal an das Anwendungsgerät senden. Sie haben auch eine detaillierte Übersicht über alle an eine bestimmten SIM-Karte gesendeten SMS direkt unter dieser Funktion.

6

2.4 WEITERLEITUNG / FORWARDING

Beim Anklicken der Registerkarte "Konfiguration" im 1NCE Kundenportal befindet sich die Funktion SMS-Weiterleitungskonfiguration (SMS Forwarding). Die SMS-Weiterleitungsfunktion ermöglicht das Versenden von MO-SMS. Hierzu muss der Benutzer die URL des Servers eingeben, der die SMS erhalten soll.

Zum Beispiel: https://myserver.de/sms

or

https://:5000/smsapp

Hinweis: Die oben genannten URL, IP, Port und Pfad sind nur Beispiele und hängen von Ihrem eigenen Setup ab.

7

2.5 MONATLICHE SMS LIMITS

Zur besseren Kontrolle des SMS-Volumenverbrauchs können Sie ein Limit von 10 SMS pro Monat festlegen. Diese Begrenzung kann im Kundenportal unter der Registerkarte "Konfiguration" jederzeit aktiviert und deaktiviert werden und gilt für alle SIM-Karten gleichermaßen.

8

2.6 AUFLADEN

Falls Sie zusätzliches SMS-Volumen benötigen, können Sie im 1NCE Kundenportal das Volumen der enthaltenen SMS für jede einzelne SIM-Karte einfach aufladen. Dies kann entweder direkt aus dem Dashboard für alle SIM-Karten mit geringem Volumen oder über die Registerkarte "Meine SIMs" erfolgen.

9

3 API

3.1 ANGEPASSTE API NUTZUNG

Über das Application Programming Interface (nachfolgend "API" genannt) können SIM-Karten auch direkt über Webservices verwaltet werden. Die 1NCE API ermöglicht es dem Anwender, ohne Nutzung des Kundenportals automatisch Informationen über die SIM-Karten des Kunden zu erhalten, da sie die Integration aller relevanten SMS Funktionen in die kundeneigene Softwareumgebung ermöglicht.

Sie können mit der 1NCE API auf der folgenden Benutzeroberfläche beginnen:

https://api.1nce.com

An dieser Stelle autorisieren Sie sich zuerst über den Button „Authorize“, indem Sie die Zugangsdaten für das 1NCE Kundenportal eingeben (E-Mail-Adresse und Passwort).

10

Anschließend können Sie die verschiedenen SMS-Anfragen testen, die unsere API anbietet:

/sims Manage your SIMs

GET/v1/sims/{iccid}/sms

Anzeigen einer Liste der SMS, die von einer speziellen SIM-Karte gesendet und empfangen werden:

Mit „Execute“ erhalten Sie eine Antwort mit einer Liste aller gesendeten und empfangenen SMS dieser SIM-Karte.

https://api.1nce.com/management-api/swagger-ui.html#//sims

11

POST/v1/sims/{iccid}/sms

Senden Sie eine SMS an die angegebene SIM-Karte mit einer Nachricht, die Sie benötigen:

Derzeit ist nur „payload“ ein Pflichtfeld und muss ausgefüllt werden.

Alle anderen Parameter sind nicht erforderlich und sollten für den Versand einer einfachen SMS nicht benötigt werden. Wenn Sie die volle Flexibilität nutzen möchten, können Sie das Datencodierungsschema und den als Hex-String kodierten User Data Header ändern. Der Typ source_address_type kann verwendet werden, um den Typ der Quelladresse wie national oder international anzugeben.

Mit „Execute“ senden Sie die SMS an Ihr Gerät, das eine 1NCE SIM-Karte verwendet. Die Antwort beinhaltet die CURL, die Request-URL sowie den Code des Response-Headers.

12

GET/v1/sims/{iccid}/sms/{id}

Erhalten Sie Details zu bestimmten SMS wie Status, Nachricht, Lieferzeit, etc.:

Nach dem Ausführen der Anfrage erhalten Sie die detaillierte Antwort mit allen Details dieser SMS.

13

DELETE/v1/sims/{iccid}/sms/{id}

SMS abbrechen, die für die Chipkarte gepuffert und noch nicht zugestellt wurde:

Mit der Ausführung dieses Befehls löschen Sie eine gepufferte und noch nicht zugestellte SMS mit einem detaillierten Antwortcode.

3.2 AUTHENTIFIZIERUNG

Die Verwendung der 1NCE REST API über das externe System des Kunden erfordert zunächst eine Authentifizierung. Daher ist die Authentifizierung über OAuth2 mit den gleichen Zugangsdaten wie für das 1NCE Kundenportal (E-Mail-Adresse und Passwort) erforderlich.

14

Als "API-Benutzer" wird die Authentifizierungsmethode mit client_id und client_secret benötigt.

Die OAuth2-Authentifizierung ist notwendig, um ein Token mit Anmeldeinformationen des 1NCE Kundenportals über den folgenden Workflow zu erhalten:

• Senden Sie Ihre Anmeldedaten base64 kodiert an den Authentifizierungsserver. • Erhalten Sie eine Antwort mit einer UUID zur Authentifizierung. • Verwenden Sie die UUID, um REST-Anfragen zu authentifizieren.

Die UUID für die Authentifizierung hat eine Gültigkeitsdauer von 240 Minuten.

Senden Sie dafür die Authentifizierungsanfrage über POST an ```

https://api.1nce.com/management-api/oauth/token

```

3.2.1 ANFRAGE:

**Header**

```json

{

'Content-Type': 'application/x-www-form-urlencoded',

'authorization': 'Basic '

}

```

**Body**

```json

{

'grant_type': 'client_credentials'

}

```

3.2.2 RÜCKMELDUNG:

```json

{

"access_token":"6ba7b810-9dad-11d1-80b4-00c04fd43XXX", // this is the

UUID token you want to use for authentication

15

"token_type":"bearer",

"expires_in":3599,

"scope":"all",

"appToken":"", // not relevant in this context

"userId":,

"orgId":4321 // example

}

```

Sobald Sie authentifiziert sind, können Sie Anfragen senden und die Antworten verwerten.

4 SENDEN EINER SMS AUS EINER EXTERNEN UMGEBUNG MIT API

4.1 SMS VON EINER ANWENDUNG ZU EINER SIM (ALIAS MT SMS)

Um eine SMS über API aus einer externen Umgebung zu versenden, erstellen Sie eine SMS im JSON-Format mit einer möglichen Quelladresse (ICCID Ihrer SIM) und dem Nachrichtentext.

Senden Sie die SMS via POST an die 1NCE API mit der ICCID des Zielgerätes als Parameter: ``` https://api.1nce.com/management-api/v1/sims//sms

```

Verwenden Sie die Authentifizierungs-UUID, um die Anwendung zu authentifizieren.

4.1.1 ANFRAGE:

**Header**

```json

{

'Content-Type': 'application/json',

'authorization': 'Bearer 6ba7b810-9dad-11d1-80b4-00c04fd43XXX', // example; the

UUID token gotten from authorization via OAuth2

'accept': 'application/json'

}

16

```

**Body**

```json

{

"payload": "message text",

"source_address": "882285100000xxx" // your ICCID

}

```

Wenn die Anfrage erfolgreich war, antwortet der Server mit “201 CREATED”.

4.1.2 ZUSTELLUNGSBERICHT:

Der SMS-Gateway-Server sendet eine unaufgeforderte Zustellbericht-Nachricht, nachdem er die SMS an das Gerät weitergeleitet hat.

Stellen Sie dafür eine REST-Schnittstelle in Ihrer Anwendung bereit, die PATCH-Anfragen ermöglicht. **Request**

```json

{

'status': {

'status': 'DELIVERED',

'id': '4'

},

'endpoint': {

'id': '8765432',

'name': '8988280666000000xxx'

},

'submit_date': '2018-08-17 16:46:48',

'organisation': {

'id': '4321'

},

'final_date': '2018-08-17 16:46:52',

'id': '6206'

}

```

17

4.2 SMS VON EINER SIM ZU EINER ANWENDUNG (ALIAS MO SMS)

MO-SMS können von einem SMS-Gateway über HTTP an den Applikationsserver des Kunden weitergeleitet werden. SMS an ein anderes mobiles Gerät wird nicht unterstützt.

4.2.1 CLIENT (SENDER)

Schreiben Sie ein Skript, um SMS mit einem Gerät (z.B. Quectel BG96) zu senden, das die 1NCE SIM-Karte verwendet.

Die SMSC-Adresse lautet 882 285 00001 6868.

Sie finden sie auch im 1NCE Kundenportal (Konfiguration -> Netzwerkeinstellungen), aber sie ist auch auf der SIM-Karte dokumentiert und kann von einem AT-Befehl gelesen werden.

Die zu sendende Nummer (Zieladresse) ist nicht relevant, da die SMS an einen Anwendungsserver gesendet wird. Sie können z.B. 12345 als b-party-Adresse wählen, aber auch andere Nummern sind möglich.

4.2.2 SERVER

Stellen Sie eine REST-Schnittstelle in Ihrer Anwendung zur Verfügung, die POST-Anfragen ermöglicht.

Die SMS wird als JSON über POST weitergeleitet. **Headers**

```

Content-Type: application/json

```

**Body**

```json

{

'multi_part_info': {

'partno': 1,

'total': 1,

'identifier': '6202'

},

'payload': 'message text',

'submit_date': '2018-08-17 16:31:51', // GMT+0

'dest_address': '12345', // example

'organisation': {

18

'id': '4567'

},

'pid': '0',

'id': '6202',

'endpoint': {

'id': '8765432',

'name': '8988280666000000xxx' // from the sending SIM

},

'source_address': '882285100000xxx', // from the sending SIM

'dcs': '0'

}

```

Mit den dcs (Data Coding Scheme) Parametern können Sie die Verschlüsselung der SMS ändern. Der Wert '0' stellt die Standard-GSM-7-Bit-Verschlüsselung dar, der Wert '4' ermöglicht eine 8-Bit-Datenverschlüsselung.

Der Forwarding-Server erwartet nach einer erfolgreichen Weiterleitung eine 2xx-Antwort. Andernfalls wird die SMS gepuffert und erneut gesendet.