Rapport des Prêts en Cours

Aperçu

Le Rapport des Prêts en Cours fournit un instantané complet de tous les prêts actifs, en affichant le capital et les intérêts restants, les paiements attendus, les arriérés et l’historique de paiement de chaque prêt du portefeuille.

Autorisation requise : reports:readCe rapport est généré à partir des métadonnées des prêts, des échéanciers et des soldes des comptes du grand livre. Seuls les prêts avec capital restant dû > 0 sont inclus.

Point d’Accès API

Obtenir le rapport des prêts en cours :

GET /reports/loans-outstanding?expectedDate={date}
Headers:
  x-organization-id: {organizationId}

Paramètres de requête :

Paramètre	Type	Obligatoire	Description
`expectedDate`	string (date ISO)	Non	Date de calcul des soldes et arriérés. Par défaut, date actuelle.

Exemple de requête :

curl -X GET "https://api.agatabo.com/reports/loans-outstanding?expectedDate=2026-06-30" \
  -H "x-organization-id: org-abc123" \
  -H "Authorization: Bearer {token}"

Structure de Réponse

{
  "asOfDate": "2026-06-30T00:00:00.000Z",
  "totalOutstanding": 12950000.00,
  "totalExpected": 8500000.00,
  "totalArrears": 500000.00,
  "loans": [
    {
      "loanId": "loan-123",
      "accountNumber": "LOAN-001",
      "organizationUserId": "orguser-456",
      "organizationUserName": "Jane Smith",
      "organizationUserAccountNumber": "SAV-002",
      "loanDate": "2025-12-01T00:00:00.000Z",
      "termMonths": 12,
      "outstandingBalance": 415000.00,
      "monthlyInstallment": 43750.00,
      "expectedByDate": 306250.00,
      "arrears": 50000.00,
      "lastRepaymentDate": "2026-05-15T00:00:00.000Z"
    },
    {
      "loanId": "loan-124",
      "accountNumber": "LOAN-002",
      "organizationUserId": "orguser-789",
      "organizationUserName": "Peter Kalisa",
      "organizationUserAccountNumber": "SAV-003",
      "loanDate": "2026-02-01T00:00:00.000Z",
      "termMonths": 10,
      "outstandingBalance": 258000.00,
      "monthlyInstallment": 30800.00,
      "expectedByDate": 153750.00,
      "arrears": 0.00,
      "lastRepaymentDate": "2026-06-01T00:00:00.000Z"
    }
    // ... more loans
  ]
}

Champs de réponse :

Champ	Type	Description
`asOfDate`	string (datetime ISO)	Date de calcul du rapport (identique au paramètre `expectedDate`)
`totalOutstanding`	number	Solde total restant dû sur tous les prêts (capital + intérêt)
`totalExpected`	number	Montant total attendu comme payé à `asOfDate` selon les échéanciers
`totalArrears`	number	Montant total en retard (attendu - réellement payé)
`loans`	array	Enregistrements individuels des prêts

Champs de ligne de prêt :

Champ	Type	Description
`loanId`	string	ID du prêt
`accountNumber`	string	Numéro de compte du prêt
`organizationUserId`	string	ID utilisateur d’organisation de l’emprunteur
`organizationUserName`	string	Nom de l’emprunteur
`organizationUserAccountNumber`	string \| null	Numéro de compte d’épargne de l’emprunteur
`loanDate`	string (datetime ISO)	Date de décaissement du prêt
`termMonths`	number	Durée du prêt en mois
`outstandingBalance`	number	Montant actuel restant dû (capital + intérêt)
`monthlyInstallment`	number	Montant EMI (capital + intérêt par mois)
`expectedByDate`	number	Montant qui aurait dû être payé à `asOfDate`
`arrears`	number	Montant en retard (expectedByDate - actuallyPaid)
`lastRepaymentDate`	string \| null (datetime ISO)	Date du paiement le plus récent

Concepts Clés

Solde Restant Dû

Solde restant dû = Capital impayé + Intérêt impayé Calculé à partir des comptes du grand livre :

Prêt à Recevoir : Capital restant dû
Intérêt à Recevoir : Intérêt impayé (si l’intérêt est payé avec les échéances)
Pénalité à Recevoir : Pénalités impayées (si applicable)

