Activer des cartes SIM avec l’API ThingSIM

Si vous installez des équipements chez vos clients, ou si vous les préparez en atelier, activer chaque carte SIM à la main dans le portail devient vite une corvée. L’API ThingSIM fait le même travail depuis vos propres outils : activer une carte SIM quand son équipement est installé, l’étiqueter pour la retrouver plus tard et récupérer les codes eSIM sans scanner de QR code. Ce guide présente le déroulé de base.

Avant de commencer

L’API est un point d’accès HTTPS unique, https://partners.netavo.com/api/v1, qui renvoie du JSON. C’est la même API que celle du portail. Créez une clé dans le portail, sous API keys, en choisissant les scopes nécessaires ; pour ce guide, il s’agit de iot.sims:read, iot.sims:write et, pour les eSIM, iot.esim:read. La clé ne s’affiche qu’une fois : conservez-la en lieu sûr. Tous les détails figurent dans la présentation pour les développeurs et la référence de l’API (en anglais).

export THINGSIM_API_KEY="votre clé"

Lister vos cartes SIM

Les cartes SIM sont identifiées par leur ICCID, le numéro imprimé sur la carte. Listez-les pour trouver celle que vous installez :

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

Vous pouvez filtrer la liste par status ou par tag, ou utiliser search.

Activer une carte SIM à la mise en service de l’équipement

Les cartes SIM arrivent désactivées et la facturation commence le jour où chacune est activée (ou automatiquement 30 jours après l’expédition, avec un préavis de 5 jours par e-mail) : le bon moment pour activer est donc celui où l’équipement est installé et testé. Envoyez un Idempotency-Key unique avec chaque activation, et réutilisez la même valeur en cas de nouvelle tentative, pour qu’une connexion interrompue n’active jamais deux fois :

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

L’étiqueter tant que vous savez où elle est

Chaque carte SIM peut porter un libellé et des tags. Renseignez-les à l’installation pour pouvoir retrouver et filtrer la carte SIM plus tard :

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": "Caméra portail bâtiment 4", "tags": ["site-lyon", "camera"]}'

Récupérer un code eSIM sans scanner de QR code

Pour les équipements qui acceptent une eSIM, le code d’activation est disponible directement : un script de provisionnement peut donc le charger dans l’équipement.

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

Les autres commandes utiles

La même API met en pause et réactive les cartes SIM, change de forfait (POST .../plan avec un identifiant de forfait obtenu par GET /v1/iot/plans), lit la consommation et les sessions, et résilie les cartes SIM retirées du service. La résiliation demande son propre scope, iot.sims:cease, pour que la clé utilisée par l’application d’un installateur ne puisse pas résilier définitivement des cartes SIM par erreur. Ne donnez à chaque clé que les scopes dont elle a besoin.

Pour être prévenu des événements plutôt que de les interroger, comme l’activation d’une carte SIM ou l’approche de la fin de son forfait, utilisez les webhooks : voir webhooks de consommation. Pour garder un parc bien rangé, voir gérer un petit parc de cartes SIM.

Questions fréquentes

L’API est-elle différente du portail ?

Non. C’est la même API que celle du portail : tout ce que vous pouvez faire sur une carte SIM dans le portail peut être automatisé.

Qu’est-ce qui empêche une requête répétée d’activer deux fois une carte SIM ?

L’en-tête Idempotency-Key. Envoyez une nouvelle valeur unique pour chaque action et la même valeur en cas de nouvelle tentative : l’API n’exécute l’action qu’une fois.

Peut-on limiter une clé API à certaines actions ?

Oui. Les clés ont des scopes ; la résiliation d’une carte SIM, par exemple, demande le scope distinct iot.sims:cease. Ne donnez à chaque clé que ce dont elle a besoin.