hub-dago-sdk 1.0.0

SDK Officiel Python pour la Passerelle Echangeur Mobile Money API

🌐 Mobile Money Payment Hub API

Passerelle de paiement hybride (Matériel/Logiciel) en Python / FastAPI pour automatiser les transactions Mobile Money (MVola, Orange Money, Airtel Money) et transformer des modems GSM physiques en une API de niveau E-Commerce (type Stripe).

Ce projet permet à un Administrateur de gérer des puces SIM physiques via des Modems USB, et à des Partenaires E-Commerce d'initier des paiements clients depuis leurs sites Web ou applications mobiles, le tout avec une Developer Experience poussée et une architecture hautement résiliente.

---

🛠️ 1. Technologies & Prérequis

• Python : Python 3.10+ (Recommandé: 3.11 ou 3.12)
• Framework Web : FastAPI & Uvicorn (Très haute performance, requêtes asynchrones)
• Base de Données : SQLite 3 avec mode WAL (Write-Ahead Logging) via SQLAlchemy ORM
• Communication Matérielle : PySerial (Dialogues AT et Sérialisation USB/COM)
• Sécurité : Passlib (Bcrypt) pour les mots de passe, python-jose pour les JWT, cryptography (Fernet) pour le chiffrement militaire AES-128 des codes PIN.

---

⚙️ 2. Installation & Configuration

A. Récupération et Environnement virtuel

# 1. Cloner le projet (si hébergé sur Git) ou ouvrir le dossier Echangeur
cd API-Mobile-Banking-main

# 2. Créer l'environnement virtuel Python
python -m venv venv

# 3. Activer l'environnement virtuel
# Sur Windows :
venv\Scripts\activate
# Sur Linux / macOS :
source venv/bin/activate

# 4. Installer les dépendances
pip install -r requirements.txt

B. Fichier de Configuration (.env)

Créez un fichier .env à la racine du projet avec les variables suivantes :

# Sécurité (OBLIGATOIRE)
JWT_SECRET_KEY=votre_cle_super_secrete_longue_et_aleatoire
# CORS de production (Laissez vide ou * en dev)
CORS_ORIGINS=https://votre-site.com,http://localhost:3000

---

🚀 3. Démarrage (Seed & Serveur)

Étape 1 : Créer le compte Super-Admin

Afin de pouvoir se connecter au futur Dashboard Web, créer le premier compte :

python seed_admin.py
# (Entrez un username et un mot de passe fort quand demandé)

Étape 2 : Démarrer le Hub

Lancez l'application en utilisant le gestionnaire principal :

python start.py

Le serveur expose désormais ses routes sur http://localhost:8000. Vous pouvez consulter la documentation OpenAPI générée dynamiquement sur : http://localhost:8000/docs

---

📖 4. Scénarios (Under the Hood) : Ce que fait le code

🔄 Scénario A : Le Bouton "Power" (Le Lifecycle Démarrage)

Que se passe-t-il exactement quand on exécute start.py ?

1. Événement create_lifespan : La fonction dans app/utils/lifecycle.py est appelée.
2. Setup Base de Données : SQLAlchemy s'assure que toutes les tables SQLite sont créées et que le mode WAL est activé pour les accès simultanés.
3. Auto-Discovery Matériel (Thread 1) : Le ModemPool scanne tous les ports USB/COM de l'ordinateur en arrière-plan. Il injecte la commande AT+CIMI sur tout port qui s'annonce comme Serial. Il identifie la puce (MVola, etc.) puis trouve le numéro de téléphone (AT+CNUM ou requête USSD). Si réussi, la puce est Auto-Enregistrée dans la base de données.
4. Allumage du Radar (Thread 2) : Le RadarService s'active. Le "SMS Listener" rentre dans une boucle infinie de 5 secondes pour lire automatiquement tous les SMS qui entrent sur chaque modem sain.
5. Démarrage FastAPI : Le serveur Web REST commence à écouter sur le port 8000.

💸 Scénario B : Initier un Paiement (Debit Client)

L'application E-commerce appelle la route /transaction/envoi/debiterClient/.

