Guide de l’API

1. Vos deux secrets

Il vous faut deux secrets : une clé d’API (envoyée dans X-MBELON-API-KEY) et un secret de signature (pour signer chaque appel et vérifier nos notifications). Dans votre portail, ouvrez Intégration : le Coffre de clés vous montre les deux chaque fois que vous en avez besoin, une fois que vous avez créé votre propre code de 4 à 8 chiffres. « Renouveler la clé et le secret » les remplace si l’un est perdu ou divulgué : les anciens cessent de marcher aussitôt. Le compte bac à sable a sa propre paire pour les essais.

2. Signez chaque appel

Envoyez trois en-têtes : X-MBELON-API-KEY (votre clé), X-MBELON-TIMESTAMP (heure Unix en secondes, à moins de 5 minutes de l’heure réelle) et X-MBELON-SIGNATURE (HMAC-SHA256 hexadécimal de l’horodatage, d’un point et du corps exact de la requête, avec votre secret).

Exemple (Node.js)

const crypto = require('crypto');

const body = JSON.stringify({ external_contract_id: 'C-1001', contract_status: 'OVERDUE' });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = crypto
  .createHmac('sha256', process.env.MBELON_SECRET)
  .update(timestamp + '.' + body)
  .digest('hex');

await fetch('https://mbelon.top/api/v1/contracts/update-status', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-MBELON-API-KEY': process.env.MBELON_API_KEY,
    'X-MBELON-TIMESTAMP': timestamp,
    'X-MBELON-SIGNATURE': signature,
  },
  body,
});

3. Enregistrer un appareil et son contrat

POST /api/v1/devices/bind avec external_contract_id, device_type et device_imei_1 (ou device_serial pour les tablettes sans SIM, télévisions et boîtiers). Facultatif : policy_name pour choisir un profil de règles.

4. Envoyer les événements de paiement

POST /api/v1/contracts/update-status avec external_contract_id et contract_status : ACTIVE déverrouille, OVERDUE verrouille (ajoutez lock_level SOFT pour d’abord appliquer des restrictions légères), PAID_OFF libère définitivement l’appareil.

Durée payée, échéance et montant

Avec contract_status ACTIVE, vous pouvez envoyer paid_duration {"value": 24, "unit": "hours" ou "days"} et, si vous voulez, starts_at. La nouvelle durée s’ajoute à la fin de la période en cours, l’échéance revient dans valid_until, et le téléphone se verrouille à cette heure exacte, même hors ligne. Vous pouvez aussi envoyer valid_until avec lock_at_valid_until: true. Ajoutez amount_due pour afficher le montant dans les rappels de paiement (5 par jour, à partir de 7 jours avant l’échéance). Sans ces champs, rien ne change pour vous.

Actions sur un appareil : verrouiller, déverrouiller, perdu, volé

POST /api/v1/devices/:reference/action avec action : FORCE_LOCK, FORCE_UNLOCK, LIBERATE, PING, REPORT_LOST, REPORT_STOLEN ou REPORT_FOUND. Un appareil déclaré perdu ou volé reste verrouillé, avec un message adapté sur son écran, et ne peut pas être déverrouillé tant que vous ne le déclarez pas retrouvé.

Règles de sécurité

Une requête signée qui modifie quelque chose n’est acceptée qu’une seule fois avec la même signature : signez chaque nouvel essai avec un nouvel horodatage, ou envoyez un en-tête Idempotency-Key (8 à 64 caractères) sur devices/bind et contracts/update-status, pour qu’un nouvel envoi rende la même réponse sans refaire l’action. Dans Intégration, vous pouvez lister les adresses de serveur autorisées à utiliser votre clé. Des limites de débit s’appliquent. Les erreurs portent un code stable et un message dans la langue de l’en-tête Accept-Language.

Préparer les téléphones en boutique

Dans Intégration, téléchargez l’outil de boutique pour Windows, Linux ou macOS. Déclarez d’abord chaque IMEI : l’outil installe mbelon sur un téléphone branché par câble, en fait le propriétaire de l’appareil et confirme l’enrôlement. Il parle à POST /api/v1/shop/prepare et /api/v1/shop/status avec la clé de votre QR code du partenaire. Son fichier contient cette clé : gardez-le privé.

5. Lire vos données

GET /api/v1/devices liste vos appareils (paramètres q et filter). GET /api/v1/devices/:reference montre un appareil. Les profils de règles sont sous /api/v1/policies.

6. Recevoir les notifications

Indiquez l’adresse de notification dans la section Intégration. Événements : device.enrolled, device.locked, device.unlocked, device.released, device.tamper, device.offline. Chaque appel porte X-MBELON-TIMESTAMP et X-MBELON-SIGNATURE, calculés comme les vôtres.

7. Mode test

Un nouveau compte est en mode test : 2 appareils réels au maximum. Quand vous êtes prêt, demandez à l’administrateur de passer en production.

8. Page pour vos clients

Vos clients voient l’état de leur contrat et comment payer sur la page d’état, avec leur numéro de contrat et les 4 derniers caractères de l’IMEI ou du numéro de série.

Ouvrir la page d’état du client