Important : Utilise les soldes réels du grand livre, pas des calculs théoriques. Reflète tous les paiements publiés.

Attendu à la Date

Attendu à la date = Montant qui aurait dû être payé à expectedDate selon l’échéancier Logique de calcul :

Obtenir les échéances dues à expectedDate
- Filtrer l’échéancier avec dueDate <= expectedDate
Additionner le capital et l’intérêt attendus
- Capital : somme du capital des échéances dues
- Intérêt :
  - IN_ADVANCE : Tous les intérêts si le prêt a commencé avant expectedDate
  - WITH_INSTALLMENTS : Somme des intérêts des échéances dues

Exemple :

Prêt : 500 000 RWF à 12 % annuel, 12 mois
Échéance mensuelle : 44 424 RWF (capital + intérêt)
Date attendue : 30 juin 2026
Début du prêt : 1er janvier 2026

Échéances dues au 30 juin : 6 échéances
Capital attendu : ~250 000 RWF
Intérêt attendu : ~16 544 RWF
Attendu à la date : ~266 544 RWF

Arriérés

Arriérés = Montant attendu - Montant réellement payé Formule :

principalArrears = expectedPrincipalByDate - principalPaid
interestArrears = expectedInterestByDate - interestPaid
totalArrears = principalArrears + interestArrears

Arriérés = 0 : Le prêt est à jour (tous les paiements attendus ont été faits à temps) Arriérés > 0 : Le prêt est en retard (paiements échus impayés) Important : Les arriérés s’accumulent avec le temps. Si un emprunteur manque plusieurs échéances, les arriérés augmentent.

Fonctionnement

Le rapport des prêts en cours :

Trouve tous les prêts avec startDate <= expectedDate

SELECT * FROM loan_meta
WHERE organization_id = {orgId}
  AND start_date <= {expectedDate}

Calcule le solde restant dû depuis le grand livre
- Utilise le service grand livre getOutstandingBreakdownByLoan()
- Additionne toutes les lignes DEBIT et CREDIT des comptes de prêt
- Capital : solde du compte Prêt à Recevoir
- Intérêt : solde du compte Intérêt à Recevoir (si applicable)
Génère l’échéancier
- Utilise les paramètres du prêt : capital, taux d’intérêt, durée
- Calcule l’EMI avec la formule standard d’amortissement
- Crée l’échéancier avec les dates d’échéance
Calcule les paiements attendus à la date
- Filtre les échéances avec dueDate <= expectedDate
- Additionne le capital et l’intérêt des échéances dues
- Tient compte du moment de paiement des intérêts (IN_ADVANCE vs WITH_INSTALLMENTS)
Calcule les arriérés
- Compare le montant attendu au montant réellement payé (depuis le grand livre)
- arrears = max(0, expectedByDate - actuallyPaid)
Obtient la date du dernier remboursement
- Trouve l’écriture comptable LOAN_PAYMENT la plus récente
- Exclut les écritures annulées
- Retourne la date de transaction
Filtre les prêts entièrement payés
- Ignore les prêts avec principalBalance <= 0
- Inclut uniquement les prêts actifs avec soldes restants

Cas d’Utilisation

Rapport Mensuel au Conseil

Suivre la santé du portefeuille pour les réunions du conseil :

GET /reports/loans-outstanding?expectedDate=2026-06-30

Présenter au conseil :

Total restant dû : 12 950 000 RWF (capital déployé)
Total des arriérés : 500 000 RWF (3,86 % du portefeuille)
Nombre de prêts actifs : 45
Tendances de retard (comparaison au mois précédent)

Actions :

Si arriérés > 5 % : Intensifier les efforts de recouvrement
Si beaucoup de prêts en retard : Revoir les critères d’octroi
Si les arriérés diminuent : La stratégie de recouvrement fonctionne

Gestion du Recouvrement

Prioriser les efforts de recouvrement : Triez les prêts par arrears (du plus élevé au plus faible) pour identifier :

Les prêts avec les plus grands montants en retard
Les membres à contacter immédiatement
Les candidats aux pénalités ou actions légales

Exemple de flux de travail :

Exécuter le rapport quotidiennement ou hebdomadairement
Filtrer les prêts avec arrears > 0
Trier par arrears décroissant
Contacter les 10 emprunteurs les plus en retard
Suivre lastRepaymentDate pour identifier les prêts dormants (pas de paiements récents)

