đ
API Notifications Push (FCM)
Référentiel complet des Endpoints, RÎles et Payloads
Enregistrement & actualisation d'un terminal FCM
Enregistre ou met Ă jour le token FCM d'un appareil mobile (Android / iOS) ou d'un navigateur Web et l'associe Ă un utilisateur externe.
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/json |
X-API-KEY |
app_ecommerce_key_9f8a7b6c5d4e3f2a |
Structure du Payload (Corps JSON)
| Champ | Type | Obligatoire ? | Description |
fcm_token |
string |
OUI
|
Le jeton d'enregistrement FCM généré par le SDK Firebase cÎté client |
platform |
string |
Optionnel
|
"android" (par défaut), "ios" ou "web" |
external_user_id |
string |
Optionnel
|
Identifiant unique de votre utilisateur applicatif (ex: "USER_101", "CLIENT_99") |
device_model |
string |
Optionnel
|
ModÚle du téléphone ou terminal (ex: "Google Pixel 8", "iPhone 15 Pro") |
app_version |
string |
Optionnel
|
Numéro de version de l'application cliente (ex: "2.4.0") |
Exemple de RequĂȘte JSON
{
"fcm_token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvdmExAmPl3509j812739182379123...",
"platform": "android",
"external_user_id": "USER_101",
"device_model": "Google Pixel 8 Pro",
"app_version": "2.5.1"
}
Réponse SuccÚs (HTTP 200)
{
"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
}
}
Réponse Erreur Type
{
"success": false,
"error": "Le champ fcm_token est obligatoire.",
"code": 400
}
Création & mise en file d'attente d'une notification push
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.
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/json |
X-API-KEY |
app_ecommerce_key_9f8a7b6c5d4e3f2a |
Structure du Payload (Corps JSON)
| Champ | Type | Obligatoire ? | Description |
title |
string |
OUI
|
Titre de la notification push visible sur l'appareil |
body |
string |
OUI
|
Corps du message de notification |
target_type |
string |
Optionnel
|
"all_users" (tous), "user" (un utilisateur), "device" (un token spécifique) ou "topic" (un topic FCM) |
target_value |
string |
Optionnel
|
Valeur de la cible si non all_users (ex: "USER_101", ou "promo_france") |
data |
object |
Optionnel
|
Paires clé/valeur transmises silencieusement à l'application (ex: {"order_id": "8412", "action": "open_screen"}) |
priority |
string |
Optionnel
|
"high" (haute priorité) ou "normal" |
immediate |
boolean |
Optionnel
|
true pour envoyer immédiatement sans attendre le cron (défaut : false) |
scheduled_at |
string |
Optionnel
|
Horodatage ISO 8601 pour un envoi différé futur (ex: "2026-09-25 10:00:00") |
Exemple de RequĂȘte JSON
{
"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
}
Réponse SuccÚs (HTTP 200)
{
"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
}
}
Réponse Erreur Type
{
"success": false,
"error": "Les champs title et body sont obligatoires.",
"code": 400
}
Listing paginé & filtrable des notifications
Retourne l'historique des notifications de l'application avec filtres par statut (a_envoyer, envoye, echec) et pagination.
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-API-KEY |
app_ecommerce_key_9f8a7b6c5d4e3f2a |
Structure du Payload (ParamĂštres d'URL)
| Champ | Type | Obligatoire ? | Description |
status |
string (query param) |
Optionnel
|
Filtrer par statut : "a_envoyer", "envoye", "echec" ou laisser vide pour tous |
page |
integer (query param) |
Optionnel
|
Numéro de la page (défaut : 1) |
limit |
integer (query param) |
Optionnel
|
Nombre d'éléments par page (défaut : 20, max : 100) |
Exemple de RequĂȘte JSON
{
"query_params": "?status=envoye&page=1&limit=20"
}
Réponse SuccÚs (HTTP 200)
{
"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"
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Clé d'authentification X-API-KEY manquante ou invalide.",
"code": 401
}
Statut individuel & logs par terminal
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).
En-tĂȘtes HTTP Requis
| En-tĂȘte | Valeur / Exemple |
X-API-KEY |
app_ecommerce_key_9f8a7b6c5d4e3f2a |
Structure du Payload (ParamĂštres d'URL)
| Champ | Type | Obligatoire ? | Description |
id |
integer (query param) |
OUI
|
Identifiant unique de la notification |
Exemple de RequĂȘte JSON
{
"query_params": "?id=84"
}
Réponse SuccÚs (HTTP 200)
{
"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
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Notification #999 introuvable.",
"code": 404
}