Accueil

Contrats d'Interface - Orchestrateur Temporal Notifications Multi-Applications

Ce document décrit de manière claire et actionnable les contrats d'interface à utiliser pour l'envoi de notifications via l'orchestrateur Temporal et les microservices (Push, Email, SMS). Il couvre les envois ciblés et broadcast, ainsi que la sémantique de criticité (planification).

Nouveau: Le système supporte maintenant plusieurs applications avec des audiences isolées. Les applications sont enregistrées dynamiquement via l'API REST du Temporal Orchestrator. Chaque application a son propre topic Kafka et ses propres workflows.

Topic d'entrée application:

Le topic varie selon l'application : {appId}.orchestration-requests

EAgence: eagence.orchestration-requests
ECompteur: ecompteur.orchestration-requests (exemple)
EFacture: efacture.orchestration-requests (exemple)

Les applications sont enregistrées via l'API REST : POST https://lolipop.dctd-cie.com/api/applications

1) Base Orchestrateur - Requête Application EAgence

Interface

{
  messageId?: string,
  correlationId?: string,
  batchId?: string,
  timestamp?: string, // ISO
  criticality: number, // 1 = immédiat ; >1 = fenêtre 6h-22h (Abidjan)
  mode_test?: boolean,
  test_date?: string, // ISO, requis si mode_test
  channels?: {
    push?: { enabled?: boolean, excludedUserIds?: string[] },
    email?: { enabled?: boolean, recipients?: string[] }, // ["broadcast"] supporté
    sms?:   { enabled?: boolean, recipients?: string[] }  // ["broadcast"] supporté
  },
  content?: {
    push?: {
      title?: string,
      body?: string,
      data?: {
        type?: "technical" | "functional_client" | "functional_backoffice",
        eventType?: "account_connection" | "account_disconnection" | "level2_attachment" | "level2_detachment" | "enrollment" | "new_bill" | "bill_payment" | "prepaid_purchase" | "request_status_change" | "payment_confirmation" | "overdue_reminder" | "cutoff_alert" | "supply_stop_alert" | "quote_available" | "custom_message" | "new_request" | "request_status_update",
        eventData?: object,
        clientId?: string,
        deviceId?: string,
        locale?: string,
        details?: object,
        customFields?: object
      },
      userIds?: string[],
      platforms?: Array<"web" | "android" | "ios" | "harmony_os">
    },
    email?: { subject?: string, body?: string, attachments?: { filename?: string, content?: string, contentType?: string }[] },
    sms?:   { message?: string }
  },
  metadata?: { 
    campaignId?: string, 
    source?: string,
    application?: string // REQUIS - Identifiant de l'application (ex: "eagence", "ecompteur")
  }
}

Champs minimum pour un push simple: { criticality: 1, channels: { push: { enabled: true } }, content: { push: { title, body } }, metadata: { application: "eagence" } }

Important: Le champ metadata.application est automatiquement ajouté par l'orchestrateur basé sur le topic Kafka utilisé. Il est utilisé pour filtrer les devices lors des broadcasts, garantissant l'isolation des audiences entre applications.

2) Envoie Sms - Contrats

Permets l'envoi de SMS à un ou plusieurs numéros spécifiques.

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  sms: {
    enabled: boolean,
    recipients: string[],
  }
}
content: {
  sms: {
    message: string,
  }
}
metadata: {
  campaignId?: string,
  source?: string,
  application?: string // REQUIS - Identifiant de l'application (ajouté automatiquement par l'orchestrateur)
}
}

Cas d'usage rapide

