API Comptes Opérateurs

L'API Comptes Opérateurs permet de gérer les comptes des opérateurs de Mobile Money et de suivre leurs mouvements financiers.

Vue d'ensemble

Endpoint	Méthode	Description
`/api/comptes-operateurs`	GET	Liste des comptes
`/api/comptes-operateurs/{id}`	GET	Détail d'un compte
`/api/comptes-operateurs`	POST	Créer un compte
`/api/comptes-operateurs/{id}`	PUT	Modifier un compte
`/api/comptes-operateurs/{id}`	DELETE	Supprimer un compte
`/api/comptes-operateurs/operateurs`	GET	Liste des opérateurs
`/api/comptes-operateurs/stats`	GET	Statistiques globales
`/api/comptes-operateurs/alertes`	GET	Alertes de solde
`/api/comptes-operateurs/by-projet-operateur`	GET	Compte par projet/opérateur
`/api/comptes-operateurs/{id}/depots`	POST	Enregistrer un dépôt
`/api/comptes-operateurs/{id}/mouvements`	GET	Historique mouvements
`/api/comptes-operateurs/{id}/stats`	GET	Statistiques du compte
`/api/comptes-operateurs/{id}/recalculer`	POST	Recalculer le solde

Permissions requises

transferts.comptes_view : Consultation des comptes
transferts.comptes_edit : Création et modification
transferts.comptes_delete : Suppression
transferts.depots_create : Enregistrement de dépôts

Liste des comptes opérateurs

Endpoint

GET /api/comptes-operateurs

Paramètres de requête

Paramètre	Type	Requis	Description
`page`	int	Non	Numéro de page (défaut: 1)
`limit`	int	Non	Éléments par page (défaut: 20)
`operateur`	string	Non	Filtrer par opérateur (orange_money, mtn_money)
`projet`	UUID	Non	Filtrer par projet
`statut`	string	Non	Filtrer par statut (actif, inactif)
`search`	string	Non	Recherche textuelle

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-001",
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "numeroCompte": "955123456",
      "nomCompte": "PCH Paiements Oio",
      "projet": {
        "id": "...",
        "nom": "PCH Guinée-Bissau"
      },
      "solde": 125000000,
      "soldeMinimum": 10000000,
      "devise": "XOF",
      "statut": "actif",
      "alerteSolde": false,
      "dernierDepot": "2025-03-10T14:30:00+00:00",
      "dernierPaiement": "2025-03-15T09:00:00+00:00",
      "createdAt": "2025-01-01T08:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "pages": 1
  }
}

Détail d'un compte

Endpoint

GET /api/comptes-operateurs/{id}

Réponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "operateur": "orange_money",
    "operateurLabel": "Orange Money",
    "numeroCompte": "955123456",
    "nomCompte": "PCH Paiements Oio",
    "description": "Compte principal pour les paiements de la région Oio",
    "projet": {
      "id": "...",
      "nom": "PCH Guinée-Bissau",
      "code": "PCH-GW"
    },
    "solde": 125000000,
    "soldeMinimum": 10000000,
    "seuilAlerte": 15000000,
    "devise": "XOF",
    "statut": "actif",
    "alerteSolde": false,
    "contacts": {
      "responsable": "Mamadou Diallo",
      "telephone": "+245955789012",
      "email": "m.diallo@pch.gw"
    },
    "dernierDepot": {
      "date": "2025-03-10T14:30:00+00:00",
      "montant": 50000000,
      "reference": "DEP-2025-0045"
    },
    "dernierPaiement": {
      "date": "2025-03-15T09:00:00+00:00",
      "montant": 12500000,
      "cycleId": "..."
    },
    "statsResume": {
      "totalDepots": 450000000,
      "totalPaiements": 325000000,
      "nombrePaiements": 13000
    },
    "createdAt": "2025-01-01T08:00:00+00:00",
    "updatedAt": "2025-03-15T09:00:00+00:00"
  }
}

Créer un compte

Endpoint

POST /api/comptes-operateurs

Corps de la requête

