# 📡 Référentiel des APIs REST - Service de Notifications FCM

Ce document récapitule l'ensemble des points de terminaison (endpoints) fournis par l'application, leurs rôles, paramètres, codes d'état HTTP et exemples de requêtes/réponses.

---

## 📋 Tableau Récapitulatif des APIs

| Méthode | Point d'accès (Endpoint) | Rôle & Description | Authentification |
|:---:|---|---|:---:|
| `POST` | `/api/register_device.php` | Enregistre ou met à jour le token FCM d'un appareil (Android / iOS / Web). | `X-API-KEY` |
| `POST` | `/api/create_notification.php` | Crée une notification dans la table MySQL avec le statut `a_envoyer` (ou envoi immédiat). | `X-API-KEY` |
| `GET` | `/api/notification_status.php` | Consulte le statut de traitement et les statistiques d'envoi d'une notification. | `X-API-KEY` |
| `GET` | `/api/list_notifications.php` | Récupère la liste paginée des notifications d'une application avec filtres par statut. | `X-API-KEY` |
| `GET` / `POST` | `/api/private/cron/send_worker.php` | Déclenche l'envoi des notifications en attente (`a_envoyer`) par lot. | Clé secrète `?key=...` |

---

## 🔐 Règles Générales & Authentification

Toutes les requêtes vers l'API (sauf le worker) doivent s'authentifier à l'aide de la clé API de l'application cliente :

- **En-tête HTTP (Recommandé)** :  
  `X-API-KEY: <votre_cle_d_application>`
- **Format d'échange** : `application/json` (UTF-8)
- **CORS** : Les en-têtes `Access-Control-Allow-Origin: *` sont activés pour autoriser les appels depuis des applications web/mobiles.

### Format Standard des Réponses d'Erreur :
```json
{
  "success": false,
  "error": "Description claire de l'erreur survenue",
  "code": 401
}
```

---

## 1. `POST /api/register_device.php`

### 🎯 Rôle
Enregistrer ou rafraîchir le jeton (token) FCM d'un terminal mobile (Android / iOS) ou d'un navigateur Web, et l'associer éventuellement à un compte utilisateur de votre système.
- Si le token existe déjà pour cette application, ses métadonnées (modèle, dernière activité, statut actif) sont mises à jour (`ON DUPLICATE KEY UPDATE`).
- Si l'utilisateur (`external_user_id`) n'existe pas encore pour cette application, il est créé automatiquement.

### En-têtes requis
```http
X-API-KEY: app_ecommerce_key_9f8a7b6c5d4e3f2a
Content-Type: application/json
```

### Paramètres du Corps (Body JSON)
| Champ | Type | Obligatoire ? | Description |
|---|---|:---:|---|
| `fcm_token` | `string` | **Oui** | Le jeton d'enregistrement FCM fourni par le SDK Firebase. |
| `platform` | `string` | Non | `"android"` *(défaut)*, `"ios"` ou `"web"`. |
| `external_user_id` | `string` | Non | Identifiant unique de l'utilisateur dans votre base (ex: `"USER_101"`, `"CLIENT_99"`). |
| `device_model` | `string` | Non | Modèle de l'appareil (ex: `"Samsung Galaxy S22"`, `"iPhone 14"`). |
| `app_version` | `string` | Non | Version de l'application cliente (ex: `"1.2.0"`). |

### Exemple de Requête
```json
{
  "fcm_token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvdmExAmPl3...",
  "platform": "android",
  "external_user_id": "USER_101",
  "device_model": "Google Pixel 7",
  "app_version": "2.4.1"
}
```

### Exemple de Réponse Succès (`HTTP 200`)
```json
{
  "success": true,
  "message": "Appareil enregistré avec succès.",
  "data": {
    "device_id": 14,
    "app_id": 1,
    "app_name": "Boutique Mobile E-Commerce",
    "platform": "android",
    "external_user_id": "USER_101",
    "is_active": 1
  }
}
```

---

## 2. `POST /api/create_notification.php`

