Guide d'intégration pour les plateformes de vente

1. Ouvrir et vérifier le compte

• Inscrivez-vous, puis « Vérifier mon compte » : type de compte (partenaire : accès sans plafond ; entreprise : plafond d'appareils réglé par mbelon), informations de la société, six documents. Le titulaire doit être le dirigeant.
• Tant que le compte n'est pas vérifié, aucun appareil ne peut être enregistré et aucune recharge n'est possible.
• Après la vérification, votre compte fonctionne en mode test ; la demande de production se fait dans le menu Intégration.
• En mode test : 2 appareils au plus, réellement verrouillés, sans aucun débit. Quand mbelon approuve la production, les appareils et contrats de test sont supprimés : enregistrez de nouveau vos vrais appareils.
• Les comptes partenaire et entreprise ont des tableaux de bord séparés. Le compte partenaire a l'intégration par API. Le compte entreprise (appareils de son propre personnel) n'a pas l'API par défaut : il travaille dans le portail (Flotte, Modèles, Ajouter un appareil) et peut cliquer sur « Demander l'accès aux API » ; une fois l'accès accordé par mbelon, des clés peuvent être créées. Tant qu'il ne l'est pas, tout appel à l'API répond 403 API_ACCESS_NOT_ENABLED. Les deux types utilisent le même portefeuille prépayé.

2. Alimenter le portefeuille

• Chaque appareil enregistré coûte le prix annuel × la durée choisie (1 à 6 ans), débité immédiatement. Aucun remboursement.
• Rechargez par Mobile Money ou carte dans le menu Portefeuille. Le crédit n'arrive qu'après confirmation du paiement.
• Sans solde suffisant, l'enregistrement est refusé (402) : surveillez GET /wallet.

3. Enregistrer l'appareil à la vente

• Appelez POST /devices/bind avec le contrat, l'IMEI, vos références et la durée. Conservez access_number.
• Faites enrôler le téléphone : le client scanne le QR code de l'appareil (portail) ou utilise le code général avec l'IMEI.
• Activation par code court : pour chaque appareil, le portail donne un code court (12 caractères, affiché XXXX-XXXX-XXXX), valable 24 heures et utilisable une seule fois. Vous ou le client pouvez aussi choisir un mot de passe d'activation (5 à 12 lettres ou chiffres, unique, valable 24 heures, utilisable une seule fois) à côté du code. Le client tape le code ou le mot de passe dans l'application : aucune adresse à saisir. L'ancien code long reste disponible.
• Un enrôlement raté est à la charge du client : aucun remboursement. Le portail indique la dernière tentative et sa raison.
• Tout peut se faire par l'API : GET /devices/:reference/enrollment renvoie le QR code (image PNG en base64, contenu et adresse) et l'état ; POST .../enrollment/activation-code et .../activation-password donnent les codes courts ; POST .../enrollment/command donne la commande pour l'ordinateur. Webhooks utiles : device.enrolled, device.enroll_failed, device.enroll_expired.

4. Suivre les paiements du client

• À chaque échéance payée : POST /contracts/update-status avec ACTIVE (et valid_until ou paid_duration).
• À chaque échéance manquée : OVERDUE. Le téléphone se verrouille à sa prochaine connexion.
• Surveillez le champ command de la fiche pour savoir si l'ordre est arrivé et appliqué, ou abonnez-vous aux webhooks.

5. Fin du contrat

• Dernier paiement : POST /contracts/update-status avec PAID_OFF : l'appareil est libéré définitivement (tout de suite s'il est joignable, sinon à sa prochaine synchronisation). L'action LIBERATE donne le même résultat avec un ordre immédiat, mais elle n'est pas obligatoire.
• Le contrat de service mbelon prend fin à son terme : passé ce terme, mbelon ne verrouille ni ne libère de lui-même.
• Un appareil libéré peut être revendu : il suffit de l'enregistrer de nouveau.