{
  "operateur": "orange_money",
  "numeroCompte": "955123456",
  "nomCompte": "PCH Paiements Oio",
  "description": "Compte principal pour les paiements de la région Oio",
  "projetId": "550e8400-e29b-41d4-a716-446655440001",
  "soldeInitial": 0,
  "soldeMinimum": 10000000,
  "seuilAlerte": 15000000,
  "contacts": {
    "responsable": "Mamadou Diallo",
    "telephone": "+245955789012",
    "email": "m.diallo@pch.gw"
  }
}

Opérateurs disponibles

Opérateur	Label	Description
`orange_money`	Orange Money	Orange Money Guinée-Bissau
`mtn_money`	MTN Mobile Money	MTN Mobile Money
`wave`	Wave	Wave
`free_money`	Free Money	Free Money

Réponse

{
  "success": true,
  "message": "Compte opérateur créé avec succès",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001"
  }
}

Liste des opérateurs

Endpoint

GET /api/comptes-operateurs/operateurs

Réponse

{
  "success": true,
  "data": [
    {
      "value": "orange_money",
      "label": "Orange Money",
      "logo": "/images/operators/orange.png",
      "actif": true
    },
    {
      "value": "mtn_money",
      "label": "MTN Mobile Money",
      "logo": "/images/operators/mtn.png",
      "actif": true
    },
    {
      "value": "wave",
      "label": "Wave",
      "logo": "/images/operators/wave.png",
      "actif": true
    }
  ]
}

Statistiques globales

Endpoint

GET /api/comptes-operateurs/stats

Paramètres de requête

Paramètre	Type	Requis	Description
`projet`	UUID	Non	Filtrer par projet
`dateDebut`	date	Non	Date de début
`dateFin`	date	Non	Date de fin

Réponse

{
  "success": true,
  "data": {
    "totalComptes": 8,
    "comptesActifs": 7,
    "soldeTotal": 850000000,
    "devise": "XOF",
    "parOperateur": [
      {
        "operateur": "orange_money",
        "label": "Orange Money",
        "comptes": 4,
        "solde": 500000000
      },
      {
        "operateur": "mtn_money",
        "label": "MTN Mobile Money",
        "comptes": 3,
        "solde": 300000000
      }
    ],
    "alertes": {
      "soldeFaible": 1,
      "inactifs": 1
    },
    "activiteRecente": {
      "depotsJour": 2,
      "montantDepotsJour": 75000000,
      "paiementsJour": 1500,
      "montantPaiementsJour": 37500000
    }
  }
}

Alertes de solde

Endpoint

GET /api/comptes-operateurs/alertes

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-002",
      "nomCompte": "PCH Paiements Bafata",
      "operateur": "orange_money",
      "solde": 8000000,
      "soldeMinimum": 10000000,
      "deficit": 2000000,
      "typeAlerte": "solde_critique",
      "message": "Solde inférieur au minimum requis"
    }
  ]
}

Compte par projet et opérateur

Endpoint

GET /api/comptes-operateurs/by-projet-operateur

Paramètres de requête

Paramètre	Type	Requis	Description
`projetId`	UUID	Oui	ID du projet
`operateur`	string	Oui	Code opérateur

Réponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "solde": 125000000,
    "operateur": "orange_money"
  }
}

Enregistrer un dépôt

Endpoint

POST /api/comptes-operateurs/{id}/depots

Corps de la requête

{
  "montant": 50000000,
  "reference": "VIR-2025-0045",
  "dateDepot": "2025-03-15",
  "source": "Transfert bancaire",
  "notes": "Approvisionnement pour cycle Mars 2025",
  "pieceJustificative": "file_id_optionnel"
}

Réponse

{
  "success": true,
  "message": "Dépôt enregistré avec succès",
  "data": {
    "depotId": "550e8400-e29b-41d4-a716-446655440010",
    "reference": "DEP-2025-0046",
    "montant": 50000000,
    "nouveauSolde": 175000000
  }
}

Historique des mouvements

Endpoint

GET /api/comptes-operateurs/{id}/mouvements

Paramètres de requête

