API Campagnes SMS

L'API Campagnes SMS permet de gerer les campagnes de communication SMS vers les beneficiaires.

Vue d'ensemble

Endpoint	Methode	Description
`/api/sms-campaigns`	GET	Liste des campagnes
`/api/sms-campaigns`	POST	Creer une campagne
`/api/sms-campaigns/{id}`	GET	Detail d'une campagne
`/api/sms-campaigns/{id}`	PUT/PATCH	Modifier une campagne
`/api/sms-campaigns/{id}`	DELETE	Supprimer une campagne
`/api/sms-campaigns/metadata`	GET	Metadonnees
`/api/sms-campaigns/statistics`	GET	Statistiques globales
`/api/sms-campaigns/{id}/add-beneficiaires`	POST	Ajouter beneficiaires
`/api/sms-campaigns/{id}/import`	POST	Importer destinataires
`/api/sms-campaigns/{id}/destinataires`	GET	Liste destinataires
`/api/sms-campaigns/{id}/destinataires/{destId}`	DELETE	Supprimer destinataire
`/api/sms-campaigns/{id}/destinataires`	DELETE	Vider destinataires
`/api/sms-campaigns/{id}/mark-ready`	POST	Marquer prete
`/api/sms-campaigns/{id}/preview`	GET	Previsualiser messages
`/api/sms-campaigns/{id}/export`	GET	Exporter Excel
`/api/sms-campaigns/{id}/reset-to-draft`	POST	Remettre en brouillon
`/api/sms-campaigns/{id}/generate-messages`	POST	Generer messages
`/api/sms-campaigns/import-template`	GET	Template d'import

Permissions requises

ROLE_USER : Tous les endpoints

Liste des campagnes

Endpoint

GET /api/sms-campaigns

Parametres de requete

Parametre	Type	Requis	Description
`page`	int	Non	Numero de page (defaut: 1)
`limit`	int	Non	Elements par page (defaut: 20)
`search`	string	Non	Recherche textuelle
`statut`	string	Non	Filtrer par statut
`type`	string	Non	Filtrer par type d'evenement

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nom": "Notification Paiement Janvier",
      "typeEvenement": "notification_paiement",
      "typeEvenementLabel": "Notification de paiement",
      "statut": "brouillon",
      "statutLabel": "Brouillon",
      "nbDestinataires": 500,
      "nbAvecTelephone": 480,
      "description": "Notification pour le cycle janvier 2025",
      "createdAt": "2025-01-15T10:00:00+00:00",
      "updatedAt": "2025-01-15T14:30:00+00:00",
      "dateExport": null,
      "canExport": true,
      "isEditable": true,
      "createdBy": {
        "id": "...",
        "email": "agent@pch.gw"
      }
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "limit": 20,
    "pages": 2
  }
}

Metadonnees

Endpoint

GET /api/sms-campaigns/metadata

Reponse

{
  "success": true,
  "data": {
    "typesCampagne": {
      "notification_paiement": "Notification de paiement",
      "rappel_conditionnalite": "Rappel conditionnalité",
      "information_generale": "Information générale",
      "alerte_urgence": "Alerte urgence"
    },
    "statuts": {
      "brouillon": "Brouillon",
      "pret": "Prêt",
      "exporte": "Exporté"
    },
    "langues": {
      "pt": "Portugais",
      "cr": "Créole",
      "fr": "Français"
    },
    "sources": {
      "selection": "Sélection",
      "import": "Import"
    }
  }
}

Statistiques globales

Endpoint

GET /api/sms-campaigns/statistics

Reponse

{
  "success": true,
  "data": {
    "totalCampagnes": 25,
    "parStatut": {
      "brouillon": 10,
      "pret": 5,
      "exporte": 10
    },
    "parType": {
      "notification_paiement": 15,
      "rappel_conditionnalite": 5,
      "information_generale": 5
    },
    "totalDestinataires": 12500,
    "totalAvecTelephone": 12000
  }
}

Detail d'une campagne

Endpoint

