Configuration — Commissions

Règles de redistribution des frais (commissions) entre les bénéficiaires : plateforme, marchand, agent, partenaire. Pour la vue d'ensemble, voir Configuration — overview.

Le systeme de commissions permet de definir comment les frais collectes sont redistribues entre les differents acteurs (plateforme, marchands, agents, etc.).

CommissionRule

Champ	Type	Description
rule_type	varchar(50)	FEE_SPLIT, AGENT_COMMISSION, CASHBACK, REFERRAL_BONUS
transaction_type_id	uuid	FK → TransactionType
beneficiary_type	varchar(50)	PLATFORM, CORPORATE, MERCHANT, AGENT, EMPLOYEE, CLIENT, PROVIDER
agent_type_id	uuid	FK → AgentType (optionnel)
provider_id	uuid	Reference fournisseur (optionnel)
calculation_type	varchar(20)	Methode de calcul
percentage	decimal(5,2)	Part en pourcentage
fixed_amount	decimal(15,4)	Montant fixe
is_split	boolean	Fait partie d'un partage
split_group_id	uuid	Identifiant du groupe de partage
fallback_beneficiary_type	varchar(50)	Beneficiaire de repli
priority_order	integer	Priorite d'evaluation
min_amount / max_amount	decimal(15,4)	Tranche de montant applicable
country_code	varchar(3)	Pays specifique (null = global)
effective_from / effective_to	date	Periode de validite

Configurations de partage

Les regles de commission sont groupees par split_group_id. Un groupe represente une configuration complete de redistribution.

POST /commission-rules/configurations cree un groupe entier :

{
  "transaction_type_id": "uuid-du-CASH_IN",
  "rule_type": "FEE_SPLIT",
  "rules": [
    { "beneficiary_type": "PLATFORM", "percentage": 40 },
    { "beneficiary_type": "MERCHANT", "percentage": 35 },
    { "beneficiary_type": "AGENT", "percentage": 25, "agent_type_id": "uuid-distribution" }
  ],
  "effective_from": "2025-01-01"
}

Regle metier : pour FEE_SPLIT, le total des pourcentages doit etre egal a 100%.

A la creation, les configurations precedentes pour le meme type de transaction sont automatiquement desactivees.

Simulation de commissions

POST /commission-rules/configurations/simulate

// Requete
{
  "transactionTypeId": "uuid",
  "feeAmount": 1500,
  "countryCode": "CG",
  "effectiveDate": "2025-06-15"
}

// Reponse
{
  "totalAmount": 1500,
  "distributions": [
    { "beneficiary_type": "PLATFORM", "percentage": 40, "amount": 600 },
    { "beneficiary_type": "MERCHANT", "percentage": 35, "amount": 525 },
    { "beneficiary_type": "AGENT", "percentage": 25, "amount": 375 }
  ],
  "validationStatus": "valid",
  "totalPercentage": 100,
  "message": "Distribution valide (100%)"
}

AgentType

Types d'agents avec leurs capacites.

Champ	Type	Description
code	varchar(50)	Identifiant unique (distribution, compliance, internal...)
has_commission	boolean	Peut recevoir des commissions
requires_merchant	boolean	Necessite un rattachement marchand
requires_pdv	boolean	Necessite un point de vente
is_internal	boolean	Agent interne Nex
is_field_agent	boolean	Agent terrain
can_be_zoned	boolean	Peut etre affecte a des zones
default_commission_rate	decimal(5,2)	Taux de commission par defaut
display_order	integer	Ordre d'affichage

---