Documentation - Service de Notification

1. Introduction

Ce document explique comment utiliser le service de notification, aussi bien pour les applications mobiles que pour le web. Il inclut le processus d’enregistrement, la gestion des désabonnements, l’accès aux statistiques, ainsi que les bases URL de chaque service.

2. Base URL

La base URL pour accéder à l'API est :

https://lolipop.dctd-cie.com/push/

2.1. Gestion des applications

Le système supporte maintenant plusieurs applications avec des audiences isolées. Chaque appareil doit être enregistré pour une application spécifique via le champ applicationId.

Avantages:

Isolation des audiences : les broadcasts d'une application n'affectent que ses propres utilisateurs
Enregistrement dynamique : nouvelles applications ajoutées via API sans modification de code
Gestion centralisée : API REST pour gérer les applications (activer/désactiver, recharger)

API de gestion des applications (Temporal Orchestrator):

Base URL: https://lolipop.dctd-cie.com/api/applications
Swagger: https://lolipop.dctd-cie.com/api/docs
Endpoints: GET (liste), POST (créer), PUT (modifier), DELETE (supprimer)
Actions: POST /{appId}/enable, POST /{appId}/disable, POST /reload

3. Enregistrement d'un appareil

Avant de recevoir des notifications, il faut enregistrer l'appareil. Important: Chaque appareil doit être enregistré pour une application spécifique via le champ applicationId (requis). Cela permet d'isoler les audiences et d'envoyer des broadcasts ciblés par application.

3.1. Mobile

Voici le déroulé comment enregistrer un appareil mobile(Android ou iOS) :

POST push/devices/register
Content-Type: application/json

{
    "applicationId": "eagence", // REQUIS - Identifiant de l'application
    "userId": "user123",
    "token": "fcm_device_token_from_mobile_app", 
    "platform": "android", // ou ios
    "deviceInfo": {
      "model": "Samsung Galaxy S21", // ou iPhone 13 Pro Max
      "osVersion": "Android 12", // ou iOS 15.6.1
      "appVersion": "2.1.0", 
      "locale": "fr-FR" 
    },
    "deviceId": "device_unique_id" 
  }

3.2. Web

Le processus d’enregistrement Web se déroule en trois étapes : récupérer la clé VAPID, créer une souscription via le Service Worker, puis enregistrer l’appareil auprès de l’API.

3.2.1. Front office (Chrome / Firefox)

Étape 1 : Récupérer la clé VAPID

GET push/devices/vapid-key

Étape 2 : Créer la souscription (extrait JavaScript minimal)

// Exemple (navigateur)
const publicKey = await fetch(`${BASE_API}/push/devices/vapid-key`).then(r => r.json()).then(d => d.publicKey);
const registration = await navigator.serviceWorker.register('/sw.js');
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(publicKey)
});

// Récupération des clés pour l'enregistrement serveur
const p256dhKey = btoa(String.fromCharCode(...new Uint8Array(subscription.getKey('p256dh'))));
const authKey = btoa(String.fromCharCode(...new Uint8Array(subscription.getKey('auth'))));

Étape 3 : Enregistrer l'appareil

POST push/devices/register
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS - Identifiant de l'application
  "userId": "user123",
  "platform": "web_chrome", // ou "web_firefox"
  "deviceInfo": {
    "userAgent": "Mozilla/5.0 ...",
    "locale": "fr-FR",
    "webPushSubscription": {
      "endpoint": "https://fcm.googleapis.com/fcm/send/abc123",
      "keys": {
        "p256dh": "P256DH_KEY",
        "auth": "AUTH_KEY"
      }
    }
  }
}

3.2.2. Backoffice

Les appareils Backoffice sont enregistrés sur un endpoint dédié et sont automatiquement exclus des broadcasts généraux.

POST push/devices/register/backoffice-device
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS - Identifiant de l'application
  "userId": "admin_user_123",
  "deviceInfo": {
    "webPushSubscription": {
      "endpoint": "https://fcm.googleapis.com/fcm/send/abc123",
      "keys": {
        "p256dh": "P256DH_KEY",
        "auth": "AUTH_KEY"
      }
    }
  },
  "isBackoffice": true
}

4. APIs directes (Push, Email, SMS)