Paramètre	Type	Requis	Description
`page`	int	Non	Numéro de page
`limit`	int	Non	Éléments par page
`type`	string	Non	Type de mouvement (depot, paiement, ajustement)
`dateDebut`	date	Non	Date de début
`dateFin`	date	Non	Date de fin

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": "depot",
      "typeLabel": "Dépôt",
      "reference": "DEP-2025-0046",
      "montant": 50000000,
      "soldeAvant": 125000000,
      "soldeApres": 175000000,
      "date": "2025-03-15T10:30:00+00:00",
      "description": "Approvisionnement Mars 2025",
      "createdBy": {
        "id": "...",
        "nom": "Admin User"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "type": "paiement",
      "typeLabel": "Paiement",
      "reference": "CYC-2025-003",
      "montant": -12500000,
      "soldeAvant": 175000000,
      "soldeApres": 162500000,
      "date": "2025-03-15T14:00:00+00:00",
      "description": "Cycle paiement Mars 2025 - 500 bénéficiaires",
      "cycleId": "..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Statistiques d'un compte

Endpoint

GET /api/comptes-operateurs/{id}/stats

Paramètres de requête

Paramètre	Type	Requis	Description
`periode`	string	Non	mois, trimestre, annee (défaut: mois)

Réponse

{
  "success": true,
  "data": {
    "compte": {
      "id": "...",
      "code": "OM-PCH-001",
      "soldeActuel": 162500000
    },
    "periode": {
      "debut": "2025-03-01",
      "fin": "2025-03-15"
    },
    "resume": {
      "totalDepots": 100000000,
      "nombreDepots": 2,
      "totalPaiements": 62500000,
      "nombrePaiements": 2500,
      "soldeDebut": 125000000,
      "soldeFin": 162500000
    },
    "evolution": [
      {"date": "2025-03-01", "solde": 125000000},
      {"date": "2025-03-05", "solde": 112500000},
      {"date": "2025-03-10", "solde": 162500000},
      {"date": "2025-03-15", "solde": 162500000}
    ],
    "moyennePaiementJour": 4166667
  }
}

Recalculer le solde

Endpoint

POST /api/comptes-operateurs/{id}/recalculer

Description

Recalcule le solde du compte en fonction de tous les mouvements enregistrés. Utile en cas de désynchronisation.

Réponse

{
  "success": true,
  "message": "Solde recalculé avec succès",
  "data": {
    "ancienSolde": 160000000,
    "nouveauSolde": 162500000,
    "difference": 2500000,
    "nombreMouvements": 156
  }
}

aviso

Cette opération peut modifier le solde affiché. Elle est recommandée uniquement en cas d'incohérence détectée.

Vue d'ensemble​

Permissions requises​

Liste des comptes opérateurs​

Endpoint​

Paramètres de requête​

Réponse​

Détail d'un compte​

Endpoint​

Réponse​

Créer un compte​

Endpoint​

Corps de la requête​

Opérateurs disponibles​

Réponse​

Liste des opérateurs​

Endpoint​

Réponse​

Statistiques globales​

Endpoint​

Paramètres de requête​

Réponse​

Alertes de solde​

Endpoint​

Réponse​

Compte par projet et opérateur​

Endpoint​

Paramètres de requête​

Réponse​

Enregistrer un dépôt​

Endpoint​

Corps de la requête​

Réponse​

Historique des mouvements​

Endpoint​

Paramètres de requête​

Réponse​

Statistiques d'un compte​

Endpoint​

Paramètres de requête​

Réponse​

Recalculer le solde​

Endpoint​

Description​

Réponse​

Vue d'ensemble

Permissions requises

Liste des comptes opérateurs

Endpoint

Paramètres de requête

Réponse

Détail d'un compte

Endpoint

Réponse

Créer un compte

Endpoint

Corps de la requête

Opérateurs disponibles

Réponse

Liste des opérateurs

Endpoint

Réponse

Statistiques globales

Endpoint

Paramètres de requête

Réponse

Alertes de solde

Endpoint

Réponse

Compte par projet et opérateur

Endpoint

Paramètres de requête

Réponse

Enregistrer un dépôt

Endpoint

Corps de la requête

Réponse

Historique des mouvements

Endpoint

Paramètres de requête

Réponse

Statistiques d'un compte

Endpoint

Paramètres de requête

Réponse

Recalculer le solde

Endpoint

Description

Réponse