API Campagnes SMS

Endpoints pour la gestion des campagnes SMS.

Endpoints

Methode	Endpoint	Description
GET	`/api/sms-campaigns`	Liste des campagnes
POST	`/api/sms-campaigns`	Creer une campagne
GET	`/api/sms-campaigns/{id}`	Detail d'une campagne
PUT	`/api/sms-campaigns/{id}`	Modifier une campagne
DELETE	`/api/sms-campaigns/{id}`	Supprimer une campagne
POST	`/api/sms-campaigns/{id}/add-beneficiaires`	Ajouter des beneficiaires
POST	`/api/sms-campaigns/{id}/import`	Importer depuis fichier
GET	`/api/sms-campaigns/{id}/destinataires`	Liste des destinataires
POST	`/api/sms-campaigns/{id}/mark-ready`	Marquer comme pret
GET	`/api/sms-campaigns/{id}/preview`	Previsualiser les messages
GET	`/api/sms-campaigns/{id}/export`	Exporter pour operateur
POST	`/api/sms-campaigns/{id}/generate-messages`	Generer les messages
GET	`/api/sms-campaigns/import-template`	Telecharger le modele

Liste des campagnes

GET /api/sms-campaigns

Parametres de requete

Parametre	Type	Description
`page`	int	Numero de page
`itemsPerPage`	int	Elements par page (max 100)
`statut`	string	Filtrer par statut
`type`	string	Filtrer par type
`search`	string	Recherche textuelle

Exemple de requete

curl "https://sig.ucp-pch.org/api/sms-campaigns?statut=brouillon&page=1" \
  -H "Authorization: Bearer TOKEN"

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nom": "Rappel Paiement Mars 2026",
      "type": "rappel_general",
      "statut": "brouillon",
      "nbDestinataires": 150,
      "nbMessagesGeneres": 0,
      "createdAt": "2026-03-15T10:30:00+00:00",
      "createdBy": {
        "id": 1,
        "nom": "Admin"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "itemsPerPage": 30,
    "totalItems": 45
  }
}

Creer une campagne

POST /api/sms-campaigns

Corps de requete

{
  "nom": "Rappel Paiement Mars 2026",
  "type": "rappel_general",
  "description": "Rappel pour les paiements du mois de mars"
}

Champs

Champ	Type	Obligatoire	Description
`nom`	string	Oui	Nom de la campagne
`type`	string	Oui	Type de campagne
`description`	string	Non	Description interne

Types valides

rappel_general
information
sensibilisation
convocation
paiement_success
paiement_failed
paiement_pending
paiement_reminder

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nom": "Rappel Paiement Mars 2026",
    "type": "rappel_general",
    "statut": "brouillon",
    "createdAt": "2026-03-15T10:30:00+00:00"
  }
}

Ajouter des beneficiaires

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

Corps de requete

{
  "filters": {
    "region": "550e8400-e29b-41d4-a716-446655440001",
    "secteur": null,
    "commune": null,
    "statut": "actif",
    "cycleId": "550e8400-e29b-41d4-a716-446655440002"
  }
}

Filtres disponibles

Filtre	Type	Description
`region`	uuid	ID de la region
`secteur`	uuid	ID du secteur
`commune`	uuid	ID de la commune
`statut`	string	Statut des beneficiaires
`cycleId`	uuid	Lie a un cycle specifique

Reponse

{
  "success": true,
  "data": {
    "added": 150,
    "skipped": 5,
    "errors": [
      "3 beneficiaires sans telephone"
    ]
  }
}

Importer depuis fichier

POST /api/sms-campaigns/{id}/import
Content-Type: multipart/form-data

Corps de requete

Champ	Type	Description
`file`	file	Fichier Excel ou CSV

Format du fichier

Colonne	Type	Obligatoire
telephone	string	Oui
nom	string	Oui
langue	string	Non (defaut: pt)

Reponse

{
  "success": true,
  "data": {
    "imported": 100,
    "skipped": 2,
    "errors": [
      {"ligne": 5, "erreur": "Numero de telephone invalide"},
      {"ligne": 12, "erreur": "Langue non reconnue"}
    ]
  }
}

Liste des destinataires

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

Parametres