Les microservices (Push, Email, SMS) exposent des APIs directes pour l'envoi de notifications. Important: Le champ applicationId est requis pour toutes les APIs d'envoi afin de cibler l'audience correcte et pour l'historique.

4.1. API Push directe

Envoi direct de notifications push via l'API REST du service Push :

POST https://lolipop.dctd-cie.com/push/api/notifications/send
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS - Identifiant de l'application
  "userIds": ["user123"],
  "notification": {
    "title": "Nouveau message",
    "body": "Vous avez reçu un nouveau message",
    "badge": 1
  },
  "options": {
    "priority": "high"
  }
}

4.2. API Push Broadcast

POST https://lolipop.dctd-cie.com/push/api/notifications/broadcast
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS - Identifiant de l'application (filtre l'audience)
  "notification": {
    "title": "Annonce importante",
    "body": "Nouvelle fonctionnalité disponible",
    "badge": 1
  },
  "options": {
    "priority": "normal"
  }
}

Isolation des audiences: Le applicationId garantit que le broadcast n'affecte que les devices enregistrés pour cette application spécifique.

4.3. API Email directe

POST https://lolipop.dctd-cie.com/email/api/email/send
Content-Type: application/json

{
  "applicationId": "eagence", // Optionnel - Pour l'historique
  "to": "client@example.com",
  "subject": "Votre facture",
  "html": "Montant: 5000 FCFA",
  "text": "Montant: 5000 FCFA"
}

4.4. API SMS directe

POST https://lolipop.dctd-cie.com/sms/api/sms/send
Content-Type: application/json

{
  "applicationId": "eagence", // Optionnel - Pour l'historique
  "to": "+22501020304",
  "message": "Code OTP: 123456"
}

Historique: Le champ applicationId dans les APIs Email et SMS est optionnel mais recommandé pour tracer quelle application a utilisé le service dans l'historique.

5. Désabonnements

Pour vous désabonner des notifications, utilisez les routes suivantes. Vous pouvez cibler un deviceId précis ou utiliser la route générique qui accepte token ou deviceId.

5.1. Désinscrire un appareil (par deviceId)

DELETE push/devices/{deviceId}

5.2. Route générique (token ou deviceId)

Permet de se désinscrire en envoyant soit le token de l'appareil, soit le deviceId (la résolution du token est faite côté serveur).

DELETE push/devices/unregister?token=DEVICE_TOKEN

DELETE push/devices/unregister?deviceId=DEVICE_ID

La désinscription est traitée de façon asynchrone via Kafka. La réponse indique que la requête a été mise en file d’attente.

6. Statistiques

Pour chaque service, vous pouvez obtenir des statistiques précises :

6.1. Statistiques globales (KPIs)

Service push:
base url: https://lolipop.dctd-cie.com/push/
endpoint: push/stats

GET https://lolipop.dctd-cie.com/push/push/stats

Service email:
base url: https://lolipop.dctd-cie.com/email/
endpoint: email/stats

GET https://lolipop.dctd-cie.com/email/email/stats

Service sms:
base url: https://lolipop.dctd-cie.com/sms/
endpoint: sms/stats

GET https://lolipop.dctd-cie.com/sms/sms/stats

6.2. Statistiques détaillées

Service push:
base url: https://lolipop.dctd-cie.com/push/
endpoint: push/stats/details

GET https://lolipop.dctd-cie.com/push/push/stats/details

Service email:
base url: https://lolipop.dctd-cie.com/email/
endpoint: email/stats/details

GET https://lolipop.dctd-cie.com/email/email/stats/details

Service sms:
base url: https://lolipop.dctd-cie.com/sms/
endpoint: sms/stats/details

GET https://lolipop.dctd-cie.com/sms/sms/stats/details

7. Base URL par service

Service Notifications Push : https://lolipop.dctd-cie.com/push/
- Swagger: https://lolipop.dctd-cie.com/push/api/docs
Service Emails : https://lolipop.dctd-cie.com/email/
- Swagger: https://lolipop.dctd-cie.com/email/api/docs
Service SMS : https://lolipop.dctd-cie.com/sms/
- Swagger: https://lolipop.dctd-cie.com/sms/api/docs