1. Auth & Contrôleur : FastAPI valide le Header X-API-Key. Il route l'appel vers TransactionController.
2. Idempotency Check : Le MobileMoneyService vérifie si la variable idempotency_key existe déjà en BD. Si oui (double-clic d'un client), la requête est rejetée en 2 millisecondes, protégeant l'E-Commerce.
3. Sandbox Check : Si test_mode=True, le système saute l'étape matérielle et passe la transaction virtuelle en REUSSIE.
4. Appel USSD (AT) : Si c'est un vrai paiement, le service demande d'abord au ModemPool un modem valide via la règle "Round-Robin" (Load Balancing pour équilibrer la charge entre plusieurs puces MVola).
5. Déchiffrement : Le Hub utilise la clé matérielle Fernet (AES) pour déchiffrer le code PIN enregistré en BD et le passe au modem.
6. Statut EN_ATTENTE : L'API crée la ligne dans SQlite (status=EN_ATTENTE) et retourne immédiatement une réponse 200 OK à l'E-Commerce. L'E-commerce affiche "Veuillez entrer votre code secret sur votre téléphone" au client final.

📡 Scénario C : Le Matching Radar (La magie du Webhook E-commerce)

Le client final tape son PIN sur son téléphone. Un SMS de "Vous avez payé 50 000Ar au marchand" arrive sur la sim.

1. SMS Listener : À la seconde qui suit, le thread du RadarService aspire le SMS en mémoire via la commande AT+CMGL="ALL".
2. Regex Intelligence : Le Hub nettoie le SMS et applique des Regex strictes et anti-fraude (r'\b([0-9\s\.,]+)\s*(?:Ar|MGA)'). Il extrait que c'est un "Dépôt/Paiement" de 50.000 Ar par le numéro 034 XX XX XXX.
3. Recherche de Transaction : Le Hub fouille dans SQLite. Il cherche une transaction EN_ATTENTE correspondant à 50.000 Ar et venant de ce Téléphone.
4. Match et Trigger Webhook : Une correspondance parfaite est trouvée. Le Hub met à jour la ligne en REUSSIE.
5. Thread Webhook : Le Hub regarde à quel marchand (Partenaire) appartient cette transaction et lit son webhook_url ou son callback_url_dynamic. Un Thread (requests.post) est tiré, avec une signature cryptographique HMAC (X-Webhook-Signature).
6. Site E-commerce : Le serveur du marchand reçoit la notification HTTP, valide la signature cryptographique, et envoie le ticket (Avion/Cinéma/Colis) à son client sur son site web !
7. Orphan Catcher (Anti-DDoS) : Si le Radar trouve ce SMS mais qu'il ne matche aucune transaction EN_ATTENTE légitime (attaque sociale ou erreur de transfert), le SMS de l'argent est sauvegardé sous statu EN_LITIGE. Ainsi la mémoire physique de la carte SIM est purgée de ce spam et elle reste performante et vide à tout moment (Auto-Suppression).

---

👔 5. Interface d'Administration (L'Opérateur du Hub)

L'administrateur gère l'infrastructure à haut-niveau.

Les Fonctionnalités de l'Administrateur

1. Lister et Assigner des Puces (/operateurs) : Configurer les Regex (codes USSD : Solde, Envoi, Débit) de chaque puce détectée automatiquement.
2. Gestion de Clés E-commerce (/api-keys/create) : Vendre des accès au Hub. L'administrateur crée un "Partenaire" (ex: Jumia Madagascar) et génère une API_KEY.
3. Supervision Temp-Réel (/supervision/modems) : Savoir quelles puces sont tombées en panne. Relancer une recherche à chaud des modems (/rescan-modems).
4. Audit Transactionnel (/transaction/list/all) : L'administrateur voit l'argent de TOUS les marchands qui transite sur sa flotte matérielle.
5. Retry 1-Click (/transaction/{id}/retry) : Un envoi est resté bloqué pour erreur réseau ? L'admin clique sur Retry, le Hub réinjecte exactement le même code USSD, depuis la MEME puce (historique tracé sans perte).
6. Lire SMS Morts (/sms/getSms) : Permet de gérer la boite de réception physique pour du dépannage manuel.

---

🛒 6. Fiche Produit : Fonctionnalités pour L'Intégration B2B / E-Commerce

Les développeurs clients (les sites E-commerce partenaires) bénéficieront des standards FinTech les plus aboutis à l'heure actuelle, via le SDK fourni (demo_ecommerce_sdk.py).

