Contrat API — abonnement mensuel Suivi du Matériel

Base : https://live.jmoai.net/api/v1/clients.

Suivi du Matériel est un abonnement mensuel de surveillance, d’accès aux équipements et de maîtrise de consommation (bridage programmé, adaptatif et ciblé). Ce n’est pas une licence. L’accès est accordé uniquement après encaissement confirmé par webhook. Le palier Essentiel vaut 4 000 XOF/mois et couvre jusqu’à 10 équipements ; une offre en cours le ramène à 3 100 XOF — c’est ce montant qui est débité aujourd’hui.

La licence annuelle STARLINK X MikroTik (25 000 XOF, 12 mois) est distincte : elle donne RADIUS + VPN, la maîtrise de consommation, et inclut un mois d’Essentiel — trois mois pour un client qui possédait déjà une licence MikhmoAI Pro annuelle payée. À l’issue de cette période, l’abonnement mensuel doit rester actif pour conserver les fonctions de suivi et de maîtrise de consommation.

L’avantage cumul MikhmoAI Pro (depuis le 2026-09-01)

Un client qui possède déjà une licence MikhmoAI Pro annuelle payée et qui prend en plus STARLINK X reçoit 3 mois de Suivi du Matériel au lieu d’un : il cumule les deux produits, on lui épargne la réactivation mensuelle.

La durée retenue est écrite dans le registre — metadata.mois_offerts sur l’abonnement, et mois_offerts dans le droit suivi_pro — jamais recalculée après coup. commercial_offer vaut alors CUMUL_MIKHMOAI_PRO_STARLINK_X au lieu de STARLINK_X_MIKROTIK.

⚠️ Une licence Pro de promotion de lancement ou d’essai n’ouvre pas le cumul : seules comptent les licences réellement acquises. L’application ne doit donc pas déduire la durée de la simple présence d’une licence Pro — elle lit mois_offerts.

Le mois offert, en pratique

Il est accordé au moment où la licence est réclamée et ses droits attribués — donc juste après le paiement, sur le même parcours que la licence elle-même. Ce n’est pas un droit annuel : c’est une souscription bornée à 31 jours, visible dans GET /subscriptions/suivi-pro comme un abonnement ACTIVE ordinaire, avec metadata.included_with_license.

Un client qui active sa licence aujourd’hui a donc les deux droits le jour même.
À l’issue de la période offerte, seul l’abonnement mensuel est à renouveler — la licence, elle, court un an.
Une réclamation rejouée n’empile pas les mois : s’il existe déjà un abonnement qui SERT le client (ACTIVE, PAST_DUE, GRACE_PERIOD, CANCEL_AT_PERIOD_END), l’octroi est refusé.
⚠️ Une demande de paiement non encaissée ne bloque plus l’offre. Un checkout Suivi abandonné (PENDING_PAYMENT, PENDING_BILLING_SETUP) était compté comme un abonnement vivant : un acheteur STARLINK X n’a rien reçu le 2026-09-01 pour cette raison, sans la moindre erreur. L’intention est désormais remplacée par l’offre, et un refus laisse toujours une trace dans le journal.
Si le client paie malgré tout ce lien abandonné, le paiement est accepté et le mois acheté démarre à la fin du mois offert : il ne paie jamais deux fois les mêmes jours.
Le mois offert suit le même cycle que le mensuel payant : période, grâce, puis suspension. Il ne peut donc pas laisser un droit éternel derrière lui.

Pour savoir, côté application, si le gérant a la licence et l’abonnement — deux vérifications distinctes —, lire GET /clients/entitlements/bridage, décrit dans CONTRAT-API-BRIDAGE. C’est le seul appel qui répond aussi à un client qui n’a rien acheté.

Prix, offre et remises

Le prix de vente vit dans le catalogue (product_plans), jamais dans le code : c’est la même source que celle lue par la vitrine, pour que le prix AFFICHÉ et le prix DÉBITÉ ne puissent pas diverger. Chaque palier expose donc quatre montants :

Champ	Sens
`base_xof`	le prix de base du palier — 4 000 (Essentiel), 10 000 (Étendu)
`offre_xof`	le montant de l’offre en cours, ou `null` s’il n’y en a pas
`prix_xof`	le montant réellement débité — c’est celui à afficher en gros
`offre_fin`	la date de fin de l’offre, ou `null`

