IoT-SIM-Karten per ThingSIM-API aktivieren

Wenn Sie Geräte bei Kunden installieren oder in der Werkstatt vorkonfigurieren, wird es schnell lästig, jede IoT-SIM-Karte von Hand im Portal zu aktivieren. Die ThingSIM-API erledigt dasselbe aus Ihren eigenen Werkzeugen heraus: eine SIM-Karte einschalten, wenn ihr Gerät installiert ist, sie beschriften, damit Sie sie später wiederfinden, und eSIM-Codes abrufen, ohne einen QR-Code zu scannen. Diese Anleitung zeigt den grundlegenden Ablauf.

Bevor Sie beginnen

Die API ist ein HTTPS-Endpunkt, https://partners.netavo.com/api/v1, der JSON zurückgibt. Es ist dieselbe API, die auch das Portal nutzt. Legen Sie im Portal unter API keys einen Schlüssel an und wählen Sie die Scopes, die er braucht; für diese Anleitung sind das iot.sims:read, iot.sims:write und für eSIMs iot.esim:read. Der Schlüssel wird nur einmal angezeigt; bewahren Sie ihn also sicher auf. Alle Details stehen in der Entwicklerübersicht und in der API-Referenz (beide auf Englisch).

export THINGSIM_API_KEY="your key"

SIM-Karten auflisten

SIM-Karten werden über ihre ICCID identifiziert, die Nummer, die auf der Karte aufgedruckt ist. Listen Sie sie auf, um die SIM-Karte zu finden, die Sie einsetzen:

curl "https://partners.netavo.com/api/v1/iot/sims?limit=5" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

Sie können die Liste nach status oder tag filtern oder search verwenden.

Eine SIM-Karte aktivieren, wenn ihr Gerät in Betrieb geht

SIM-Karten kommen inaktiv an, und die Abrechnung beginnt an dem Tag, an dem die jeweilige SIM-Karte eingeschaltet wird (oder automatisch 30 Tage nach dem Versand, mit 5 Tagen Vorankündigung per E-Mail). Der natürliche Zeitpunkt für die Aktivierung ist also, wenn das Gerät installiert und getestet ist. Senden Sie bei jeder Aktivierung einen eindeutigen Idempotency-Key und verwenden Sie bei einem erneuten Versuch denselben Wert, damit eine abgebrochene Verbindung nie zu einer doppelten Aktivierung führt:

curl -X POST "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/activate" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Beschriften, solange Sie wissen, wo sie eingebaut ist

Jede SIM-Karte kann eine Bezeichnung und Tags tragen. Setzen Sie sie bei der Installation, damit sich die SIM-Karte später finden und filtern lässt:

curl -X PATCH "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000" \
  -H "Authorization: Bearer $THINGSIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "Halle 4 Torkamera", "tags": ["standort-hamburg", "kamera"]}'

Einen eSIM-Code ohne QR-Scan abrufen

Bei Geräten mit eSIM ist der Aktivierungscode direkt abrufbar, sodass ein Provisionierungsskript ihn auf das Gerät laden kann:

curl "https://partners.netavo.com/api/v1/iot/sims/8944000000000000000/esim" \
  -H "Authorization: Bearer $THINGSIM_API_KEY"

Weitere Funktionen, die Sie brauchen werden

Mit derselben API pausieren Sie SIM-Karten und nehmen sie wieder in Betrieb, wechseln Tarife (POST .../plan mit einer Tarif-ID aus GET /v1/iot/plans), lesen Verbrauch und Sitzungen aus und kündigen SIM-Karten, die ausgemustert werden. Das Kündigen braucht einen eigenen Scope, iot.sims:cease, damit ein Schlüssel in der App eines Installationsbetriebs SIM-Karten nicht versehentlich endgültig kündigen kann. Geben Sie jedem Schlüssel nur die Scopes, die er braucht.

Wenn Sie über Ereignisse informiert werden wollen, statt sie abzufragen, etwa wenn eine SIM-Karte aktiviert wird oder sich ihrem Volumen nähert, nutzen Sie Webhooks: siehe Verbrauchs-Webhooks. Wie Sie eine Flotte übersichtlich halten, lesen Sie unter eine kleine SIM-Flotte führen.

Häufige Fragen

Unterscheidet sich die API vom Portal?

Nein. Es ist dieselbe API, die auch das Portal nutzt; alles, was Sie im Portal mit einer SIM-Karte tun können, können Sie also automatisieren.

Was verhindert, dass eine wiederholte Anfrage eine SIM-Karte doppelt aktiviert?

Der Header Idempotency-Key. Senden Sie bei jeder Aktion einen neuen eindeutigen Wert und bei einer Wiederholung denselben Wert, dann führt die API die Aktion genau einmal aus.

Lässt sich ein API-Schlüssel auf bestimmte Aktionen beschränken?

Ja. Schlüssel haben Scopes; zum Kündigen einer SIM-Karte etwa ist der eigene Scope iot.sims:cease nötig. Geben Sie jedem Schlüssel also nur, was er braucht.