{
    "module": "Notifications Push (Firebase FCM)",
    "base_url": "https://notif.compareb2b.com/public/notif",
    "endpoints": [
        {
            "id": "register_device",
            "method": "POST",
            "path": "/register_device.php",
            "title": "Enregistrement & actualisation d'un terminal FCM",
            "summary": "Enregistre ou met à jour le token FCM d'un appareil mobile (Android / iOS) ou d'un navigateur Web et l'associe à un utilisateur externe.",
            "headers": {
                "Content-Type": "application/json",
                "X-API-KEY": "app_ecommerce_key_9f8a7b6c5d4e3f2a"
            },
            "payload": {
                "fcm_token": {
                    "type": "string",
                    "required": true,
                    "description": "Le jeton d'enregistrement FCM généré par le SDK Firebase côté client"
                },
                "platform": {
                    "type": "string",
                    "required": false,
                    "description": "\"android\" (par défaut), \"ios\" ou \"web\""
                },
                "external_user_id": {
                    "type": "string",
                    "required": false,
                    "description": "Identifiant unique de votre utilisateur applicatif (ex: \"USER_101\", \"CLIENT_99\")"
                },
                "device_model": {
                    "type": "string",
                    "required": false,
                    "description": "Modèle du téléphone ou terminal (ex: \"Google Pixel 8\", \"iPhone 15 Pro\")"
                },
                "app_version": {
                    "type": "string",
                    "required": false,
                    "description": "Numéro de version de l'application cliente (ex: \"2.4.0\")"
                }
            },
            "request_example": {
                "fcm_token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvdmExAmPl3509j812739182379123...",
                "platform": "android",
                "external_user_id": "USER_101",
                "device_model": "Google Pixel 8 Pro",
                "app_version": "2.5.1"
            },
            "response_success": {
                "success": true,
                "message": "Appareil enregistré avec succès.",
                "data": {
                    "device_id": 14,
                    "app_id": 1,
                    "app_name": "Boutique E-Commerce",
                    "platform": "android",
                    "external_user_id": "USER_101",
                    "is_active": 1
                }
            },
            "response_error": {
                "success": false,
                "error": "Le champ fcm_token est obligatoire.",
                "code": 400
            }
        },
        {
            "id": "create_notification",
            "method": "POST",
            "path": "/create_notification.php",
            "title": "Création & mise en file d'attente d'une notification push",
            "summary": "Enregistre une notification push ciblée (tous les utilisateurs, utilisateur précis, terminal unique ou topic FCM) avec expédition immédiate ou différée.",
            "headers": {
                "Content-Type": "application/json",
                "X-API-KEY": "app_ecommerce_key_9f8a7b6c5d4e3f2a"
            },
            "payload": {
                "title": {
                    "type": "string",
                    "required": true,
                    "description": "Titre de la notification push visible sur l'appareil"
                },
                "body": {
                    "type": "string",
                    "required": true,
                    "description": "Corps du message de notification"
                },
                "target_type": {
                    "type": "string",
                    "required": false,
                    "description": "\"all_users\" (tous), \"user\" (un utilisateur), \"device\" (un token spécifique) ou \"topic\" (un topic FCM)"
                },
                "target_value": {
                    "type": "string",
                    "required": false,
                    "description": "Valeur de la cible si non all_users (ex: \"USER_101\", ou \"promo_france\")"
                },
                "data": {
                    "type": "object",
                    "required": false,
                    "description": "Paires clé/valeur transmises silencieusement à l'application (ex: {\"order_id\": \"8412\", \"action\": \"open_screen\"})"
                },
                "priority": {
                    "type": "string",
                    "required": false,
                    "description": "\"high\" (haute priorité) ou \"normal\""
                },
                "immediate": {
                    "type": "boolean",
                    "required": false,
                    "description": "true pour envoyer immédiatement sans attendre le cron (défaut : false)"
                },
                "scheduled_at": {
                    "type": "string",
                    "required": false,
                    "description": "Horodatage ISO 8601 pour un envoi différé futur (ex: \"2026-09-25 10:00:00\")"
                }
            },
            "request_example": {
                "title": "Flash Promo -20% !",
                "body": "Profitez de 20% sur tout le catalogue jusqu'à ce soir.",
                "target_type": "user",
                "target_value": "USER_101",
                "data": {
                    "promo_code": "FLASH20",
                    "redirect_url": "/catalog/deals"
                },
                "priority": "high",
                "immediate": true
            },
            "response_success": {
                "success": true,
                "message": "Notification créée et expédiée avec succès.",
                "data": {
                    "notification_id": 84,
                    "status": "envoye",
                    "recipients_count": 1,
                    "success_count": 1,
                    "failure_count": 0
                }
            },
            "response_error": {
                "success": false,
                "error": "Les champs title et body sont obligatoires.",
                "code": 400
            }
        },
        {
            "id": "list_notifications",
            "method": "GET",
            "path": "/list_notifications.php",
            "title": "Listing paginé & filtrable des notifications",
            "summary": "Retourne l'historique des notifications de l'application avec filtres par statut (a_envoyer, envoye, echec) et pagination.",
            "headers": {
                "X-API-KEY": "app_ecommerce_key_9f8a7b6c5d4e3f2a"
            },
            "payload": {
                "status": {
                    "type": "string (query param)",
                    "required": false,
                    "description": "Filtrer par statut : \"a_envoyer\", \"envoye\", \"echec\" ou laisser vide pour tous"
                },
                "page": {
                    "type": "integer (query param)",
                    "required": false,
                    "description": "Numéro de la page (défaut : 1)"
                },
                "limit": {
                    "type": "integer (query param)",
                    "required": false,
                    "description": "Nombre d'éléments par page (défaut : 20, max : 100)"
                }
            },
            "request_example": {
                "query_params": "?status=envoye&page=1&limit=20"
            },
            "response_success": {
                "success": true,
                "page": 1,
                "limit": 20,
                "total": 142,
                "notifications": [
                    {
                        "id": 84,
                        "title": "Flash Promo -20% !",
                        "body": "Profitez de 20% sur tout le catalogue...",
                        "target_type": "user",
                        "target_value": "USER_101",
                        "status": "envoye",
                        "recipients_count": 1,
                        "success_count": 1,
                        "failure_count": 0,
                        "created_at": "2026-09-22 01:14:02"
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Clé d'authentification X-API-KEY manquante ou invalide.",
                "code": 401
            }
        },
        {
            "id": "notification_status",
            "method": "GET",
            "path": "/notification_status.php",
            "title": "Statut individuel & logs par terminal",
            "summary": "Consulte l'état d'avancement d'une notification et les détails d'expédition pour chaque terminal (FCM Message ID ou code d'erreur en cas de token invalide).",
            "headers": {
                "X-API-KEY": "app_ecommerce_key_9f8a7b6c5d4e3f2a"
            },
            "payload": {
                "id": {
                    "type": "integer (query param)",
                    "required": true,
                    "description": "Identifiant unique de la notification"
                }
            },
            "request_example": {
                "query_params": "?id=84"
            },
            "response_success": {
                "success": true,
                "notification": {
                    "id": 84,
                    "title": "Flash Promo -20% !",
                    "status": "envoye",
                    "recipients_count": 1,
                    "success_count": 1,
                    "failure_count": 0,
                    "sent_at": "2026-09-22 01:14:03"
                },
                "device_logs": [
                    {
                        "device_id": 14,
                        "platform": "android",
                        "external_user_id": "USER_101",
                        "status": "envoye",
                        "fcm_message_id": "projects/my-app/messages/0:1727000123918239%8f9a",
                        "error_message": null
                    }
                ]
            },
            "response_error": {
                "success": false,
                "error": "Notification #999 introuvable.",
                "code": 404
            }
        }
    ]
}