Fonctionnalité E-Commerce	Description B2B	Route API
Sandboxing (Mode Test)	Les développeurs peuvent coder l'entièreté de l'intégration checkout en simulant l'argent de faux clients, vérifiant ainsi leur code de backend en 1 journée, sans vider un seul centime sur les puces du hub.	POST /sandbox/simulate
Idempotency Engine	Impossibilité absolue de double-débiter le compte d'un client ou de le rembourser deux fois par accident ou lag de bouton.	Header: X-Idempotency-Key
Multitenant Webhooks	Signature forte (HMAC) envoyant une confirmation PUSH en temps réel au serveur du marchand. Supporte les environnements massifs (le marchand route sa transaction A vers un webhook 1, et sa transaction B vers le webhook 2).	Mécanisme Interne (Radar)
Double Assurance (Fallback)	En cas de panne de l'opérateur sur le Push USSD (pas de pop-up), le client peut envoyer l'argent manuellement. Le Hub rattrape le SMS et valide la commande E-commerce comme si de rien n'était.	Intégration Radar
Accumulation (Paiement Partiel)	Tolérance à l'erreur humaine. Le client devait 50,000 Ar mais envoie 10,000 Ar par erreur. Le Hub stocke les sommes, passe en statut PAIEMENT_PARTIEL et notifie le marchand, jusqu'à l'atteinte des 50,000.	Mécanisme Interne (Radar)
Hub Auto-Refund (Trop Perçu)	L'intelligence ultime : Si un client envoie 60,000 au lieu de 50,000, le Radar valide le panier et déclenche un thread matériel invisible qui rend instantanément la monnaie (les 10,000 de différence) au client, sans aucun code côté e-commerce.	Thread Auto-Refund
Abandon Panier (Cancel)	Timeout du Panier e-commerce = Destruction de la transaction. L'inventaire E-commerce se libère instantanément et de façon sécurisée (même si le client paie tardivement).	POST /transaction/cancel
Remboursement Direct	En cas d'erreur de délivrance de la marchandise (cinéma/Billet avion), un seul endpoint e-commerce permet de déclencher l'envoi physique sur la puce source pour re-créditer le client en 8 secondes.	POST /transaction/refund
Réconciliation (Summary)	Les comptables de chaque marchand partenaires obtiennent leur rapport journalier exact en volume et monnaie.	GET /transaction/summary

🛡️ Sûreté, Code et Robustesse

Le socle Python qui porte ces route a été conçu pour du Zéro Défaillance :

• SQLite en config Write-Ahead Logging pour le Concurrency Multithreading sans Deadlocks (Pas de database locked).
• Code PIN des marchands hashé en un format Militaire AES (Fernet).
• Anti-DDoS sur l'interface de Connexion d'Aministration (Double verrou IP et Username).
• Disparition de la latence de 10 secondes due au polling USSD : Implémentation du Fast-Path lors de l'exécution des ordres USSD.
• Implémentation complète et documentée d'un Anti-Spam mémoire (Garbage Collector Hardware).

Il s'agit du nec-plus-ultra de l'automatisation financière matérielle.

---

💻 7. Exemples d'Intégration Code (Snippets)

Voici comment vos partenaires (développeurs E-Commerce) vont utiliser votre API dans la vraie vie.

A. Lancer un paiement (Debiter Client)

Ce code est exécuté par le serveur web du marchand lorsqu'un client clique sur "Payer".

import requests
import uuid

API_URL = "http://api.votre-hub.com"
API_KEY = "votre_cle_partenaire_generee_par_admin"

# La requête pour débiter le client
response = requests.post(
    f"{API_URL}/transaction/envoi/debiterClient/1", # '1' = ID de l'opérateur (MVola, etc.)
    headers={
        "x-api-key": API_KEY,
        "X-Idempotency-Key": str(uuid.uuid4()) # Anti Double-Clic
    },
    json={
        "phone": "0341122233",
        "montant": 50000,
        "external_ref": "CMD-2024-88A",
        "callback_url": "https://mon-eshop.com/webhooks/paiements",
        "test_mode": False
    }
)

print(response.json())

B. Le WebHook (Recevoir la confirmation)

Le Hub appellera le callback_url de votre partenaire en temps réel (Push).