{
  "criticality": 1,
  "messageId": "sms_2024_01_123",
  "correlationId": "1234567890",
  "channels": { 
      "sms": { 
          "enabled": true, 
          "recipients": ["+22501020304"] 
      } 
  },
  "content": { 
      sms: { 
          "message": "Code OTP: 123456" 
      } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

3) Envoie Email - Contrats

Permets l'envoi d'email à un ou plusieurs destinataires spécifiques.

Payload simplifié:

{
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  email: {
    enabled: boolean,
    recipients: string[],
  }
}
content: {
  email: {
    subject: string,
    body: string,
    attachments: { filename: string, content: string, contentType: string }[],
  }
}
metadata: {
  campaignId?: string,
  source?: string,
  application?: string // REQUIS - Identifiant de l'application (ajouté automatiquement par l'orchestrateur)
}
}


    
      Cas d'usage rapide
      {
  "criticality"   : 1,
  "messageId": "bill_2024_01_123",
  "correlationId": "1234567890",
  "channels": {
       "email": { 
          "enabled": true, 
          "recipients": ["client@example.com"] 
      } 
  },
  "content": { 
      "email": { 
          "subject": "Votre facture", 
          "body": "<p>Montant...</p>"
      } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}



  4) Envoie Push - Contrats
  Permets l'envoi de push à un ou plusieurs utilisateurs spécifiques.
  
    
        a) Envoi ciblé par userIds (canaux: web, android, ios)
      Payload simplifié:
      {
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  push: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    userIds: string[],
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  }
}
metadata: {
  campaignId?: string,
  source?: string,
  application?: string // REQUIS - Identifiant de l'application (ajouté automatiquement par l'orchestrateur)
}
}

    
    
         b) Broadcast par plateformes (android / ios / web)
        Payload simplifié:
        {
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,

channels: {
  push: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  }
}
metadata: {
  campaignId?: string,
  source?: string,
  application?: string // REQUIS - Identifiant de l'application (ajouté automatiquement par l'orchestrateur)
}
}
        
    
  


  
    
      Cas d'usage rapide a) Push ciblé par userIds
      {
  "criticality": 2,
  "messageId": "push_2024_01_123",
  "correlationId": "1234567890",
  "channels": { "push": { "enabled": true } },
  "content": { 
    "push": {
         "title": "Maj compte", 
         "body": "Votre compte est lié", 
         "userIds": ["user123"], 
         "platforms": ["android","ios","web"],
         data: { 
            "type": "functional_client", 
            "eventType": "level2_attachment", 
            "clientId": "CLI-001" 
        } 
    } 
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

    

    
        Cas d'usage rapide b) Broadcast par plateformes
        {
    "criticality": 2,
    "messageId": "push_2024_01_123",
    "correlationId": "1234567890",
    "channels": { "push": { "enabled": true } },
    "content": { 
      push: {
           "title": "Maj compte", 
           "body": "Votre compte est lié", 
           "platforms": ["android", "web", "ios"],
           "data": { 
              "type": "functional_client", 
              "eventType": "level2_attachment", 
              "clientId": "CLI-001" 
          } 
      } 
    },
    "metadata": {
      "campaignId": "CAM-001",
      "source": "eagence"
    }
  }


      






  

  5) Envoie sur tous les canaux - Contrats
  Permets l'envoi de notification sur tous les canaux (push, email, sms).
  
    
      Payload simplifié:
      {
criticality: number,
messageId?: string,
correlationId?: string,
timestamp?: string,
channels: {
  push: {
    enabled: boolean
  },
  email: {
    enabled: boolean
  },
  sms: {
    enabled: boolean
  }
}
content: {
  push: {
    title: string,
    body: string,
    platforms: string[], // android, ios, web
    data: {
      type: string,
      eventType: string,
      eventData: object,
    }
  },
  email: {
    subject: string,
    body: string,
    attachments: { filename: string, content: string, contentType: string }[],
  }
  sms: {
    message: string,
  }
}
metadata: {
  campaignId?: string,
  source?: string,
  application?: string // REQUIS - Identifiant de l'application (ajouté automatiquement par l'orchestrateur)
}
}
        
    
    
      Cas d'usage rapide sur tous les canaux
      {
  "criticality": 2,
  "messageId": "push_2024_01_123",
  "correlationId": "1234567890",
  "channels": { 
    "push": { 
      "enabled": true 
    }, 
    "email": { 
      "enabled": true,
      "recipients": ["client@example.com"]
    },
    "sms": { 
      "enabled": true,
      "recipients": ["+22501020304"]
    } 
  },
  "content": { 
    "push": {
         "title": "Maj compte", 
         "body": "Votre compte est lié", 
         "userIds": ["CLI-001"], 
         "platforms": ["android","ios","web"],
         data: { 
            "type": "functional_client", 
            "eventType": "level2_attachment", 
            "clientId": "CLI-001" 
        } 
    },
    "email": {
      "subject": "Maj compte", 
      "body": "Votre compte est lié", 
    },
    "sms": {
      "message": "Votre compte est lié", 
    },
  },
  "metadata": {
    "campaignId": "CAM-001",
    "source": "eagence"
  }
}

    
  



 



  6) APIs directes des microservices
  Les microservices (Push, Email, SMS) exposent également des APIs directes pour l'envoi de notifications sans passer par l'orchestrateur. Important: Le champ applicationId est requis pour toutes les APIs d'envoi.
  
  
    
      API Push directe
      POST https://lolipop.dctd-cie.com/push/api/notifications/send
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS
  "userIds": ["user123"],
  "notification": {
    "title": "Nouveau message",
    "body": "Vous avez reçu un nouveau message"
  }
}
    
    
      API Push Broadcast
      POST https://lolipop.dctd-cie.com/push/api/notifications/broadcast
