API Grilles Tarifaires

Reference des endpoints pour la gestion des grilles tarifaires et le calcul des frais de transaction.

Base URL

/api/grilles-tarifaires

Endpoints

Lister les grilles

Retourne toutes les grilles actives groupees par operateur.

GET /api/grilles-tarifaires

Reponse :

{
  "success": true,
  "data": [
    {
      "operateur": "telecel",
      "operateurLabel": "TELECEL",
      "tranches": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "operateur": "telecel",
          "operateurLabel": "TELECEL",
          "numeroTranche": 1,
          "montantMin": 1,
          "montantMax": 2500,
          "taxeAdministrative": 200,
          "fraisRetrait": 100,
          "coutTotal": 300,
          "trancheLabel": "1 - 2 500 FCFA",
          "actif": true,
          "createdAt": "2026-05-04T10:00:00+00:00"
        }
      ]
    },
    {
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "tranches": [...]
    }
  ],
  "operateurs": {
    "telecel": "TELECEL",
    "orange_money": "Orange Money",
    "mtn": "MTN Mobile Money"
  }
}

Lister les operateurs

Retourne la liste des operateurs disponibles.

GET /api/grilles-tarifaires/operateurs

Reponse :

{
  "success": true,
  "data": [
    { "code": "telecel", "label": "TELECEL" },
    { "code": "orange_money", "label": "Orange Money" },
    { "code": "mtn", "label": "MTN Mobile Money" }
  ]
}

Calculer les frais

Calcule les frais pour un montant et un operateur.

GET /api/grilles-tarifaires/calculer?montant={montant}&operateur={operateur}

Parametres :

Parametre	Type	Description
montant	number	Montant en FCFA
operateur	string	Code operateur (telecel, orange_money, mtn)

Exemple :

GET /api/grilles-tarifaires/calculer?montant=70000&operateur=telecel

Reponse :

{
  "success": true,
  "data": {
    "montantBeneficiaire": 70000,
    "taxeAdministrative": 200,
    "fraisRetrait": 1200,
    "fraisTotal": 1400,
    "montantTotal": 71400,
    "tranche": {
      "id": "550e8400-e29b-41d4-a716-446655440006",
      "numero": 6,
      "label": "50 001 - 100 000 FCFA",
      "montantMin": 50001,
      "montantMax": 100000
    }
  }
}

Erreur (pas de tranche) :

{
  "success": false,
  "data": {
    "montantBeneficiaire": 3000000,
    "taxeAdministrative": 0,
    "fraisRetrait": 0,
    "fraisTotal": 0,
    "montantTotal": 3000000,
    "erreur": "Aucune tranche trouvée pour ce montant et cet opérateur"
  }
}

Comparer les operateurs

Compare les frais entre tous les operateurs pour un montant.

GET /api/grilles-tarifaires/comparer?montant={montant}

Exemple :

GET /api/grilles-tarifaires/comparer?montant=70000

Reponse :

{
  "success": true,
  "data": [
    {
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "montantBeneficiaire": 70000,
      "taxeAdministrative": 150,
      "fraisRetrait": 1000,
      "fraisTotal": 1150,
      "montantTotal": 71150
    },
    {
      "operateur": "telecel",
      "operateurLabel": "TELECEL",
      "montantBeneficiaire": 70000,
      "taxeAdministrative": 200,
      "fraisRetrait": 1200,
      "fraisTotal": 1400,
      "montantTotal": 71400
    },
    {
      "operateur": "mtn",
      "operateurLabel": "MTN Mobile Money",
      "montantBeneficiaire": 70000,
      "taxeAdministrative": 200,
      "fraisRetrait": 1300,
      "fraisTotal": 1500,
      "montantTotal": 71500
    }
  ]
}

Calculer en lot

Calcule les frais pour tous les paiements d'un cycle (simulation).

POST /api/grilles-tarifaires/calculer-lot

Corps :

{
  "cycleId": "550e8400-e29b-41d4-a716-446655440010",
  "operateur": "telecel"
}

Reponse :

{
  "success": true,
  "data": {
    "totalMontantBeneficiaires": 10500000,
    "totalFrais": 210000,
    "totalMontantTransaction": 10710000,
    "nbPaiements": 150,
    "operateur": "telecel",
    "operateurLabel": "TELECEL",
    "details": [
      {
        "paiementId": "550e8400-e29b-41d4-a716-446655440020",
        "beneficiaire": "Maria Silva",
        "montantBeneficiaire": 70000,
        "taxeAdministrative": 200,
        "fraisRetrait": 1200,
        "fraisTotal": 1400,
        "montantTotal": 71400,
        "tranche": {
          "numero": 6,
          "label": "50 001 - 100 000 FCFA"
        }
      }
    ]
  }
}

Appliquer les frais (individuel)

Applique les frais a un paiement specifique.

POST /api/grilles-tarifaires/appliquer/{paiementId}

Corps :

{
  "operateur": "telecel"
}

Reponse :

{
  "success": true,
  "message": "Frais appliqués avec succès",
  "data": {
    "montantBeneficiaire": 70000,
    "taxeAdministrative": 200,
    "fraisRetrait": 1200,
    "fraisTotal": 1400,
    "montantTotal": 71400,
    "tranche": {
      "numero": 6,
      "label": "50 001 - 100 000 FCFA"
    }
  }
}

