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/validate`	POST	Vérifier un fichier CT avant import (multipart `file`, `operateur`)
`/api/reconciliation/sessions/{id}/match`	POST	Effectuer le rapprochement
`/api/reconciliation/sessions/{id}/entries`	GET	Entrées de la session
`/api/reconciliation/entries/{id}/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/sessions/{id}/stats`	GET	Statistiques d'une session
`/api/reconciliation/sessions/{id}/export`	GET	Rapport de la session (JSON)
`/api/reconciliation/templates/{operateur}`	GET	Modèle d'import d'un opérateur (`ROLE_RAF`)
`/api/reconciliation/operateurs`	GET	Opérateurs configurés (`ROLE_RAF`)

Toutes ces routes demandent la permission transferts.reconciliation. Le fichier importé est le fichier CT renvoyé par l'opérateur.

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 (multipart/form-data)

Champ	Requis	Description
`file`	Oui	Fichier CT de l'opérateur
`operateur`	Oui	Code de l'opérateur
`dateDebut`, `dateFin`	Oui	Période couverte
`cycleId`	Non	Transfert concerné ; refusé s'il est déjà terminé

Réponse

{
  "success": true,
  "message": "Session creee avec 3500 lignes importees",
  "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

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

{
  "resolution": "corrige",
  "comment": "Numéro de téléphone mis à jour depuis le dernier paiement"
}

Résolution	Description
`accepte`	Écart accepté
`corrige`	Écart corrigé
`rejete`	Écart rejeté

Réponse : { "success": true, "message": "Entree resolue", "data": { … } }. Sans resolution : 400 Resolution requise ; entrée introuvable : 404.

Résolution en lot

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

{
  "entryIds": ["<uuid>", "<uuid>"],
  "resolution": "accepte",
  "comment": "Écarts d'arrondi"
}

Réponse : { "success": true, "message": "2 entrees resolues" }. Sans entryIds : 400 Liste d'entrees requise.

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}
    ]
  }
}

Rapport d'une session

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

Renvoie le rapport de la session en JSON ({ "success": true, "data": { … } }), que l'interface met en forme pour l'export.

Modèle d'import d'un opérateur

GET /api/reconciliation/templates/{operateur}

Décrit les colonnes attendues dans le fichier CT de cet opérateur. Un opérateur inconnu renvoie 400. Réservé au rôle ROLE_RAF.

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​

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 (multipart/form-data)​

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​

Résolution en lot​

Finaliser la session​

Endpoint​

Corps de la requête (optionnel)​

Contraintes​

Réponse​

Statistiques globales​

Endpoint​

Paramètres de requête​

Réponse​

Rapport d'une session​

Modèle d'import d'un opérateur​

Opérateurs configurés​

Endpoint​

Réponse​

Vue d'ensemble

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 (multipart/form-data)

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

Résolution en lot

Finaliser la session

Endpoint

Corps de la requête (optionnel)

Contraintes

Réponse

Statistiques globales

Endpoint

Paramètres de requête

Réponse

Rapport d'une session

Modèle d'import d'un opérateur

Opérateurs configurés

Endpoint

Réponse