// Exemple en NodeJS (Express) sur le serveur du Marchand E-commerce
app.post('/webhooks/paiements', (req, res) => {
    const signature = req.headers['x-webhook-signature'];
    const timestamp = req.headers['x-webhook-timestamp'];
    
    // Validation cryptographique
    const isValid = verifyHmac(req.rawBody, signature, timestamp, "MON_SECRET_WEBHOOK");
    if (!isValid) return res.status(403).send("Hacker détecté");

    const paiement = req.body;
    
    if (paiement.status === "REUSSIE") {
        console.log(`[SUCCÈS] Commande payée intégralement !`);
        
    } else if (paiement.status === "PAIEMENT_PARTIEL") {
        console.log(`[ATTENTION] Le client a envoyé ${paiement.montant_paye} sur ${paiement.montant_attendu}.`);
        
    } else if (paiement.status === "TROP_PERCU") {
        console.log(`[BONUS] Trop d'argent reçu. Validation, le Hub rembourse le reste automatiquement !`);
    }
    
    res.send("Webhook reçu");
});

C. Mode Sandbox (Simulation de Test)

Pour que les développeurs testent sans argent réel.

# 1. Créer une transaction (test_mode=true)
curl -X POST "http://api.votre-hub.com/transaction/envoi/debiterClient/1"      -H "x-api-key: PARTNER_KEY"      -H "Content-Type: application/json"      -d '{"phone": "0340000000", "montant": 10000, "test_mode": true}'

# 2. Simuler que le faux client a tapé son code PIN
curl -X POST "http://api.votre-hub.com/transaction/sandbox/simulate-payment/sandbox-uuid"      -H "x-api-key: PARTNER_KEY"

---

👑 8. Guide d'Administration (Pour le Propriétaire du Hub)

Si vous êtes le propriétaire du Hub, vous devez fournir des accès à vos marchands E-commerce. Tout se fait via vos routes d'administration (protégées par votre token de connexion Admin).

A. Autoriser un nouveau Partenaire (Créer une API Key)

Pour intégrer un nouveau partenaire commercial (ex: Cinema Paradiso), vous (l'administrateur) devez faire un appel réseau vers votre Hub pour lui créer un compte E-Commerce.

Méthode API : POST /api-keys/create
Header Requis : Authorization: Bearer <VOTRE_TOKEN_ADMIN_OBTENU_AU_LOGIN>

Corps de la Requête (JSON) :

{
  "app_name": "Cinema Paradiso",
  "permissions": ["debiter", "envoi", "solde"],
  "webhook_url": "https://backend.cinema.mg/api/v1/payment-callback",
  "webhook_secret": "CLE_SECRETE_PARTAGEE_POUR_LA_SIGNATURE_HMAC"
}

Note sur le Webhook :

• webhook_url : C'est ici, lors de la création du compte !! Le lien permanent du serveur de votre Partenaire où le Radar l'avertira des paiements.
• webhook_secret : Un mot de passe aléatoire que vous lui donnez en main propre. Son serveur s'en servira pour vérifier cryptographiquement (HMAC) que le webhook vient bien de vous, et pas d'un hacker. (Ceci sert pour prouver l'authenticité de l'expéditeur).

Réponse du Serveur :

{
  "status": "succes",
  "message": "Clé API générée",
  "app_name": "Cinema Paradiso",
  "api_key": "apk_ab12cd34ef56gh78ij..."
}

[!IMPORTANT] L'API générera un jeton api_key commençant par apk_. Vous devez transmettre cette clé à votre partenaire de façon chiffrée ou en personne. Le partenaire devra l'envoyer dans le Header X-API-Key à chaque fois qu'il contactera le Hub, sans quoi FastAPI rejettera ses requêtes !

---

📦 9. Installation du SDK Officiel (PyPI / GitHub)

Pour une intégration Zéro-Crash avec gestion de micro-coupures réseau et exceptions personnalisées, n'utilisez pas de requêtes manuelles. Utilisez notre librairie officielle.

Installation via GitHub (Gratuit / Privé) :

pip install git+https://github.com/votre-nom/API-Mobile-Banking.git

Utilisation dans votre code :

from echangeur_sdk import MobileMoneyPaymentGateway, HubConnectionError, HubAPIError

try:
    gateway = MobileMoneyPaymentGateway("http://api.votre-hub.com", "votre_cle_api")
    response = gateway.initier_paiement(
        phone="0340000000",
        montant=50000,
        order_id="CMD-123",
        idempotency_key="idemp_123"
    )
    print("Paiement initié :", response)

except HubConnectionError as e:
    print("SERVEUR CASSÉ OU COUPURE INTERNET HUB :", e)
    # L'e-commerce peut dire "Veuillez réessayer dans 5 minutes".
    
except HubAPIError as e:
    print(f"Erreur Métier [{e.status_code}] :", e.message)
    # L'e-commerce peut dire "Le numéro de téléphone est invalide".