### 🎯 Rôle
Enregistrer une notification dans la base de données avec le statut **`a_envoyer`** pour traitement ultérieur par le worker, ou déclencher son envoi immédiat via FCM.

### En-têtes requis
```http
X-API-KEY: app_ecommerce_key_9f8a7b6c5d4e3f2a
Content-Type: application/json
```

### Paramètres du Corps (Body JSON)
| Champ | Type | Obligatoire ? | Description / Valeurs |
|---|---|:---:|---|
| `title` | `string` | **Oui** | Titre visible de la notification. |
| `body` | `string` | **Oui** | Contenu du message. |
| `target_type` | `string` | Non | Cible : `"all_users"` *(défaut)*, `"user"`, `"platform"`, `"single_device"`. |
| `target_value` | `string` | Conditionnel | Valeur associée à la cible :<br>• Si `"user"` : identifiant `external_user_id`<br>• Si `"platform"` : `"android"` ou `"ios"`<br>• Si `"single_device"` : token FCM brut. |
| `data` | `object` | Non | Paires clé/valeur de données invisibles transmises à l'app (deep-linking, redirections, IDs). |
| `image_url` | `string` | Non | URL d'une image d'illustration grand format. |
| `priority` | `string` | Non | `"high"` *(défaut, réveil immédiat)* ou `"normal"`. |
| `scheduled_at` | `string` | Non | Date/Heure d'envoi différé (`"YYYY-MM-DD HH:MM:SS"`). |
| `immediate_send`| `boolean`| Non | `false` *(défaut, reste à 'a_envoyer')* ou `true` *(envoi sur-le-champ)*. |

### Exemple de Requête
```json
{
  "title": "🎉 Vente Flash !",
  "body": "20% de remise supplémentaire pendant 2 heures.",
  "target_type": "user",
  "target_value": "USER_101",
  "data": {
    "screen": "promotions",
    "promo_code": "FLASH20"
  },
  "immediate_send": false
}
```

### Exemple de Réponse Succès (`HTTP 201`)
```json
{
  "success": true,
  "message": "Notification enregistrée avec succès avec le statut 'a_envoyer'.",
  "data": {
    "notification_id": 56,
    "app_id": 1,
    "app_name": "Boutique Mobile E-Commerce",
    "title": "🎉 Vente Flash !",
    "target_type": "user",
    "target_value": "USER_101",
    "status": "a_envoyer",
    "scheduled_at": null,
    "created_at": "2026-09-14 23:20:00",
    "stats": {
      "recipients": 0,
      "success": 0,
      "failure": 0
    }
  }
}
```

---

## 3. `GET /api/notification_status.php`

