API Réconciliation

L'API Réconciliation permet de rapprocher les paiements effectués avec les relevés des opérateurs Mobile Money.

Vue d'ensemble

Endpoint	Méthode	Description
`/api/reconciliation/sessions`	GET	Liste des sessions
`/api/reconciliation/sessions`	POST	Créer une session
`/api/reconciliation/sessions/{id}`	GET	Détail d'une session
`/api/reconciliation/sessions/{id}/validate`	POST	Valider une session
`/api/reconciliation/sessions/{id}/match`	POST	Effectuer le rapprochement
`/api/reconciliation/sessions/{id}/entries`	GET	Entrées de la session
`/api/reconciliation/sessions/{id}/entries/{entryId}/resolve`	POST	Résoudre une entrée
`/api/reconciliation/sessions/{id}/resolve-batch`	POST	Résolution en lot
`/api/reconciliation/sessions/{id}/finalize`	POST	Finaliser la session
`/api/reconciliation/stats`	GET	Statistiques globales
`/api/reconciliation/export/{id}`	GET	Exporter une session
`/api/reconciliation/templates`	GET	Templates d'import
`/api/reconciliation/operateurs`	GET	Opérateurs configurés

Permissions requises

transferts.reconciliation_view : Consultation des réconciliations
transferts.reconciliation_edit : Création et modification
transferts.reconciliation_validate : Validation et finalisation

Liste des sessions de réconciliation

Endpoint

GET /api/reconciliation/sessions

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)
`statut`	string	Non	Filtrer par statut
`operateur`	string	Non	Filtrer par opérateur
`cycle`	UUID	Non	Filtrer par cycle de paiement
`dateDebut`	date	Non	Date de début
`dateFin`	date	Non	Date de fin

Statuts de session

Statut	Description
`brouillon`	Session créée, en attente de données
`en_cours`	Rapprochement en cours
`a_valider`	En attente de validation
`valide`	Session validée et finalisée
`annule`	Session annulée

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "REC-2025-003",
      "nom": "Réconciliation Mars 2025 - Orange Money",
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "cycle": {
        "id": "...",
        "code": "CYC-2025-003",
        "nom": "Paiements Mars 2025"
      },
      "dateDebut": "2025-03-01",
      "dateFin": "2025-03-15",
      "statut": "en_cours",
      "statistiques": {
        "totalEntrees": 3500,
        "rapprochees": 3450,
        "nonRapprochees": 50,
        "enErreur": 12,
        "tauxRapprochement": 98.57
      },
      "createdAt": "2025-03-16T08:00:00+00:00",
      "createdBy": {
        "id": "...",
        "nom": "Admin User"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 25,
    "pages": 2
  }
}

Créer une session de réconciliation

Endpoint

POST /api/reconciliation/sessions

Corps de la requête

{
  "nom": "Réconciliation Mars 2025 - Orange Money",
  "operateur": "orange_money",
  "cycleId": "550e8400-e29b-41d4-a716-446655440001",
  "dateDebut": "2025-03-01",
  "dateFin": "2025-03-15",
  "fichierReleve": "file_upload_id",
  "options": {
    "toleranceMontant": 0,
    "toleranceDate": 2,
    "autoMatch": true
  }
}

Options de rapprochement

Option	Type	Description
`toleranceMontant`	int	Écart de montant toléré (en XOF)
`toleranceDate`	int	Écart de date toléré (en jours)
`autoMatch`	bool	Effectuer le rapprochement automatique

Réponse

{
  "success": true,
  "message": "Session de réconciliation créée",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "REC-2025-004",
    "statut": "brouillon",
    "entreesParsees": 3500
  }
}

Détail d'une session

Endpoint

GET /api/reconciliation/sessions/{id}

Réponse

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "REC-2025-003",
    "nom": "Réconciliation Mars 2025 - Orange Money",
    "operateur": "orange_money",
    "operateurLabel": "Orange Money",
    "cycle": {
      "id": "...",
      "code": "CYC-2025-003",
      "nom": "Paiements Mars 2025",
      "montantTotal": 87500000,
      "nombrePaiements": 3500
    },
    "dateDebut": "2025-03-01",
    "dateFin": "2025-03-15",
    "statut": "en_cours",
    "fichierReleve": {
      "nom": "releve_orange_mars_2025.xlsx",
      "taille": 245000,
      "uploadDate": "2025-03-16T08:00:00+00:00"
    },
    "options": {
      "toleranceMontant": 0,
      "toleranceDate": 2,
      "autoMatch": true
    },
    "statistiques": {
      "totalEntreesReleve": 3520,
      "totalPaiementsCycle": 3500,
      "rapprochees": 3450,
      "nonRapprocheesSIG": 50,
      "nonRapprocheesReleve": 70,
      "enErreur": 12,
      "montantRapproche": 86250000,
      "montantNonRapproche": 1250000,
      "tauxRapprochement": 98.57
    },
    "createdAt": "2025-03-16T08:00:00+00:00",
    "updatedAt": "2025-03-16T10:30:00+00:00",
    "createdBy": {
      "id": "...",
      "nom": "Admin User"
    }
  }
}

