> ## Documentation Index
> Fetch the complete documentation index at: https://help.agatabo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rapport des Prêts en Cours

> Suivre les prêts actifs, soldes restants, arriérés et la santé du portefeuille

## 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.

<Note>
  **Autorisation requise** : `reports:read`

  Ce 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.
</Note>

***

## Point d'Accès API

**Obtenir le rapport des prêts en cours :**

```http theme={null}
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 :**

```bash theme={null}
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

```json theme={null}
{
  "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 :**

1. **Obtenir les échéances dues à expectedDate**
   * Filtrer l'échéancier avec `dueDate <= expectedDate`

2. **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 :**

```typescript theme={null}
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 :

1. **Trouve tous les prêts avec startDate \<= expectedDate**
   ```sql theme={null}
   SELECT * FROM loan_meta
   WHERE organization_id = {orgId}
     AND start_date <= {expectedDate}
   ```

2. **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)

3. **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

4. **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)

5. **Calcule les arriérés**
   * Compare le montant attendu au montant réellement payé (depuis le grand livre)
   * `arrears = max(0, expectedByDate - actuallyPaid)`

6. **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

7. **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 :**

```http theme={null}
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 :**

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

***

### Planification de Liquidité

**Comprendre le déploiement du capital :**

```http theme={null}
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

```http theme={null}
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](/fr/tontines/reserves/overview)

***

### 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 :**

```http theme={null}
# 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 :**

1. **Immédiat** : Contacter les emprunteurs en retard
2. **Court terme** : Appliquer les pénalités selon la politique de l'organisation
3. **Moyen terme** : Renforcer les critères d'octroi, exiger des garants
4. **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 :**

```sql theme={null}
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 :**

```typescript theme={null}
getOutstandingBreakdownByLoan(loanId)
// Returns: { outstandingPrincipal, outstandingInterest }
```

**Écritures comptables (pour le dernier paiement) :**

```sql theme={null}
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

<Note>
  **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
</Note>

***

## 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

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

**Réponse :**

```json theme={null}
{
  "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 :

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Enregistrement des Paiements de Prêt" icon="money-bill-wave" href="/fr/tontines/loans/recording-loan-payments">
    Réduire les soldes restants
  </Card>

  <Card title="Application des Pénalités" icon="gavel" href="/fr/tontines/loans/applying-penalties">
    Gérer les prêts en retard
  </Card>

  <Card title="Bilan" icon="scale-balanced" href="/fr/tontines/reports/balance-sheet">
    Rapprocher les actifs de prêts
  </Card>

  <Card title="Gestion des Réserves" icon="shield" href="/fr/tontines/reserves/overview">
    Provisionner les créances douteuses
  </Card>
</CardGroup>