Parametre	Type	Description
`page`	int	Numero de page
`itemsPerPage`	int	Elements par page
`langue`	string	Filtrer par langue
`valide`	bool	Filtrer par validite

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "telephone": "+245955123456",
      "nom": "Mamadou Diallo",
      "langue": "cr",
      "estValide": true,
      "messageGenere": "Mamadou Diallo, lembra di kumpri bo paiementu na 15/03/2026."
    }
  ],
  "stats": {
    "total": 150,
    "valides": 147,
    "invalides": 3,
    "parLangue": {
      "pt": 45,
      "cr": 80,
      "ff": 25
    }
  }
}

Previsualiser les messages

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

Parametres

Parametre	Type	Description
`limite`	int	Nombre d'exemples (max 10)
`langue`	string	Filtrer par langue

Reponse

{
  "success": true,
  "data": [
    {
      "destinataire": {
        "nom": "Mamadou Diallo",
        "telephone": "+245955123456",
        "langue": "cr"
      },
      "message": "Mamadou Diallo, lembra di kumpri bo paiementu na 15/03/2026.",
      "longueur": 62
    }
  ]
}

Marquer comme pret

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

Pre-requis

La campagne doit etre en statut "brouillon"
Au moins un destinataire valide
Les messages doivent etre generes

Reponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "statut": "pret",
    "nbDestinatairesValides": 147,
    "readyAt": "2026-03-15T11:00:00+00:00"
  }
}

Erreurs possibles

Code	Description
400	Campagne deja prete ou exportee
422	Aucun destinataire valide

Exporter pour operateur

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

Pre-requis

La campagne doit etre en statut "pret"

Reponse

Retourne un fichier Excel (.xlsx) avec les colonnes :

Colonne	Description
Telephone	Numero au format international
Message	Message personnalise
Langue	Code langue
Nom	Nom du destinataire

Headers de reponse

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="campagne-rappel-mars-2026.xlsx"

Generer les messages

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

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

Reponse

{
  "success": true,
  "data": {
    "generes": 147,
    "erreurs": [
      {"destinataire": "Diallo", "erreur": "Template manquant pour langue 'bjg'"}
    ]
  }
}

Telecharger le modele d'import

GET /api/sms-campaigns/import-template

Retourne un fichier Excel modele pour l'import de destinataires.

Reponse

Fichier Excel avec les colonnes :

telephone (exemple: +245955123456)
nom (exemple: Nom Complet)
langue (exemple: pt)

Codes d'erreur

Code	Description
400	Requete invalide
401	Non authentifie
403	Permission refusee
404	Campagne non trouvee
422	Erreur de validation
500	Erreur serveur

Permissions

Endpoint	Permission
GET (lecture)	`sms.campaigns_view`
POST/PUT/DELETE	`sms.campaigns_edit`
Export	`sms.campaigns_export`

Endpoints​

Liste des campagnes​

Parametres de requete​

Exemple de requete​

Reponse​

Creer une campagne​

Corps de requete​

Champs​

Types valides​

Reponse​

Ajouter des beneficiaires​

Corps de requete​

Filtres disponibles​

Reponse​

Importer depuis fichier​

Corps de requete​

Format du fichier​

Reponse​

Liste des destinataires​

Parametres​

Reponse​

Previsualiser les messages​

Parametres​

Reponse​

Marquer comme pret​

Pre-requis​

Reponse​

Erreurs possibles​

Exporter pour operateur​

Pre-requis​

Reponse​

Headers de reponse​

Generer les messages​

Reponse​

Telecharger le modele d'import​

Reponse​

Codes d'erreur​

Permissions​

Endpoints

Liste des campagnes

Parametres de requete

Exemple de requete

Reponse

Creer une campagne

Corps de requete

Champs

Types valides

Reponse

Ajouter des beneficiaires

Corps de requete

Filtres disponibles

Reponse

Importer depuis fichier

Corps de requete

Format du fichier

Reponse

Liste des destinataires

Parametres

Reponse

Previsualiser les messages

Parametres

Reponse

Marquer comme pret

Pre-requis

Reponse

Erreurs possibles

Exporter pour operateur

Pre-requis

Reponse

Headers de reponse

Generer les messages

Reponse

Telecharger le modele d'import

Reponse

Codes d'erreur

Permissions