Effectuer le rapprochement

Endpoint

POST /api/reconciliation/sessions/{id}/match

Corps de la requête (optionnel)

{
  "criteresMatch": {
    "telephone": true,
    "montant": true,
    "reference": true,
    "date": false
  },
  "forceRematch": false
}

Réponse

{
  "success": true,
  "message": "Rapprochement effectué",
  "data": {
    "totalTraitees": 3500,
    "rapprochees": 3450,
    "nonRapprochees": 50,
    "nouveauxMatches": 3450,
    "duree": "12.5s"
  }
}

Entrées de la session

Endpoint

GET /api/reconciliation/sessions/{id}/entries

Paramètres de requête

Paramètre	Type	Requis	Description
`page`	int	Non	Numéro de page
`limit`	int	Non	Éléments par page
`statut`	string	Non	rapprochee, non_rapprochee, erreur, resolu
`source`	string	Non	sig (paiements SIG), releve (relevé opérateur)
`search`	string	Non	Recherche par téléphone ou référence

Réponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "source": "sig",
      "statut": "rapprochee",
      "paiement": {
        "id": "...",
        "reference": "TXN-2025-001234",
        "beneficiaire": "Mamadou Diallo",
        "telephone": "+245955123456",
        "montant": 25000,
        "datePaiement": "2025-03-05T10:30:00+00:00"
      },
      "entreeReleve": {
        "reference": "OM-2025-789456",
        "telephone": "+245955123456",
        "montant": 25000,
        "dateTransaction": "2025-03-05T10:32:00+00:00"
      },
      "scoreMatch": 100,
      "ecartMontant": 0,
      "ecartDate": 2
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440101",
      "source": "sig",
      "statut": "non_rapprochee",
      "paiement": {
        "id": "...",
        "reference": "TXN-2025-001235",
        "beneficiaire": "Fatou Sane",
        "telephone": "+245955789012",
        "montant": 25000,
        "datePaiement": "2025-03-05T11:00:00+00:00"
      },
      "entreeReleve": null,
      "raisonNonMatch": "Aucune transaction correspondante dans le relevé"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 3500,
    "pages": 70
  }
}

Résoudre une entrée

Endpoint

POST /api/reconciliation/sessions/{id}/entries/{entryId}/resolve

Corps de la requête

{
  "action": "match_manuel",
  "entreeReleveId": "550e8400-e29b-41d4-a716-446655440200",
  "commentaire": "Numéro de téléphone mis à jour depuis le dernier paiement"
}

Actions disponibles

Action	Description
`match_manuel`	Rapprocher manuellement avec une entrée du relevé
`ignorer`	Marquer comme ignoré (paiement annulé, etc.)
`erreur_operateur`	Signaler une erreur de l'opérateur
`erreur_sig`	Signaler une erreur dans le SIG
`en_attente`	Mettre en attente pour investigation

Réponse

{
  "success": true,
  "message": "Entrée résolue avec succès",
  "data": {
    "entryId": "550e8400-e29b-41d4-a716-446655440101",
    "nouveauStatut": "resolu",
    "action": "match_manuel"
  }
}

Résolution en lot

Endpoint

POST /api/reconciliation/sessions/{id}/resolve-batch

Corps de la requête

{
  "entries": [
    {
      "entryId": "550e8400-e29b-41d4-a716-446655440101",
      "action": "ignorer",
      "commentaire": "Paiement annulé"
    },
    {
      "entryId": "550e8400-e29b-41d4-a716-446655440102",
      "action": "match_manuel",
      "entreeReleveId": "550e8400-e29b-41d4-a716-446655440201"
    }
  ]
}

Réponse

{
  "success": true,
  "message": "12 entrées résolues",
  "data": {
    "traitees": 12,
    "reussies": 11,
    "echouees": 1,
    "erreurs": [
      {"entryId": "...", "message": "Entrée relevé déjà utilisée"}
    ]
  }
}

Finaliser la session

Endpoint

POST /api/reconciliation/sessions/{id}/finalize

Corps de la requête (optionnel)

{
  "commentaire": "Réconciliation Mars 2025 terminée. 50 cas non résolus transférés au prochain cycle.",
  "actions": {
    "marquerPaiementsEchoues": true,
    "notifierResponsables": true
  }
}

Contraintes

Toutes les entrées en erreur doivent être résolues
Un taux de rapprochement minimum de 95% est recommandé

Réponse

{
  "success": true,
  "message": "Session finalisée avec succès",
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "statut": "valide",
    "dateValidation": "2025-03-16T14:00:00+00:00",
    "resume": {
      "totalRapprochees": 3450,
      "totalNonRapprochees": 50,
      "tauxFinal": 98.57,
      "montantValide": 86250000
    }
  }
}

Statistiques globales

Endpoint

GET /api/reconciliation/stats

Paramètres de requête

