Simkaarten activeren met de ThingSIM API

Installeer je apparaten bij klanten, of bouw je ze op een werkbank, dan wordt elke simkaart met de hand activeren in het portaal al snel een klus. De ThingSIM API doet hetzelfde vanuit je eigen tools: een simkaart inschakelen als het apparaat geïnstalleerd is, hem labelen zodat je hem later terugvindt, en eSIM-codes ophalen zonder een QR-code te scannen. Deze gids loopt de basisstappen door.

Voordat je begint

De API is één HTTPS-endpoint, https://partners.netavo.com/api/v1, dat JSON teruggeeft. Het is dezelfde API die het portaal gebruikt. Maak in het portaal onder API keys een sleutel aan met de scopes die nodig zijn; voor deze gids zijn dat iot.sims:read, iot.sims:write en, voor eSIMs, iot.esim:read. De sleutel wordt één keer getoond, dus bewaar hem op een veilige plek. Alle details staan in het developer overview en de API-referentie (beide in het Engels).

export THINGSIM_API_KEY="your key"

Je simkaarten opvragen

Simkaarten worden herkend aan hun ICCID, het nummer dat op de kaart gedrukt staat. Vraag de lijst op om de simkaart te vinden die je installeert:

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

Je kunt de lijst filteren op status of tag, of search gebruiken.

Activeer een simkaart als het apparaat live gaat

Simkaarten komen inactief aan en de facturering start op de dag dat je een simkaart inschakelt (of automatisch 30 dagen na verzending, met minstens 5 dagen van tevoren een e-mail). Het logische moment om te activeren is dus als het apparaat geïnstalleerd en getest is. Stuur bij elke activering een unieke Idempotency-Key mee, en gebruik dezelfde waarde opnieuw als je het verzoek herhaalt, zodat een weggevallen verbinding nooit twee keer activeert:

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

Label hem terwijl je nog weet waar hij zit

Elke simkaart kan een label en tags hebben. Stel ze in bij de installatie, zodat je de simkaart later kunt terugvinden en filteren:

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": "Poortcamera unit 4", "tags": ["locatie-utrecht", "camera"]}'

Haal een eSIM-code op zonder QR-scan

Voor apparaten die een eSIM gebruiken, is de activeringscode direct beschikbaar, zodat een provisioningscript hem op het apparaat kan laden:

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

Andere functies die je nodig hebt

Met dezelfde API pauzeer en hervat je simkaarten, wijzig je bundels (POST .../plan met een plan-id uit GET /v1/iot/plans), lees je verbruik en sessies uit en zeg je simkaarten op die niet meer in gebruik zijn. Opzeggen vraagt een eigen scope, iot.sims:cease, zodat een sleutel in de app van een installateur niet per ongeluk simkaarten definitief kan opzeggen. Geef elke sleutel alleen de scopes die hij nodig heeft.

Wil je van gebeurtenissen horen in plaats van ernaar te pollen, zoals een simkaart die activeert of bijna door zijn bundel heen is, gebruik dan webhooks: zie verbruikswebhooks. Voor een overzichtelijke vloot, zie een kleine simkaartvloot beheren.

Veelgestelde vragen

Is de API anders dan het portaal?

Nee. Het is dezelfde API die het portaal gebruikt, dus alles wat je in het portaal met een simkaart kunt doen, kun je automatiseren.

Wat voorkomt dat een herhaald verzoek een simkaart twee keer activeert?

De header Idempotency-Key. Stuur bij elke actie een nieuwe unieke waarde en bij een herhaling dezelfde waarde, dan voert de API de actie één keer uit.

Kan ik een API-sleutel beperken tot bepaalde acties?

Ja. Sleutels hebben scopes; voor het opzeggen van een simkaart is bijvoorbeeld de aparte scope iot.sims:cease nodig, dus geef elke sleutel alleen wat hij nodig heeft.