API Mobile V2 — À partir du 31 octobre 2026, les commandes sur une version d'offre obsolète seront refusées

🚧

Action requise avant le 31/10/2026

À partir du 31 octobre 2026, toute commande de ligne mobile (POST /subscriptions) ou de recharge data qui contient un product_version_id qui n'est plus la version en vigueur de l'offre sera refusée.

Si votre intégration utilise un product_version_id fixe (codé en dur, en configuration ou en base de données), vos commandes échoueront à partir de cette date. Merci de lire ce qui suit.

Pourquoi ce changement ?

Nos offres mobiles évoluent : un prix change, un volume de data est ajusté, une option est ajoutée… À chaque évolution, une nouvelle version de l'offre est publiée avec un nouveau product_version_id, et l'ancienne version devient obsolète.

Aujourd'hui, certaines intégrations envoient toujours le même product_version_id, récupéré une fois pour toutes lors de la mise en place. Leurs commandes restent donc sur une ancienne version de l'offre :

• les nouveaux tarifs ne sont pas appliqués, ce qui crée des écarts entre ce que vous pensez commander et ce qui est facturé ;
• les évolutions de l'offre (quotas, options) ne vous parviennent pas ;
• vos équipes et les nôtres perdent du temps à expliquer et régulariser ces écarts.

Pour garantir que chaque commande porte les conditions en vigueur, nous n'accepterons plus que la version courante des offres.

Ce qui change concrètement

Seules les nouvelles commandes sont concernées.

Comprendre les identifiants

Quand vous appelez GET /products, chaque produit renvoyé contient plusieurs identifiants. Ils ne jouent pas tous le même rôle :

📘

La règle d'or

Un product_version_id est une donnée à lire, pas une donnée à stocker. Ne mémorisez pas quel identifiant utiliser : mémorisez quelle offre vous voulez (par exemple son sku), puis demandez à l'API l'identifiant en vigueur au moment de commander.

La bonne implémentation, étape par étape

❌ Ce qu'il ne faut pas faire

// L'identifiant a été copié une fois pour toutes : il deviendra obsolète
// à la prochaine évolution de l'offre, et la commande sera refusée.
const PRODUCT_VERSION_ID = "3f2b...-...";

await api.post("/subscriptions", {
  product_version_id: PRODUCT_VERSION_ID,
  variant_id: "a81c...",
  // ...
});

✅ Ce qu'il faut faire

Étape 1 — Récupérer le catalogue en vigueur

GET /products

La réponse contient toujours les versions courantes de nos offres, avec leurs identifiants à jour :

[
  {
    "product_version_id": "9c41e2d0-...",
    "name": "Forfait Mobile Pro",
    "variants_or_pfs": [
      {
        "variant_id": "b7a3...",
        "sku": "MOB-PRO-50GO",
        "quota_label": "50 Go",
        "pricing": { "recurring_price": 12.50, "access_fee": 0 }
      }
    ],
    "options": [ ... ]
  }
]

Étape 2 — Retrouver l'offre souhaitée grâce à une référence stable

Parcourez la réponse pour trouver la déclinaison qui correspond à votre référence (par exemple le sku MOB-PRO-50GO) et lisez les identifiants du moment : product_version_id, variant_id, et le cas échéant option_id / option_variant_id.

Étape 3 — Commander avec ces identifiants

POST /subscriptions

{
  "product_version_id": "9c41e2d0-...",
  "variant_id": "b7a3...",
  "external_reference": "CMD-2026-00042",
  "customer": { "name": "ACME SAS", "company_number": "12345678900012" },
  "sim_card": "esim"
}

Exemple complet

async function commanderLigne(skuSouhaite, commande) {
  // 1. Catalogue en vigueur
  const produits = await api.get("/products");

  // 2. Recherche de l'offre par sa référence stable
  for (const produit of produits) {
    const variantes = Array.isArray(produit.variants_or_pfs) ? produit.variants_or_pfs : [];
    const variante = variantes.find((v) => v.sku === skuSouhaite);

    if (variante) {
      // 3. Commande avec les identifiants du moment
      return api.post("/subscriptions", {
        ...commande,
        product_version_id: produit.product_version_id,
        variant_id: variante.variant_id,
      });
    }
  }

  throw new Error(`Offre ${skuSouhaite} introuvable dans le catalogue en vigueur`);
}

Et si je mets le catalogue en cache ?

C'est possible, à deux conditions :

1. Une durée de cache courte : quelques heures maximum. Idéalement, appelez GET /products juste avant chaque commande : l'appel est léger.
2. Rafraîchir le cache si une commande est refusée : si une commande est rejetée parce que la version est obsolète, rechargez GET /products puis relancez la commande avec les nouveaux identifiants.

💡

Bon réflexe : si votre outil présente le prix à vos utilisateurs avant la commande, affichez celui renvoyé par GET /products (pricing). Ainsi, vos équipes voient toujours le tarif réellement appliqué.

Les recharges data sont aussi concernées

Le principe est le même pour les recharges :

1. GET /subscriptions/{subscription_id}/mobile_data_top_up/products pour obtenir les recharges disponibles et leurs identifiants en vigueur ;
2. POST /subscriptions/{subscription_id}/mobile_data_top_up avec le product_version_id et le variant_id que vous venez de récupérer.

Checklist avant le 31 octobre

• Aucun product_version_id, variant_id ou identifiant d'option n'est codé en dur, en configuration ou stocké durablement en base.
• Chaque commande est précédée d'un appel à GET /products (ou s'appuie sur un cache de quelques heures maximum).
• L'offre souhaitée est identifiée par une référence stable (sku).
• En cas de refus pour version obsolète, votre intégration recharge le catalogue et relance la commande.
• Le même principe est appliqué aux recharges data.

Besoin d'aide ?

Votre Customer Success Manager est disponible pour vérifier votre intégration avec vous.