Planification de Liquidité

Comprendre le déploiement du capital :

GET /reports/loans-outstanding

Analyser :

totalOutstanding : Capital actuellement prêté (non disponible pour de nouveaux prêts)
Comparer à la caisse disponible (depuis le Bilan)
Ratio de liquidité : Caisse ÷ Épargne des Membres

Prise de décision :

Si caisse faible et encours élevé : Limiter les nouvelles approbations de prêts
Si caisse élevée et encours faible : Promouvoir les produits de prêt
Suivre les tendances de croissance des prêts mois par mois

Provisionnement pour Créances Douteuses

Calculer les réserves nécessaires : Norme de référence : provisionner 50-100 % des arriérés comme réserve pour créances douteuses

GET /reports/loans-outstanding?expectedDate=2026-06-30

Exemple :

Total des arriérés : 500 000 RWF
Provision recommandée : 250 000 - 500 000 RWF
Comparer aux réserves actuelles (depuis le Bilan)
Si les réserves sont insuffisantes : Allouer davantage depuis les bénéfices

Voir : Gestion des Réserves

Indicateurs de Qualité du Portefeuille

Calculer les indicateurs clés de performance : PAR30 (Portefeuille à Risque 30 jours) :

Pourcentage du portefeuille avec paiements en retard de >30 jours
Nécessite une analyse d’ancienneté (pas directement dans ce rapport)
Cible : < 10 %

Taux de retard :

Taux de retard = (prêts avec arriérés > 0) ÷ (total des prêts) × 100

Arriérés moyens par prêt :

Arriérés moyens = totalArrears ÷ nombre de prêts

Suivi du recouvrement :

Exécuter le rapport chaque mois
Comparer totalArrears au mois précédent
Calculer le taux de recouvrement : (Arriérés précédents - Arriérés actuels) ÷ Arriérés précédents × 100

Comparer les Périodes

Suivre les changements du portefeuille dans le temps :

# Prior month
GET /reports/loans-outstanding?expectedDate=2026-05-31

# Current month
GET /reports/loans-outstanding?expectedDate=2026-06-30

Analyse comparative :

Indicateur	Mai 2026	Juin 2026	Variation
Total Restant Dû	12 000 000	12 950 000	+950 000 (+7,92 %)
Total Arriérés	600 000	500 000	-100 000 (-16,67 %) ✓
Nombre de Prêts	43	45	+2 prêts
Encours Moyen/Prêt	279 070	287 778	+8 708

Insights :

Le portefeuille croît (2 nouveaux prêts décaissés)
Les arriérés diminuent malgré la croissance du portefeuille (bon signe - recouvrement efficace)
La taille moyenne des prêts augmente légèrement

Signaux d’alerte :

Encours qui augmente plus vite que les remboursements (risque de liquidité)
Arriérés qui augmentent mois par mois (problèmes de recouvrement)
Nombreux prêts sans paiements récents (vérifier lastRepaymentDate)

Indicateurs de Santé du Portefeuille

Portefeuille sain :

✅ Arriérés < 5 % du total restant dû
✅ La plupart des prêts avec arrears = 0 (paiements à jour)
✅ lastRepaymentDate dans les 30 derniers jours pour la plupart des prêts
✅ Total restant dû en croissance lente (prêts durables)

Signaux d’alerte :

⚠️ Arriérés 5-10 % du total restant dû
⚠️ 10-20 % des prêts en retard
⚠️ Tendance d’augmentation des arriérés mois par mois

Action nécessaire :

❌ Arriérés > 10 % du total restant dû
❌ >20 % des prêts en retard
❌ Grands prêts individuels en retard (risque d’emprunteur unique)
❌ Nombreux prêts sans paiements récents

Actions correctives :

Immédiat : Contacter les emprunteurs en retard
Court terme : Appliquer les pénalités selon la politique de l’organisation
Moyen terme : Renforcer les critères d’octroi, exiger des garants
Long terme : Augmenter les réserves, passer en perte les prêts irrécouvrables

Relation avec les Autres Rapports

Bilan : Les totaux des prêts en cours doivent se rapprocher avec le Bilan :

Bilan (Actifs) :
  Prêts à Recevoir :        12 500 000 RWF
  Intérêts à Recevoir :        450 000 RWF
  Total Actifs de Prêts :   12 950 000 RWF