GET /api/sms-campaigns/{id}

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nom": "Notification Paiement Janvier",
    "typeEvenement": "notification_paiement",
    "typeEvenementLabel": "Notification de paiement",
    "statut": "brouillon",
    "statutLabel": "Brouillon",
    "nbDestinataires": 500,
    "nbAvecTelephone": 480,
    "description": "Notification pour le cycle janvier 2025",
    "createdAt": "2025-01-15T10:00:00+00:00",
    "updatedAt": "2025-01-15T14:30:00+00:00",
    "dateExport": null,
    "canExport": true,
    "isEditable": true,
    "createdBy": {
      "id": "...",
      "email": "agent@pch.gw"
    },
    "stats": {
      "bySource": {
        "selection": 400,
        "import": 100
      },
      "byLangue": {
        "pt": 300,
        "cr": 150,
        "fr": 50
      }
    }
  }
}

Creer une campagne

Endpoint

POST /api/sms-campaigns

Corps de la requete

{
  "nom": "Notification Paiement Janvier",
  "typeEvenement": "notification_paiement",
  "description": "Notification pour le cycle janvier 2025"
}

Champs requis

nom : Nom de la campagne
typeEvenement : Type d'evenement

Reponse

{
  "success": true,
  "message": "Campagne creee avec succes",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nom": "Notification Paiement Janvier",
    "typeEvenement": "notification_paiement",
    "statut": "brouillon"
  }
}

Ajouter des beneficiaires

Endpoint

POST /api/sms-campaigns/{id}/add-beneficiaires

Corps de la requete

{
  "beneficiaireIds": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "codeLangue": "pt"
}

Reponse

{
  "success": true,
  "message": "450 beneficiaire(s) ajoute(s), 50 deja present(s)",
  "data": {
    "added": 450,
    "skipped": 50,
    "campaign": {...}
  }
}

Importer des destinataires

Endpoint

POST /api/sms-campaigns/{id}/import

Multipart form-data:

file : Fichier CSV/Excel

Reponse

{
  "success": true,
  "message": "200 destinataire(s) importe(s), 5 erreur(s)",
  "data": {
    "imported": 200,
    "errors": 5,
    "errorDetails": [
      {"ligne": 12, "erreur": "Telephone invalide"},
      {"ligne": 45, "erreur": "Nom manquant"}
    ],
    "campaign": {...}
  }
}

Liste des destinataires

Endpoint

GET /api/sms-campaigns/{id}/destinataires

Parametres

Parametre	Type	Requis	Description
`page`	int	Non	Numero de page
`limit`	int	Non	Elements par page (defaut: 50)

Reponse

{
  "success": true,
  "data": [
    {
      "id": "...",
      "nom": "Mamadou Diallo",
      "telephone": "+245955123456",
      "hasValidPhone": true,
      "codeLangue": "pt",
      "nomLangue": "Portugais",
      "source": "selection",
      "variables": {
        "montant": "15000",
        "cycle": "Janvier 2025"
      },
      "messageGenere": "Caro Mamadou Diallo, o seu pagamento de 15000 XOF...",
      "createdAt": "2025-01-15T10:00:00+00:00",
      "beneficiaire": {
        "id": "...",
        "code": "BEN-OIO-2025-000001"
      }
    }
  ],
  "pagination": {
    "total": 500,
    "page": 1,
    "limit": 50,
    "pages": 10
  },
  "stats": {
    "bySource": {"selection": 400, "import": 100},
    "byLangue": {"pt": 300, "cr": 150, "fr": 50}
  }
}

Previsualiser les messages

Endpoint

GET /api/sms-campaigns/{id}/preview

Parametres

Parametre	Type	Requis	Description
`limit`	int	Non	Nombre de previews (defaut: 5)

Reponse

{
  "success": true,
  "data": {
    "previews": [
      {
        "destinataire": {
          "id": "...",
          "nom": "Mamadou Diallo",
          "telephone": "+245955123456",
          "codeLangue": "pt"
        },
        "message": "Caro Mamadou Diallo, o seu pagamento de 15000 XOF para Janvier 2025 esta disponivel...",
        "hasTemplate": true
      },
      {
        "destinataire": {...},
        "message": "[Aucun template pour Créole]",
        "hasTemplate": false
      }
    ],
    "total": 480
  }
}