Content-Type: application/json

{
  "applicationId": "eagence", // REQUIS - Filtre l'audience
  "notification": {
    "title": "Annonce importante",
    "body": "Nouvelle fonctionnalité disponible"
  }
}
    
    
      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"
}
    
    
      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"
}
    
  

  
    Note importante:
    
      Push: applicationId est REQUIS pour cibler l'audience correcte et isoler les broadcasts.
      Email et SMS: applicationId est optionnel mais recommandé pour tracer quelle application a utilisé le service dans l'historique.

    

  


  7) Bonnes pratiques
  
    Inclure correlationId pour le traçage bout-en-bout.
    Définir la criticité; utiliser 1 pour les urgences.
    Utiliser le bon topic Kafka selon l'application : {appId}.orchestration-requests
    Vérifier que l'application est enregistrée et activée via l'API REST avant d'envoyer des notifications.
    Isolation des audiences: Les broadcasts n'affectent que les devices enregistrés pour l'application spécifiée dans metadata.application.
    APIs directes: Toujours inclure applicationId dans les APIs directes (requis pour Push, recommandé pour Email/SMS).
  

  8) Gestion des applications
  Les applications sont gérées via l'API REST du Temporal Orchestrator :
    
      Enregistrer une nouvelle application
      POST https://lolipop.dctd-cie.com/api/applications
Content-Type: application/json

{
  "appId": "ecompteur",
  "name": "ECompteur",
  "topic": "ecompteur.orchestration-requests",
  "workflow": "SharedDistributionWorkflow", // Utilisé pour consumerType: "generic"
  "consumerType": "generic", // "generic" utilise toujours SharedDistributionWorkflow
  "enabled": true,
  "description": "Application de gestion des compteurs",
  "metadata": {
    "criticalityRequired": true,
    "defaultCriticality": 1,
    "timezone": "Africa/Abidjan",
    "businessHours": {
      "start": "06:00",
      "end": "22:00"
    }
  }
}
      Note: Pour consumerType: "generic", le champ workflow est ignoré car le système utilise toujours SharedDistributionWorkflow. Pour un workflow personnalisé, utilisez consumerType: "custom" et spécifiez customConsumerClass.
    
  
    Liste des applications
    GET https://lolipop.dctd-cie.com/api/applications
  
  
    Activer/Désactiver une application
    POST https://lolipop.dctd-cie.com/api/applications/{appId}/enable
POST https://lolipop.dctd-cie.com/api/applications/{appId}/disable
  
  
    Recharger les applications
    POST https://lolipop.dctd-cie.com/api/applications/reload
    Recharge les applications depuis la base de données et redémarre les consumers Kafka.