### 🎯 Rôle
Interroger l'état d'avancement d'une notification et obtenir les statistiques précises d'envoi (nombre d'appareils ciblés, succès, échecs).

### En-têtes requis
```http
X-API-KEY: app_ecommerce_key_9f8a7b6c5d4e3f2a
```

### Paramètres d'URL (Query String)
| Paramètre | Type | Obligatoire ? | Description |
|---|---|:---:|---|
| `id` | `integer` | **Oui** | L'identifiant numérique de la notification (`notification_id`). |

### Exemple d'Appel
```http
GET /api/notification_status.php?id=56
```

### Exemple de Réponse Succès (`HTTP 200`)
```json
{
  "success": true,
  "data": {
    "id": 56,
    "title": "🎉 Vente Flash !",
    "body": "20% de remise supplémentaire pendant 2 heures.",
    "status": "envoye",
    "target_type": "user",
    "target_value": "USER_101",
    "scheduled_at": null,
    "sent_at": "2026-09-14 23:20:02",
    "created_at": "2026-09-14 23:20:00",
    "error_details": null,
    "stats": {
      "recipients": 2,
      "success": 2,
      "failure": 0,
      "retries": 0
    },
    "recent_logs": [
      {
        "id": 102,
        "device_id": 14,
        "status": "succes",
        "error_code": null,
        "fcm_message_id": "projects/mon-projet/messages/0:1694723000...",
        "sent_at": "2026-09-14 23:20:02"
      }
    ]
  }
}
```

---

## 4. `GET /api/list_notifications.php`

### 🎯 Rôle
Lister l'historique des notifications créées par l'application appelante, avec pagination et filtrage par statut (`a_envoyer`, `envoye`, `echec`, etc.).

### En-têtes requis
```http
X-API-KEY: app_ecommerce_key_9f8a7b6c5d4e3f2a
```

### Paramètres d'URL (Query String Optionnels)
| Paramètre | Type | Valeur par défaut | Description |
|---|---|:---:|---|
| `status` | `string` | *(aucun)* | Filtrer par statut : `"a_envoyer"`, `"en_cours"`, `"envoye"`, `"echec"`, `"partiel"`. |
| `limit` | `integer` | `20` | Nombre d'éléments retournés (maximum 100). |
| `offset` | `integer` | `0` | Décalage pour la pagination. |

### Exemple d'Appel
```http
GET /api/list_notifications.php?status=a_envoyer&limit=10&offset=0
```

### Exemple de Réponse Succès (`HTTP 200`)
```json
{
  "success": true,
  "app": {
    "id": 1,
    "name": "Boutique Mobile E-Commerce"
  },
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "count": 10
  },
  "data": [
    {
      "id": 56,
      "app_id": 1,
      "title": "🎉 Vente Flash !",
      "body": "20% de remise...",
      "target_type": "user",
      "target_value": "USER_101",
      "status": "a_envoyer",
      "priority": "high",
      "scheduled_at": null,
      "sent_at": null,
      "recipients_count": 0,
      "success_count": 0,
      "failure_count": 0,
      "created_at": "2026-09-14 23:20:00"
    }
  ]
}
```

---

## 5. `GET|POST /api/private/cron/send_worker.php`

### 🎯 Rôle
Point d'entrée du Worker d'envoi. Sélectionne par lot les notifications au statut **`a_envoyer`** dont la date d'envoi est arrivée (`scheduled_at IS NULL OR scheduled_at <= NOW()`), les expédie via l'API FCM HTTP v1 de Google et met à jour leur statut final.

### Modes d'exécution
1. **Ligne de commande (CLI / Tâche Cron système Linux)** :
   ```bash
   php api/private/cron/send_worker.php
   ```
2. **Requête Web (Webhook / URL sécurisée)** :
   ```http
   GET /api/private/cron/send_worker.php?key=FCM_WORKER_SECRET_CHANGE_ME_2026
   ```

### Exemple de Réponse JSON (Mode Web)
```json
{
  "success": true,
  "timestamp": "2026-09-14 23:22:00",
  "count_processed": 3,
  "duration_sec": 0.428,
  "details": [
    {
      "id": 56,
      "app_id": 1,
      "status": "envoye",
      "recipients": 2,
      "success": 2,
      "failure": 0
    }
  ]
}
```

---

## 🚦 Cycle de Vie des Statuts de Notification

```mermaid
stateDiagram-v2
    [*] --> a_envoyer : Création (create_notification.php)
    a_envoyer --> en_cours : Prise en charge par le Worker
    en_cours --> envoye : 100% des réceptions réussies
    en_cours --> partiel : Certains appareils ont réussi, d'autres ont échoué
    en_cours --> echec : Aucun envoi n'a abouti (ex: 0 destinataires ou erreur credentials)
```

| Statut | Signification |
|---|---|
| `a_envoyer` | Notification enregistrée en base, en attente d'expédition par le worker. |
| `en_cours` | Prise en charge en cours par le processus d'envoi (verrouillage de concurrence). |
| `envoye` | Notification expédiée avec succès à tous les destinataires ciblés. |
| `partiel` | Succès partiel (certains appareils ont reçu la notification, d'autres ont échoué). |
| `echec` | Échec de l'envoi (aucun appareil actif trouvé, ou identifiants Firebase invalides). |
