Intégration API IoT Connect Capped Plans

Cet article expliquera comment commencer à intégrer les API Transatel pour gérer votre  offre de plans IoT Connect Capped.

Si vous êtes sur notre offre générique IoT Connect, avec uniquement de la tarification au compteur ou des forfaits mutualisés comme modèles tarifaires, veuillez consulter cet article

Nous récapitulerons toutes les API requises et recommandées, avec les liens sur le Portail Développeur Transatel et les références API. Pour commencer votre intégration API de nos services, veuillez lire cet article d’abord. Il expliquera comment obtenir des identifiants et où trouver les valeurs techniques liées à votre offre dans le portail de gestion SIM.

Entrons maintenant dans plus de détails concernant les API nécessaires pour gérer l’offre

Activation de vos cartes SIM

Le cycle de vie et les informations de la SIM sont gérés avec les API Connectivity Management
Ces API servent à : – activer les SIM, – modifier les services (appelés « options ») pour vos SIM, – suspendre ou terminer les SIM, – remplir des champs d’information tels que Référence ou Groupes pour organiser votre flotte – récupérer les informations des services d’une SIM spécifique

Pour activer vos SIMs, vous trouverez toutes les notices techniques requises dans le portail de gestion SIM, dans le menu catalogue > options.

Vous aurez besoin de :

• la référence du rate plan utilisé pour votre compte. Si votre compte est sur notre offre standard en euros, cette référence doit être
  M2MA_WW_TSL_IOTCONNECT_CAPPED
• Les labels techniques pour les options que vous souhaitez configurer pour les nouvelles SIM. Cela inclut le choix entre paiement au compteur et forfaits bloqués. Par exemple, pour activer une SIM sur le modèle tarifaire « forfaits bloqués », vous devrez inclure la IOTC_REF_BUNDLES de valeur pour l’option « OFFER_901_IOT_CONNECT_CAP_PRICING » dans votre appel API.

Comment trouver les options spécifiques de votre service pour les appels API ?

Toutes les valeurs des options sont disponibles dans le menu Catalogue > Options de la plateforme de gestion SIM

Là, vous pourrez trouver tous les noms techniques des options de l’offre, à inclure dans vos appels API. Si vous avez plusieurs forfaits tarifaires (par exemple divers forfaits groupés) disponibles dans votre contrat, vous les trouverez dans une liste déroulante :

Voici un exemple pour l’une de nos offres génériques d’IoT :

Ce sont les valeurs exactes utilisées pour créer et modifier les profils de service lors de l’utilisation de notre portail de gestion SIM. L’appel API pour activer une SIM contiendra exactement les mêmes informations qu’un profil de service :
 – le plan tarifaire (qui est le lien vers l’offre) – la valeur de chaque option

Remarque : Pour le moment, les profils de service ne peuvent pas être utilisés avec des API,  mais vous pouvez « recréer » n’importe quelle configuration de profil de service avec les options en utilisant les API de gestion de la connectivité.

Certaines options ont plusieurs choix, et un seul peut être sélectionné. Dans notre interface, elles correspondent aux choix dans les listes déroulantes de notre portail de gestion SIM. Par exemple, pour « Modèle tarifaire », vous devez choisir entre les valeurs des forfaits plafonnés et du paiement à l’utilisation

Chaque sélection a aussi une valeur par défaut – si vous n’en sélectionnez pas une dans votre appel, c’est celle-ci qui sera implémentée.

Voici un exemple d’appel d’activation pour une SIM qui sera sur le modèle tarifaire Forfaits :

Remarque : Si vous n’incluez pas de valeur spécifique pour le modèle tarifaire dans votre activation de la SIM, la SIM sera configurée pour le modèle des forfaits plafonnés comme valeur par défaut

Récupération de la liste des SIM/eSIM

Utilisez l’  API SIM Search API pour rechercher, filtrer, trier et paginer les données SIM à travers votre flotte.

Principaux cas d’utilisation :

• Créer des tableaux de bord d’inventaire SIM
• Intégrer les données SIM dans des portails clients ou outils internes
• Récupérer les SIM par compte ou groupe

Pour garder votre interface synchronisée, nous recommandons d’utiliser les webhooks liés au cycle de vie de la SIM. Comme de nombreuses actions sont asynchrones (par exemple : il faut quelques minutes pour activer une SIM après l’envoi de l’appel d’activation), vous pouvez vouloir recevoir des événements pour vous informer qu’un changement a été effectué. Les webhooks que vous pouvez recevoir sont détaillés ici.

Ajout et gestion des plans

Pour gérer pleinement les forfaits, vous aurez besoin des API suivantes : – OCS Subscription
C’est l’API principale requise pour le service. Cela vous permettra d’ajouter les bons forfaits de données à vos SIM.

– OCS Inventory
Cette API vous permet de vérifier l’inventaire et le solde restant d’une SIM – si elle contient des plans abonnés, ainsi que tous leurs détails. Utilisez cette API pour afficher le solde restant d’un forfait dans votre propre application ou interface.

– OCS Catalogue
Cette API vous permet de récupérer tous les plans de données disponibles dans notre catalogue. Conseil : pour vérifier les forfaits par emplacement, nous incluons les emplacements couverts dans un ensemble dans le champ « tags », au format ISO-2.

– Événements
OCS : Ce sont les événements Webhook liés au cycle de vie du produit (ex : bundle expiré…). C’est utile pour activer les notifications pour vos utilisateurs finaux, ou dans votre propre interface.

Récupération de l’utilisation des données

Pour suivre l’utilisation de vos cartes SIM, vous pouvez utiliser :

• l’OCS Inventory – pour les SIM utilisant des bundles. Cette API donnera tous les détails sur les forfaits actuellement souscrits sur une SIM, le solde, la date d’expiration…
• l’  API Network Usage – pour toutes les SIM, mais surtout pour les SIM en mode Pay-per-Use. Cette API fournit l’utilisation agrégée des données sur une période de temps spécifique, et peut également filtrer l’utilisation par pays, date…

Glossaire – Valeurs spécifiques à l’API pour les plans IoT Connect Cappped

Comme la documentation de l’API est générique et ne liste pas les valeurs spécifiques à chaque offre, voici tout ce que vous devez savoir :

 mvnoRef : le nom de votre compte, et commence par « M2MA_WW_TSL_….. » Vous pouvez facilement le trouver sur notre plateforme de gestion SIM :

COS : cela fait référence au catalogue de l’offre. Elle est requise lors de la demande du catalogue des plans pour les SIM dans le modèle des plans plafonnés – la valeur pour les comptes de production est WW_M2MA_COS_IOT_CONNECT

Payment : Comme vous – client de Transatel – payez les bundles à Transatel, la valeur à saisir dans les demandes d’abonnement est « customer »

Rateplan
: Cette valeur est requise uniquement si vous envisagez d’utiliser l’API optionnelle de gestion des abonnements. Vous pouvez trouver votre plan tarifaire dans le Plaftorm de gestion de SIM dans le catalogue > options

Le rate plan pour cette offre est M2MA_WW_TSL_IOTCONNECT_CAPPED