Rapport des Prêts en Cours :
  Total Restant Dû :        12 950 000 RWF ✓ (doit correspondre)

Contrôle de rapprochement :

En cas d’écart : investiguer les paiements de prêt non publiés ou erreurs de données
Exécuter les deux rapports avec le même asOfDate pour comparaison

Sources de Données

Le rapport des prêts en cours est généré à partir de : Métadonnées des prêts :

SELECT * FROM loan_meta
WHERE organization_id = {orgId}
  AND start_date <= {expectedDate}

Comptes du grand livre :

Prêt à Recevoir (capital restant dû)
Intérêt à Recevoir (intérêt impayé)
Pénalité à Recevoir (pénalités impayées)

Service grand livre :

getOutstandingBreakdownByLoan(loanId)
// Returns: { outstandingPrincipal, outstandingInterest }

Écritures comptables (pour le dernier paiement) :

SELECT transaction_date FROM journal_entries
WHERE kind = 'LOAN_PAYMENT'
  AND status = 'POSTED'
  AND reversed_entry_id IS NULL
  AND transaction_date <= {expectedDate}
ORDER BY transaction_date DESC, created_at DESC
LIMIT 1

Calcul des échéances :

Utilise les conditions du prêt : capital, taux d’intérêt, période
Génère un échéancier d’amortissement avec EMI
Applique le type de calcul des intérêts et les règles de calendrier de paiement

Bonnes Pratiques

Gestion du portefeuille de prêts :Surveillance :

✅ Examiner chaque semaine pour détecter tôt les retards
✅ Trier par arriérés pour prioriser le recouvrement
✅ Suivre lastRepaymentDate pour identifier les prêts inactifs
✅ Exporter chaque mois pour les réunions du conseil et rapports financiers

Analyse :

✅ Comparer au mois précédent pour identifier les tendances
✅ Calculer les métriques du portefeuille : taux de retard, ratio d’arriérés
✅ Rapprocher totalOutstanding avec les actifs de prêts du Bilan
✅ Suivre le taux de recouvrement : réduction des arriérés mois par mois

Recouvrement :

✅ Contacter les emprunteurs lorsque arrears > 0 (ne pas attendre)
✅ Appliquer les pénalités de manière cohérente selon la politique de l’organisation
✅ Documenter les efforts de recouvrement et engagements des emprunteurs
✅ Escalader aux garants ou à l’action légale si nécessaire

Gestion des risques :

✅ Provisionner des réserves : 50-100 % du total des arriérés
✅ Limiter la concentration : taille maximale du prêt en % du portefeuille
✅ Revoir les critères d’octroi si les arriérés restent > 5 %
✅ Passer en perte les prêts irrécouvrables (ne pas gonfler artificiellement le portefeuille)

Reporting :

✅ Rapports au conseil : Inclure les prêts en cours avec le Bilan
✅ Rapports aux membres : Partager la santé du portefeuille en assemblée générale
✅ Réglementaire : Peut être requis pour les audits financiers
✅ Archiver les instantanés mensuels pour l’analyse historique

Questions Fréquentes

Q : Pourquoi totalOutstanding ne correspond-il pas à la somme de monthlyInstallment × termMonths ? R : totalOutstanding est le solde actuel (ce qui est dû maintenant), pas le montant original du prêt. Il diminue au fur et à mesure des paiements. Montant original du prêt = capital décaissé + total des intérêts (pas dans ce rapport). Q : Pourquoi arrears = 0 alors que lastRepaymentDate est ancien ? R : L’emprunteur peut avoir effectué de gros paiements anticipés couvrant des échéances futures. Les arriérés suivent seulement l’attendu vs le réel à expectedDate. Si le montant attendu est payé (même tôt), il n’y a pas d’arriérés. Q : Les arriérés peuvent-ils être négatifs ? R : Non. Le backend utilise max(0, expectedByDate - actuallyPaid). Les trop-perçus ne créent pas d’arriérés négatifs ; ils réduisent les arriérés futurs. Q : Pourquoi un prêt entièrement payé apparaît-il encore ? R : Le rapport exclut les prêts avec principalBalance <= 0. S’il apparaît, le prêt a encore du capital restant dû. Vérifiez le grand livre pour des erreurs de publication de paiement. Q : Comment monthlyInstallment est-il calculé ? R : Avec la formule EMI (Equated Monthly Installment) :