6. Plusieurs vendeurs

Votre plateforme a plusieurs vendeurs ? Chacun peut travailler seul par l'API, sans jamais ouvrir le portail mbelon et sans voir les appareils des autres.

• Activez le mode vendeur strict (menu Intégration), ou créez une clé par vendeur avec le droit devices:read, devices:write et devices:control seulement, liée à ce vendeur.
• Chaque appel annonce son vendeur par l'en-tête X-Mbelon-Seller (inutile avec une clé liée). L'appareil créé porte ce vendeur ; un appareil d'un autre vendeur répond 404.
• Stockez le numéro d'accès de chaque appareil : il remplace l'IMEI dans tous les appels du vendeur.
• Le vendeur peut tout faire sur ses appareils : enregistrer, obtenir le QR code et les codes d'activation (GET /devices/:reference/enrollment), verrouiller, déverrouiller, déclarer perdu, volé ou retrouvé, localiser, ajouter un compte Google de protection. Il ne règle pas les restrictions du téléphone.
• Un seul portefeuille : celui du compte. Si votre plateforme débite déjà chaque vendeur à l'enregistrement d'un appareil, gardez cette logique chez vous : quand mbelon répond 402 INSUFFICIENT_BALANCE, affichez la même erreur au vendeur et rien n'est enregistré.
• Le vendeur n'a pas à savoir que mbelon existe : il ne voit que votre plateforme et l'application du téléphone. Les boutons d'action sont adaptés à l'état de l'appareil (un appareil verrouillé ne peut plus être verrouillé de nouveau ; la localisation reste toujours possible).
• Pour les comptes Google de protection après remise à zéro, le vendeur peut ajouter les siens à l'enregistrement (frp_account_ids) : ils s'ajoutent à ceux de mbelon et du partenaire.

7. Bonnes pratiques

• Signez toujours le JSON exact envoyé.
• Utilisez Idempotency-Key pour les enregistrements : une panne réseau ne doit jamais payer deux fois.
• Traitez chaque webhook une seule fois, d'après son identifiant X-MBELON-DELIVERY.
• Gardez vos secrets côté serveur ; régénérez-les en cas de doute (menu Intégration).

8. Protéger les appareils avant la mise en production

• Portail > Réglages : renseignez les comptes Google autorisés après une remise à zéro (identifiants numériques, cinq au plus). Essayez d’abord sur un appareil de test : un identifiant faux peut bloquer l’appareil pour tout le monde.
• Enrôlez un appareil de test, puis ouvrez sa rubrique « Protection » : visez 100 (Élevée) et aucun point à corriger.
• Vérifiez sur l’appareil : la remise à zéro depuis les réglages est bloquée, le mode développeur est inaccessible, l’application ne peut pas être désinstallée.
• Pour une réparation, ouvrez le mode atelier (durée limitée) : les protections reviennent toutes seules à la fin.
• Surveillez GET /fleet : counts.low_protection doit rester à 0. Les codes de protection_gaps disent quoi faire (voir la documentation de l’API).

9. Recettes par type de plateforme

Quelle que soit votre plateforme, le principe est le même : un événement chez vous déclenche un appel signé vers mbelon, et les webhooks de mbelon reviennent chez vous.

• Pour savoir ce que le téléphone a fait, abonnez-vous aux webhooks ou lisez le champ command de l’appareil.
• Traitez chaque webhook une seule fois, d’après son identifiant X-MBELON-DELIVERY.
• Un appareil verrouillé garde le numéroteur par défaut (appels et codes de forfait) ; réglez-le avec lock_allow_dialer, lock_allowed_packages, lock_allow_play_store et disable_outgoing_calls (documentation de l’API).
• Un compte Google de protection propre à un vendeur : frp_account_ids à l’enregistrement ou PUT /devices/:reference/frp-accounts.

10. Problèmes fréquents et réponses