Affichage attendu : 4 000 XOF barré, 3 100 XOF en évidence, et l’échéance de l’offre. Ne jamais recalculer le prix côté application : prix_xof fait foi.

La remise générale de 20 % sur les licences ne s’applique PAS ici, ni aucune autre réduction automatique (playbook marketing, avantage partenaire). Un abonnement mensuel amputé de 20 % l’est à chaque échéance. Seuls un coupon valide ou un code de parrainage explicite peuvent réduire le prix — et dans ce cas c’est la meilleure des deux réductions qui s’applique, jamais leur somme : un code de 500 XOF ne descend pas 3 100 à 2 600, il perd face à l’offre de 900 XOF déjà en place.

Si le palier n’est pas publié au catalogue, le checkout répond 503 SUIVI_PRO_TARIF_INDISPONIBLE plutôt que de deviner un montant. Ce n’est pas une panne de l’application : c’est une offre qui n’est pas encore ouverte à la vente.

Lire l’état

GET /subscriptions/suivi-pro retourne les paliers, le quota réellement appliqué, la licence porteuse et subscription : NONE, PENDING_BILLING_SETUP, PENDING_PAYMENT, ACTIVE, PAST_DUE, GRACE_PERIOD, CANCEL_AT_PERIOD_END, CANCELLED ou SUSPENDED.

Souscrire

POST /subscriptions/suivi-pro avec { "plan_code":"suivi-pro-essentiel" } est une prévisualisation sûre. Pour demander une souscription facturable, envoyer { "plan_code":"…", "confirm":true }. Les réponses PENDING_BILLING_SETUP ou PENDING_PAYMENT ne donnent encore aucun droit : le paiement doit être confirmé côté serveur.

Payer

GET /subscriptions/suivi-pro/payment-methods?plan_code=… retourne les moyens proposés par le Hub pour ce palier. POST /subscriptions/suivi-pro/checkout avec { "plan_code":"…", "provider":"fedapay|geniuspay", "confirm":true }

⚠️ FedaPay et GeniusPay seulement pour l’abonnement mensuel (décision du 30/08/2026). N’affichez pas de choix Chario : le serveur le refuserait par 400 SUIVI_PRO_PAYMENT_PROVIDER_UNAVAILABLE. La liste qui fait foi est celle de GET /subscriptions/suivi-pro/payment-methods — construisez les boutons à partir d’elle, jamais d’une liste écrite en dur. retourne payment_url, payment_transaction_id et subscription_id. Le prix est calculé côté serveur ; l’application ne transmet ni montant, ni identifiant client. Un second appel réutilise l’URL non payée lorsqu’elle existe. En cas d’état externe incertain, l’API renvoie 409 ou 502 SUIVI_PRO_CHECKOUT_PENDING_RECONCILIATION : l’application ne doit pas relancer automatiquement le débit.

promo_code est optionnel. Suivi Pro exclut toutes les remises automatiques, notamment la réduction générale de 20 %. Seuls un coupon valide ou un code de parrainage/revendeur explicite peuvent réduire le prix. Avec un code, Chario n’est pas proposé tant que son checkout externe ne sait pas appliquer ce même coupon.

La réconciliation FedaPay ↔ facture Lago est active depuis le 30/08/2026 : le facturier émet le même montant que celui encaissé (3 100 XOF) et la facture est réglée à la confirmation du paiement. Si elle venait à être refermée, le serveur répondrait 503 SUIVI_PRO_PAYMENT_RECONCILIATION_UNAVAILABLE sans créer aucune transaction — ce n’est pas une panne de l’application, c’est la vente qui est suspendue.

Résilier

DELETE /subscriptions/suivi-pro arrête d’abord la facturation. Si cette confirmation échoue, le service reste actif et l’API refuse la résiliation plutôt que de couper un client qui pourrait encore être facturé.

Garanties

un seul abonnement Suivi Pro vivant par client ;
webhook de paiement idempotent ;
en cas de délai incertain du facturier, le contrat reste en attente et ne peut pas créer un second abonnement ;
période de grâce bornée avant suspension ;
le plafond d’équipements vient du droit actif, jamais du client mobile ;
le mois offert avec la licence est accordé sur le chemin commun d’attribution des droits : aucun parcours d’achat ne peut l’oublier, et son échec n’empêche jamais l’activation de la licence payée.