API

Dokumentation

API Funktionalität

Allgemeine Informationen

1NCE bietet ein so genanntes Application Programming Interface (kurz „API“) an, das Nutzern die Möglichkeit gibt, die wichtigsten Funktionen des Kundenportals in die eigenen Anwendungen zu integrieren. Die unterstützten Funktionen der 1NCE API ermöglichen dem Kunden im Allgemeine, seine 1NCE SIM-Karten von einem externen System heraus zu managen, zu kontrollieren und zu überwachen.

API Nutzung

Das 1NCE API kann über den folgenden Link aufgerufen werden:

https://api.1nce.com

Für den Zugriff auf die 1NCE API muss sich der Kunde zuerst authentifizieren. Die geschieht über das anklicken des „Authorize“-Buttons. Der Kunden wird daraufhin aufgefordert, seine Zugangsdaten einzugeben. Diese Zugangsdaten sind identisch mit denen für das Kundenportal (E-Mail-Adresse und Passwort). Nur als “API User” sind diese die Client ID, mit der Kundennummer als Präfix, und das dazugehörige Passwort (Client secret).

 

 

Im nächsten Schritt kann man die einzelnen 1NCE API Anfragen ausprobieren:

1. /orders ->Kontrolle über Bestellungen

GET/v1/orders

Eine Liste aller Bestellungen anzeigen

POST/v1/orders

Eine Bestellung aufgeben

GET/v1/orders/{order_number}

Details zu einer bestimmten Bestellung entsprechend der Bestellnummer

2. /products ->Produkt Information

GET/v1/products

Eine Liste der Produkte anzeigen

3. /sims ->SIM-Karten managen

GET/v1/sims

Eine Liste aller SIM-Karten anzeigen

POST/v1/sims

Ändern einer SIM-Karten Liste zum Aktivieren, Deaktivieren, Labeln, IMEI-Lock setzen, etc.

GET/v1/sims/{iccid}

Anzeigen aller Statusinformationen, wie Status, Label, MSISDN, IMSI, ICCID, Lifetime, etc.

PUT/v1/sims/{iccid}

Ändern einer SIM-Karte zu ‚aktiviert‘, ‚deaktiviert‘, ändern des Labels oder des IMEI-Lock, etc.

GET/v1/sims/{iccid}/connectivity_info

Auslesen von Verbindungsinformationen und Standortdaten einer SIM-Karte

GET/v1/sims/{iccid}/events

Auslesen der Event-Daten einer SIM-Karte, wie Netzwerk Events

GET/v1/sims/{iccid}/quota/data

Anzeigen des Daten-Verbrauchs einer SIM-Karte

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

Anzeigen des SMS-Verbrauchs einer SIM-Karte

POST/v1/sims/{iccid}/reset

Eine SIM-Karte veranlassen, die Verbindung zurück zu setzen. Die positive Rückmeldung bedeutet jedoch nur, dass der Befehl zur Karte übermittelt wurde, die eigentliche Ausführung kann etwas verzögert sein.

GET/v1/sims/{iccid}/sms

Abrufen einer Liste von SMS, die von der SIM-Karte empfangen und versendet wurden

POST/v1/sims/{iccid}/sms

Eine SMS (MT) an eine SIM-Karte schicken

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

Details zu einer SMS abrufen

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

Zurückrufen einer SMS, die nur zwischengespeichert und noch nicht der Karte zugestellt wurde

POST/v1/sims/{iccid}/topup

Das Daten-Volumen einer SIM-Karte aufladen

GET/v1/sims/{iccid}/usage

Abrufen einer Liste des täglichen Verbrauchs einer SIM-Karte

POST/v1/sims/topup

Das Daten-Volumen aller SIM-Karten aufladen

Eine detaillierte Beschreibung, wie die einzelnen Anfragen zu nutzen sind, wird nach dem Anklicken der Anfragen angezeigt. Um im nächsten Schritt die Nutzung auszuprobieren und gezielte Werte einzutragen, muss man den Button “Try it out” anklicken.

Klicken Sie eine Anfrage an, um diese zu testen.
Sobald Sie autorisiert sind, können Sie nach dem Anklicken des “Try it out”-Button Ihre eigene ICCID eintragen.
Sie können einen realen Test durchführen, indem Sie den Button “Execute” anklicken.

Authentifizierung

Bei der Einbindung des 1NCE REST API in das kundeneigene externe System ist eine Authentifizierung notwendig. Die Authentifizierung ist über OAuth2 ist hier erforderlich. Hierbei handelt es sich in der Regel um die gleichen Nutzerdaten wie beim 1NCE Kundenportal (E-Mail-Adresse und Passwort); als “API User” ist die Authentifizierung mit client_id und client_secret erforderlich.

Die OAuth2 Authentifizierung ist notwendig, um eine Zeichenfolge (Token) als Zugangsdaten zu den Funktionen des 1NCE Kundenportals über folgende Schritte zu erhalten:

 

  • Senden Sie Ihre Zugangsdaten base64 kodiert an den Authentifizierungs-Server.
  • Erhalten Sie eine Rückmeldung mit der UUID zur Authentifizierung.
  • Nutzen Sie diese UUID zur Authentifizierung der REST-Anfrage.

 

Die UUID zur Authentifizierung ist 240 Minuten gültig. Achtung: Nach Ablauf der 240 Minuten muss der Authentifizierungs-Prozess wiederholt werden.
Senden Sie die Authentifizierungs-Anfrage über POST an

 

„`

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

„`

1. Anfrage

**Header**

„`json

{

‚Content-Type‘: ‚application/x-www-form-urlencoded‘,

‚authorization‘: ‚Basic <base64 encoded username:password>‘

}

„`

**Body**

„`json

{

‚grant_type‘: ‚client_credentials‘

}

„`

2. Rückmeldung

„`json

{

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

UUID token you want to use for authentication

„token_type“:“bearer“,

„expires_in“:3599,

„scope“:“all“,

„appToken“:“<application_token>“, // not relevant in this context

„userId“:<id>,

„orgId“:4321 // example

}

„`

 

Bitte beachten Sie, dass nur als authentifizierter Nutzer Anfragen gesendet und Rückmeldungen empfangen werden können.

API Dokument

1NCE stellt eine komfortable Übersicht aller API Anfragen in einem API Dokument zur Verfügung. Zugang über

https://api.1nce.com/management-api/api-docs

finde Sie oben auf der 1NCE API Seite.

(Die Ansicht kann möglicherweise nicht mit jedem Browser dargestellt werden, Empfehlung: Firefox 63.0 oder neuere Version)