Intégration API pour Ubigi for Business

Cet article explique comment intégrer nos API pour l’offre Ubigi for Business.

Avant de commencer : lisez Comment intégrer nos API ? pour obtenir vos identifiants et trouver vos profils de service et valeurs techniques dans la plateforme de gestion des SIM. Les liens et références des API sont disponibles sur le Portail Développeurs.

1. Activer vos SIM et gérer leurs services

API : Connectivity Management

Utilisez cette API pour activer, suspendre ou résilier des SIM, modifier leurs services, renseigner les champs de référence et de groupe, et consulter les informations de service d’une SIM.

Recommandé : utiliser les profils de service

Créez ou choisissez un profil de service dans la plateforme de gestion des SIM, puis indiquez sa référence dans la requête d’activation. La SIM reçoit le modèle tarifaire et les services du profil, et apparaît sous ce profil dans l’interface, exactement comme si vous l’aviez activée depuis l’interface.

POST /api/subscribers/sim-serial/{simSerial}/activate
{
  "serviceProfile": "<référence de votre profil de service>",
  "externalReference": "Device-0001",
  "group": "Group A1"
}

💡 Pour modifier les services d’une SIM, attribuez-lui un autre profil de service. La SIM reprend la configuration du nouveau profil et n’est pas marquée comme déviée. Elle reste alignée sur son profil et correctement classée dans l’interface.

Alternative : utiliser un rate plan et des options

Si vous avez besoin d’une configuration spécifique pour chaque SIM, indiquez le rate plan et le libellé technique de chaque option. Vous trouverez tous les rate plans et libellés d’options dans la plateforme de gestion des SIM, dans Catalogue > Options.

Par exemple, pour activer une SIM sur le modèle tarifaire par forfaits avec un compte standard en EUR, activez l’option UBGBUS_REF_BUNDLE avec la valeur on :

{
  "ratePlan": "M2MA_WW_TSL_MWC_1",
  "options": [
    {
      "name": "UBGBUS_REF_BUNDLE",
      "value": "on"
    }
  ]
}

⚠️ Modifier les options d’une SIM une par une la marque comme déviée par rapport à son profil de service dans la plateforme de gestion des SIM. Pour modifier les services sans dévier vos SIM, attribuez-leur plutôt un autre profil de service.

⚠️ Si aucun modèle tarifaire n’est indiqué, la SIM est configurée par défaut en Pay-per-Use Premium Networks.

Bon à savoir :

• Chaque option a une valeur par défaut si vous ne la renseignez pas.
• Certaines options n’acceptent qu’une seule valeur, comme une liste déroulante dans l’interface.

2. Récupérer la liste de vos SIM

API : SIM Search

Recherchez, filtrez, triez et paginez vos SIM. Cas d’usage courants : tableaux de bord d’inventaire, portails clients, outils internes, récupération des SIM par compte ou par groupe, et processus de service client et de diagnostic.

De nombreuses actions sont asynchrones (une activation peut prendre quelques minutes). Abonnez-vous aux événements Connectivity Management (webhooks) pour être notifié des changements de cycle de vie.

3. Ajouter et gérer des forfaits

API	Fonction
OCS Subscription	Ajoute un forfait à une SIM. C’est l’API principale de cette offre.
OCS Inventory	Affiche les forfaits d’une SIM, le statut de souscription et le solde restant, par exemple pour l’afficher dans votre interface.
OCS Catalog	Liste les forfaits disponibles.
OCS Events	Envoie des webhooks lors des événements du cycle de vie des forfaits (par exemple, l’expiration d’un forfait), pour notifier les utilisateurs finaux ou mettre à jour votre interface.

💡 Pour trouver les forfaits par pays, utilisez le champ tags d’OCS Catalog : il liste les pays couverts par chaque forfait, au format ISO-2.

4. Récupérer les informations eSIM

API : SIM Management, endpoint Get eSIM details uniquement

Cet endpoint renvoie le code d’activation, le lien de téléchargement du QR code, le statut de l’eSIM et le statut de l’appareil (utile pour le diagnostic). Les API Reserve et Release ne s’appliquent pas à Ubigi for Business : vos profils sont déjà réservés et libérés.

5. Récupérer la consommation data

• OCS Inventory : détail des forfaits, solde restant et date d’expiration pour les SIM disposant d’un forfait.
• Network Usage : consommation data totale de toutes les SIM sur une période donnée, filtrable par pays et par date. Particulièrement utile pour les SIM en paiement à l’usage.

Glossaire – valeurs pour Ubigi for Business

La documentation API étant générique, elle ne précise pas les valeurs propres à chaque offre. Voici celles à utiliser pour Ubigi for Business.

Valeur	Utilisée dans	Valeur à renseigner
serviceProfile	Connectivity Management (activation, modification de services)	La référence de votre profil de service, dans Catalogue > Profils de service
mvnoRef	API OCS	Le nom de votre compte Ubigi for Business, au format M2MA_WW_TSL_…, visible dans la plateforme de gestion des SIM
COS (Catalog of Services) pour les forfaits	OCS Catalog	Production : WW_COS_UBG_MKP_EUR
payment	OCS Subscription	Customer (en tant que client Transatel, c’est vous qui payez les forfaits)
ratePlan	Connectivity Management (méthode rate plan + options) et API optionnelle Subscriptions Management	Votre rate plan, dans Catalogue > Options (par exemple, M2MA_WW_TSL_MWC_1 pour un compte standard en EUR)

Besoin d’aide ?

Contactez notre équipe support via le Service Desk.