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 coûte 3 100 XOF/mois et couvre jusqu’à 10 équipements.

La licence annuelle STARLINK X MikroTik est distincte : elle donne accès aux fonctions MikroTik/VPN/RADIUS compatibles et inclut un mois d’Essentiel. À l’issue de ce mois, l’abonnement mensuel doit rester actif pour conserver les fonctions de suivi et de maîtrise de consommation.

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|chario", "confirm":true } 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.

Quand la réconciliation FedaPay ↔ facture Lago n’est pas activée, le serveur répond 503 SUIVI_PRO_PAYMENT_RECONCILIATION_UNAVAILABLE et ne crée aucune transaction.

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.