# 📡 Plateforme API & Passerelles Multi-Canaux (`api/`)

Ce dossier contient l'ensemble des services backend transactionnels ainsi que le Hub central :

- [index.php](file:///c:/workspace/notificationFCM/api/index.php) : **Hub Central & Dispatcher API** renvoyant vers les index de chaque service (Mail, Notif, Paiement, SMS, Geo) via interface graphique, redirection HTTP 302 (`?service=mail|notif|paiement|sms|geo`) ou découverte JSON (`?format=json`).
- [style.css](file:///c:/workspace/notificationFCM/api/style.css) : Feuille de style du tableau de bord.
- [firebase-messaging-sw.js](file:///c:/workspace/notificationFCM/api/firebase-messaging-sw.js) : Service Worker pour le test des notifications push Web.

### 1. `api/public/` (Endpoints publics de l'API)
Points d'entrée REST appelés par les applications clientes, organisés par module :

- **Module Push Notifications (`api/public/notif/`)** :
  - [register_device.php](file:///c:/workspace/notificationFCM/api/public/notif/register_device.php) : Enregistrement et mise à jour d'appareils et tokens FCM.
  - [create_notification.php](file:///c:/workspace/notificationFCM/api/public/notif/create_notification.php) : Création et mise en file d'attente d'une notification push.
  - [notification_status.php](file:///c:/workspace/notificationFCM/api/public/notif/notification_status.php) : Consultation de l'état d'avancement d'une notification.
  - [list_notifications.php](file:///c:/workspace/notificationFCM/api/public/notif/list_notifications.php) : Historique paginé et filtrable des notifications.
  - [index.php](file:///c:/workspace/notificationFCM/api/public/notif/index.php) : Dashboard & console d'administration interactive des push FCM.

- **Module Passerelle SMS B2B (`api/public/sms/`)** :
  - [send.php](file:///c:/workspace/notificationFCM/api/public/sms/send.php) : Envoi SMS sécurisé avec HMAC-SHA256, Nonce, Smart Routing & Circuit Breaker.
  - [batch.php](file:///c:/workspace/notificationFCM/api/public/sms/batch.php) : Envoi groupé de SMS (Bulk).
  - [status.php](file:///c:/workspace/notificationFCM/api/public/sms/status.php) : Statut et suivi de cascade failover.
  - [balance.php](file:///c:/workspace/notificationFCM/api/public/sms/balance.php) : Solde de crédits et quotas.
  - [webhook_dlr.php](file:///c:/workspace/notificationFCM/api/public/sms/webhook_dlr.php) : Réception DLR et dispatch webhook signé.
  - [index.php](file:///c:/workspace/notificationFCM/api/public/sms/index.php) : Dashboard interactif SMS & Studio HMAC.

- **Module Passerelle Email B2B (`api/public/email/`)** :
  - [send.php](file:///c:/workspace/notificationFCM/api/public/email/send.php) : Envoi d'e-mails unitaires transactionnels (SMTP Sockets, Google Workspace, M365, Brevo, SendGrid).
  - [batch.php](file:///c:/workspace/notificationFCM/api/public/email/batch.php) : Envoi d'e-mails en masse et campagnes (Bulk).
  - [status.php](file:///c:/workspace/notificationFCM/api/public/email/status.php) : Suivi détaillé des livraisons, ouvertures et clics.
  - [domains.php](file:///c:/workspace/notificationFCM/api/public/email/domains.php) : Certification et gestion des domaines expéditeurs (SPF / DKIM).
  - [webhook_events.php](file:///c:/workspace/notificationFCM/api/public/email/webhook_events.php) : Réception des événements fournisseurs (DLR, bounces).
  - [index.php](file:///c:/workspace/notificationFCM/api/public/email/index.php) : Dashboard interactif Email & Studio de test en direct.

- **Module Paiements & Escrow Multi-Tenant (`api/public/paiement/`)** :
  - [v1/payments/charge.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/payments/charge.php) : Débit direct standard immédiat (PCI-DSS tokenized).
  - [v1/escrow/hold.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/escrow/hold.php) : Étape 1 : Immobilisation des fonds sous séquestre.
  - [v1/escrow/release.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/escrow/release.php) : Étape 2->3 : Libération des fonds au sous-marchand.
  - [v1/escrow/dispute.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/escrow/dispute.php) : Étape 3 : Déclaration de litige et gel conservatoire.
  - [v1/escrow/refund.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/escrow/refund.php) : Étape 3 : Annulation et remboursement de l'acheteur.
  - [v1/payments/status.php](file:///c:/workspace/notificationFCM/api/public/paiement/v1/payments/status.php) : Consultation de l'état d'une transaction et grand livre comptable.
  - [webhook_gateway.php](file:///c:/workspace/notificationFCM/api/public/paiement/webhook_gateway.php) : Réception des webhooks des passerelles bancaires (Stripe, Adyen).
  - [test_client.php](file:///c:/workspace/notificationFCM/api/public/paiement/test_client.php) : Suite de validation cryptographique et failover.
  - [index.php](file:///c:/workspace/notificationFCM/api/public/paiement/index.php) : Dashboard interactif, studio de test & gestion des circuit breakers.
  - [README_PAIEMENT.md](file:///c:/workspace/notificationFCM/api/public/paiement/README_PAIEMENT.md) : Documentation technique détaillée.

- **Module Géolocalisation & Adresses SaaS (`api/public/geo/`)** :
  - [autocomplete.php](file:///c:/workspace/notificationFCM/api/public/geo/autocomplete.php) : Autocomplétion d'adresses postales en temps réel (BAN, Nominatim, Mapbox, Google).
  - [geocode.php](file:///c:/workspace/notificationFCM/api/public/geo/geocode.php) : Géocodage direct (Adresse texte ➔ Coordonnées GPS latitude/longitude).
  - [reverse.php](file:///c:/workspace/notificationFCM/api/public/geo/reverse.php) : Géocodage inverse (GPS latitude/longitude ➔ Adresse postale complète).
  - [distance.php](file:///c:/workspace/notificationFCM/api/public/geo/distance.php) : Distance vol d'oiseau (formule de Haversine), cap cardinal et estimation routière.
  - [route.php](file:///c:/workspace/notificationFCM/api/public/geo/route.php) : Calcul d'itinéraire complet (OSRM, Mapbox Directions, Google Directions) avec géométrie polyline.
  - [index.php](file:///c:/workspace/notificationFCM/api/public/geo/index.php) : Dashboard SaaS interactif, carte Leaflet temps réel, simulateur de failover & gestionnaire de Circuit Breakers.
  - [doc.php](file:///c:/workspace/notificationFCM/api/public/geo/doc.php) : Référentiel des endpoints et spécifications techniques (avec export `?format=json`).
  - [README_GEO.md](file:///c:/workspace/notificationFCM/api/public/geo/README_GEO.md) : Documentation technique et d'architecture.

### 2. `api/private/` (Classes métier, configuration, cron et base de données)
Logique interne du service de notifications :
- [bootstrap.php](file:///c:/workspace/notificationFCM/api/private/bootstrap.php) : Initialisation de l'environnement, autoloader, connexion DB et CORS.
- [NotificationService.php](file:///c:/workspace/notificationFCM/api/private/NotificationService.php) : Gestion métier des notifications et appareils.
- [FcmClient.php](file:///c:/workspace/notificationFCM/api/private/FcmClient.php) : Client HTTP v1 Firebase Cloud Messaging (OAuth2 JWT).
- [AuthService.php](file:///c:/workspace/notificationFCM/api/private/AuthService.php) : Authentification par clé d'API (`X-API-KEY`).
- [Database.php](file:///c:/workspace/notificationFCM/api/private/Database.php) : Gestionnaire singleton PDO MySQL.
- [Logger.php](file:///c:/workspace/notificationFCM/api/private/Logger.php) : Journalisation des requêtes API et envois.
- **`config/`** : Configuration globale (`config.php`) et clés Firebase (`firebase_credentials/`).
- **`cron/`** : Script worker de traitement d'envoi par lot (`send_worker.php`).
- **`database/`** : Schéma DDL MySQL (`schema.sql`) et données d'exemple (`seed_example.sql`).
- **`debug_file/`** : Journaux de débogage et logs applicatifs (`app.log`, `worker.log`, `api_requests.log`, `fcm_debug.log`).


👉 Pour la documentation technique complète (paramètres, types, en-têtes, exemples cURL et JSON), consultez le document principal : **[API.md](file:///c:/workspace/notificationFCM/API.md)**.