Paramètre	Type	Requis	Description
`dateDebut`	date	Non	Date de début
`dateFin`	date	Non	Date de fin
`operateur`	string	Non	Filtrer par opérateur

Réponse

{
  "success": true,
  "data": {
    "periode": {
      "debut": "2025-01-01",
      "fin": "2025-03-15"
    },
    "resume": {
      "totalSessions": 12,
      "sessionsValidees": 10,
      "sessionsEnCours": 2,
      "tauxMoyenRapprochement": 97.8
    },
    "parOperateur": [
      {
        "operateur": "orange_money",
        "sessions": 8,
        "tauxMoyen": 98.2,
        "montantTotal": 450000000
      },
      {
        "operateur": "mtn_money",
        "sessions": 4,
        "tauxMoyen": 97.1,
        "montantTotal": 200000000
      }
    ],
    "tendance": [
      {"mois": "Janvier", "taux": 97.5},
      {"mois": "Février", "taux": 98.1},
      {"mois": "Mars", "taux": 98.5}
    ],
    "problemesFrequents": [
      {"type": "telephone_modifie", "count": 45},
      {"type": "paiement_en_attente", "count": 23},
      {"type": "doublon_operateur", "count": 12}
    ]
  }
}

Exporter une session

Endpoint

GET /api/reconciliation/export/{id}

Paramètres de requête

Paramètre	Type	Requis	Description
`format`	string	Non	csv, excel (défaut: excel)
`contenu`	string	Non	all, rapprochees, non_rapprochees

Réponse

Fichier Excel/CSV téléchargé avec les colonnes :

Référence paiement
Bénéficiaire
Téléphone
Montant SIG
Référence relevé
Montant relevé
Statut
Action
Commentaire

Templates d'import

Endpoint

GET /api/reconciliation/templates

Réponse

{
  "success": true,
  "data": [
    {
      "operateur": "orange_money",
      "label": "Orange Money",
      "colonnesRequises": ["reference", "telephone", "montant", "date_transaction"],
      "colonnesOptionnelles": ["statut", "frais"],
      "formatDate": "DD/MM/YYYY HH:mm",
      "templateUrl": "/api/reconciliation/templates/orange_money/download"
    },
    {
      "operateur": "mtn_money",
      "label": "MTN Mobile Money",
      "colonnesRequises": ["trans_id", "msisdn", "amount", "trans_date"],
      "formatDate": "YYYY-MM-DD HH:mm:ss",
      "templateUrl": "/api/reconciliation/templates/mtn_money/download"
    }
  ]
}

Opérateurs configurés

Endpoint

GET /api/reconciliation/operateurs

Réponse

{
  "success": true,
  "data": [
    {
      "code": "orange_money",
      "label": "Orange Money",
      "actif": true,
      "derniereSynchro": "2025-03-15T10:00:00+00:00",
      "comptesLies": 4
    },
    {
      "code": "mtn_money",
      "label": "MTN Mobile Money",
      "actif": true,
      "derniereSynchro": "2025-03-14T16:30:00+00:00",
      "comptesLies": 3
    }
  ]
}

Vue d'ensemble​

Permissions requises​

Liste des sessions de réconciliation​

Endpoint​

Paramètres de requête​

Statuts de session​

Réponse​

Créer une session de réconciliation​

Endpoint​

Corps de la requête​

Options de rapprochement​

Réponse​

Détail d'une session​

Endpoint​

Réponse​

Effectuer le rapprochement​

Endpoint​

Corps de la requête (optionnel)​

Réponse​

Entrées de la session​

Endpoint​

Paramètres de requête​

Réponse​

Résoudre une entrée​

Endpoint​

Corps de la requête​

Actions disponibles​

Réponse​

Résolution en lot​

Endpoint​

Corps de la requête​

Réponse​

Finaliser la session​

Endpoint​

Corps de la requête (optionnel)​

Contraintes​

Réponse​

Statistiques globales​

Endpoint​

Paramètres de requête​

Réponse​

Exporter une session​

Endpoint​

Paramètres de requête​

Réponse​

Templates d'import​

Endpoint​

Réponse​

Opérateurs configurés​

Endpoint​

Réponse​

Vue d'ensemble

Permissions requises

Liste des sessions de réconciliation

Endpoint

Paramètres de requête

Statuts de session

Réponse

Créer une session de réconciliation

Endpoint

Corps de la requête

Options de rapprochement

Réponse

Détail d'une session

Endpoint

Réponse

Effectuer le rapprochement

Endpoint

Corps de la requête (optionnel)

Réponse

Entrées de la session

Endpoint

Paramètres de requête

Réponse

Résoudre une entrée

Endpoint

Corps de la requête

Actions disponibles

Réponse

Résolution en lot

Endpoint

Corps de la requête

Réponse

Finaliser la session

Endpoint

Corps de la requête (optionnel)

Contraintes

Réponse

Statistiques globales

Endpoint

Paramètres de requête

Réponse

Exporter une session

Endpoint

Paramètres de requête

Réponse

Templates d'import

Endpoint

Réponse

Opérateurs configurés

Endpoint

Réponse