EMI = P × r × (1 + r)^n / ((1 + r)^n - 1)
Where:
  P = principal
  r = monthly interest rate
  n = number of months

Pour les intérêts payés d’avance, le calcul diffère (tous les intérêts à l’avance). Q : Pourquoi expectedByDate semble-t-il trop élevé ? R : Si l’intérêt est payé IN_ADVANCE, tous les intérêts sont attendus immédiatement au décaissement. Cela peut rendre expectedByDate très élevé tôt dans la durée du prêt. Q : Puis-je obtenir l’ancienneté des arriérés (30 jours, 60 jours, 90+ jours) ? R : Ce rapport ne décompose pas les arriérés par ancienneté. L’analyse d’ancienneté exige de comparer les arriérés actuels aux arriérés historiques des périodes précédentes. Suivez-les mensuellement pour calculer l’ancienneté manuellement.

Exemple : Analyse du Portefeuille

Scénario : Analyser la santé du portefeuille de prêts au 30 juin 2026

curl -X GET "https://api.agatabo.com/reports/loans-outstanding?expectedDate=2026-06-30" \
  -H "x-organization-id: org-abc123"

Réponse :

{
  "totalOutstanding": 12950000.00,
  "totalExpected": 8500000.00,
  "totalArrears": 500000.00,
  "loans": [45 loans]
}

Calculer les métriques : Ratio d’arriérés :

Ratio d'arriérés = 500 000 ÷ 12 950 000 × 100 = 3,86 %

Statut : ✓ Sain (< 5 %) Taux de retard :

Prêts avec arriérés > 0 : 8 prêts
Taux de retard = 8 ÷ 45 × 100 = 17,78 %

Statut : ⚠️ Alerte (10-20 % est un risque modéré) Encours moyen par prêt :

Moyenne = 12 950 000 ÷ 45 = 287 778 RWF

Plus grand prêt en retard : Filtrer les prêts où arrears > 0, trier par arrears décroissant :

{
  "organizationUserName": "Jane Smith",
  "outstandingBalance": 415000.00,
  "arrears": 50000.00,
  "lastRepaymentDate": "2026-05-15"
}

Action : Contacter Jane Smith (45 jours depuis le dernier paiement, 50 000 RWF en retard) Recommandation : La santé globale du portefeuille est acceptable (arriérés < 5 %), mais le taux de retard est élevé. Concentrez les efforts de recouvrement sur les 8 prêts en retard pour éviter que les arriérés augmentent.

Sujets Connexes

Enregistrement des Paiements de Prêt

Réduire les soldes restants

Application des Pénalités

Gérer les prêts en retard

Bilan

Rapprocher les actifs de prêts

Gestion des Réserves

Provisionner les créances douteuses

​Aperçu

​Point d’Accès API

​Structure de Réponse

​Concepts Clés

​Solde Restant Dû

​Attendu à la Date

​Arriérés

​Fonctionnement

​Cas d’Utilisation

​Rapport Mensuel au Conseil

​Gestion du Recouvrement

​Planification de Liquidité

​Provisionnement pour Créances Douteuses

​Indicateurs de Qualité du Portefeuille

​Comparer les Périodes

​Indicateurs de Santé du Portefeuille

​Relation avec les Autres Rapports

​Sources de Données

​Bonnes Pratiques

​Questions Fréquentes

​Exemple : Analyse du Portefeuille

​Sujets Connexes

Enregistrement des Paiements de Prêt

Application des Pénalités

Bilan

Gestion des Réserves

Aperçu

Point d’Accès API

Structure de Réponse

Concepts Clés

Solde Restant Dû

Attendu à la Date

Arriérés

Fonctionnement

Cas d’Utilisation

Rapport Mensuel au Conseil

Gestion du Recouvrement

Planification de Liquidité

Provisionnement pour Créances Douteuses

Indicateurs de Qualité du Portefeuille

Comparer les Périodes

Indicateurs de Santé du Portefeuille

Relation avec les Autres Rapports

Sources de Données

Bonnes Pratiques

Questions Fréquentes

Exemple : Analyse du Portefeuille

Sujets Connexes