Appliquer les frais en lot

Applique les frais a tous les paiements d'un cycle.

POST /api/grilles-tarifaires/appliquer-lot

Securite : ROLE_ADMIN requis

Corps :

{
  "cycleId": "550e8400-e29b-41d4-a716-446655440010",
  "operateur": "telecel"
}

Reponse :

{
  "success": true,
  "message": "150 paiements mis à jour avec succès",
  "data": {
    "totalMontantBeneficiaires": 10500000,
    "totalFrais": 210000,
    "totalMontantTransaction": 10710000,
    "nbPaiements": 150,
    "operateur": "telecel",
    "operateurLabel": "TELECEL",
    "details": [...]
  }
}

Creer une tranche

Cree une nouvelle tranche tarifaire.

POST /api/grilles-tarifaires

Securite : ROLE_ADMIN requis

Corps :

{
  "operateur": "telecel",
  "numeroTranche": 12,
  "montantMin": 2000001,
  "montantMax": 3000000,
  "taxeAdministrative": 200,
  "fraisRetrait": 15000,
  "actif": true,
  "description": "Nouvelle tranche haute valeur"
}

Reponse :

{
  "success": true,
  "message": "Tranche créée avec succès",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440050",
    "operateur": "telecel",
    "operateurLabel": "TELECEL",
    "numeroTranche": 12,
    "montantMin": 2000001,
    "montantMax": 3000000,
    "taxeAdministrative": 200,
    "fraisRetrait": 15000,
    "coutTotal": 15200,
    "trancheLabel": "2 000 001 - 3 000 000 FCFA",
    "actif": true,
    "description": "Nouvelle tranche haute valeur",
    "createdAt": "2026-07-31T14:30:00+00:00"
  }
}

Modifier une tranche

Met a jour une tranche existante.

PUT /api/grilles-tarifaires/{id}

Securite : ROLE_ADMIN requis

Corps :

{
  "taxeAdministrative": 250,
  "fraisRetrait": 1300,
  "description": "Mise à jour juillet 2026"
}

Note : L'operateur ne peut pas etre modifie.

Reponse :

{
  "success": true,
  "message": "Tranche mise à jour avec succès"
}

Desactiver une tranche

Desactive une tranche (soft delete).

DELETE /api/grilles-tarifaires/{id}

Securite : ROLE_ADMIN requis

Reponse :

{
  "success": true,
  "message": "Tranche désactivée avec succès"
}

Structure GrilleTarifaire

Champ	Type	Description
id	UUID	Identifiant unique
operateur	string	Code operateur (telecel, orange_money, mtn)
operateurLabel	string	Nom affichable de l'operateur
numeroTranche	int	Numero de sequence (1, 2, 3...)
montantMin	decimal	Montant minimum (inclusif)
montantMax	decimal	Montant maximum (inclusif)
taxeAdministrative	decimal	Frais administratif fixe
fraisRetrait	decimal	Frais de retrait variable
coutTotal	decimal	taxe + fraisRetrait (calcule)
trancheLabel	string	Label formate (ex: "50 001 - 100 000 FCFA")
actif	bool	Tranche active ou desactivee
description	string?	Notes optionnelles
createdAt	datetime	Date de creation
updatedAt	datetime?	Date de derniere modification

Structure CalculFrais

Champ	Type	Description
montantBeneficiaire	number	Montant que recoit le beneficiaire
taxeAdministrative	number	Frais administratif
fraisRetrait	number	Frais de retrait
fraisTotal	number	Total des frais
montantTotal	number	Montant total de la transaction
tranche	object?	Information sur la tranche utilisee
erreur	string?	Message d'erreur si calcul impossible

Codes erreur

Code	Description
400	Parametres invalides (montant ou operateur manquant)
403	Permission insuffisante (admin requis)
404	Tranche ou cycle non trouve
422	Operateur inconnu ou aucune tranche correspondante

Exemples d'utilisation

Simulation avant application

// 1. Calculer les frais pour un cycle
const simulation = await fetch('/api/grilles-tarifaires/calculer-lot', {
  method: 'POST',
  body: JSON.stringify({
    cycleId: 'uuid-cycle',
    operateur: 'telecel'
  })
});

const result = await simulation.json();
console.log(`Total frais: ${result.data.totalFrais} FCFA`);

// 2. Si acceptable, appliquer les frais
if (confirm(`Appliquer ${result.data.totalFrais} FCFA de frais ?`)) {
  await fetch('/api/grilles-tarifaires/appliquer-lot', {
    method: 'POST',
    body: JSON.stringify({
      cycleId: 'uuid-cycle',
      operateur: 'telecel'
    })
  });
}

Comparaison pour choix operateur

const comparison = await fetch('/api/grilles-tarifaires/comparer?montant=100000');
const result = await comparison.json();

// Trouver l'operateur le moins cher
const cheapest = result.data[0];
console.log(`Operateur recommande: ${cheapest.operateurLabel} (${cheapest.fraisTotal} FCFA)`);