Marquer comme prete

Endpoint

POST /api/sms-campaigns/{id}/mark-ready

Reponse

{
  "success": true,
  "message": "Campagne prete pour export",
  "data": {
    "id": "...",
    "statut": "pret"
  }
}

Erreur si aucun telephone valide

{
  "success": false,
  "error": "Aucun destinataire avec numero de telephone valide"
}

Exporter en Excel

Endpoint

GET /api/sms-campaigns/{id}/export

Retourne un fichier Excel avec les colonnes:

Nom
Telephone
Langue
Message

La campagne est automatiquement marquee comme "exportee".

Generer les messages

Endpoint

POST /api/sms-campaigns/{id}/generate-messages

Genere les messages personnalises pour tous les destinataires en utilisant les templates.

Reponse

{
  "success": true,
  "message": "475 message(s) genere(s), 5 sans template",
  "data": {
    "generated": 475,
    "noTemplate": 5
  }
}

Remettre en brouillon

Endpoint

POST /api/sms-campaigns/{id}/reset-to-draft

Reponse

{
  "success": true,
  "message": "Campagne remise en brouillon",
  "data": {
    "id": "...",
    "statut": "brouillon"
  }
}

Telecharger le template d'import

Endpoint

GET /api/sms-campaigns/import-template

Retourne un fichier Excel vide avec les colonnes requises pour l'import.

Types d'evenement

Type	Description
`notification_paiement`	Notification de paiement
`rappel_conditionnalite`	Rappel de conditionnalite
`information_generale`	Information generale
`alerte_urgence`	Alerte urgence

Statuts de campagne

Statut	Description
`brouillon`	Campagne en cours de preparation
`pret`	Campagne prete pour export
`exporte`	Campagne exportee

Langues disponibles

Code	Langue
`pt`	Portugais
`cr`	Creole
`fr`	Francais

Sources de destinataires

Source	Description
`selection`	Selection de beneficiaires
`import`	Import depuis fichier

Vue d'ensemble​

Permissions requises​

Liste des campagnes​

Endpoint​

Parametres de requete​

Reponse​

Metadonnees​

Endpoint​

Reponse​

Statistiques globales​

Endpoint​

Reponse​

Detail d'une campagne​

Endpoint​

Reponse​

Creer une campagne​

Endpoint​

Corps de la requete​

Champs requis​

Reponse​

Ajouter des beneficiaires​

Endpoint​

Corps de la requete​

Reponse​

Importer des destinataires​

Endpoint​

Reponse​

Liste des destinataires​

Endpoint​

Parametres​

Reponse​

Previsualiser les messages​

Endpoint​

Parametres​

Reponse​

Marquer comme prete​

Endpoint​

Reponse​

Erreur si aucun telephone valide​

Exporter en Excel​

Endpoint​

Generer les messages​

Endpoint​

Reponse​

Remettre en brouillon​

Endpoint​

Reponse​

Telecharger le template d'import​

Endpoint​

Types d'evenement​

Statuts de campagne​

Langues disponibles​

Sources de destinataires​

Vue d'ensemble

Permissions requises

Liste des campagnes

Endpoint

Parametres de requete

Reponse

Metadonnees

Endpoint

Reponse

Statistiques globales

Endpoint

Reponse

Detail d'une campagne

Endpoint

Reponse

Creer une campagne

Endpoint

Corps de la requete

Champs requis

Reponse

Ajouter des beneficiaires

Endpoint

Corps de la requete

Reponse

Importer des destinataires

Endpoint

Reponse

Liste des destinataires

Endpoint

Parametres

Reponse

Previsualiser les messages

Endpoint

Parametres

Reponse

Marquer comme prete

Endpoint

Reponse

Erreur si aucun telephone valide

Exporter en Excel

Endpoint

Generer les messages

Endpoint

Reponse

Remettre en brouillon

Endpoint

Reponse

Telecharger le template d'import

Endpoint

Types d'evenement

Statuts de campagne

Langues disponibles

Sources de destinataires