> ## 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. # Workflow de Décaissement de Prêt > Processus de création et de décaissement des prêts ## Vue d'ensemble Le **Workflow de Décaissement de Prêt** dans Agatabo décrit le processus de création des prêts, de validation appropriée et d'enregistrement du décaissement avec une comptabilité exacte. **Implémentation actuelle** : la création et le décaissement du prêt se font **simultanément** dans un seul appel API. Le prêt est créé avec le statut `ACTIVE` et décaissé immédiatement. Le statut **PENDING existe** dans le schéma de base de données, mais il n'est pas actuellement utilisé par l'API. Un workflow d'approbation en plusieurs étapes pourra être ajouté dans de futures versions. *** ## Vue d'ensemble du workflow ``` Préparation → Création et validation → Décaissement automatique → Suivi ``` *** ## Étape 1 : Préparation avant le prêt **Qui** : Agent de crédit ou Administrateur **Avant de créer le prêt dans le système** : * Le Membre a le solde d'Épargne requis (généralement 20 à 30 % du montant du prêt) * Le Membre n'a aucun prêt existant `ACTIVE` ou `DEFAULTED` * Le Membre a le rôle "member" assigné (requis pour l'éligibilité au prêt) * Le Membre est actif dans l'organisation * Examiner les sources de revenu du Membre * Vérifier l'historique de prêt du Membre (défauts passés ?) * Vérifier que le Membre peut payer les échéances * Évaluer la solvabilité générale * **Garants** : autres membres actifs qui cosignent * **Nantissements** : actifs physiques (propriété, équipement) avec valeurs estimées * **Exigence d'Épargne** : solde d'Épargne minimum que le Membre doit maintenir * **Documents** : photos, titres, évaluations, accords * Déterminer le montant du Capital (dans les limites de l'organisation) * Décider la Période du prêt (mois) * Définir le taux d'Intérêt (selon la politique de l'organisation) * Choisir la méthode de calcul de l'Intérêt * Calculer les échéances estimées **Checklist avant la saisie dans le système** : * ✅ Membre éligible au prêt * ✅ Garanties suffisantes pour couvrir le montant du prêt * ✅ Conditions du prêt conformes aux politiques de l'organisation * ✅ Documentation requise collectée * ✅ Approbation du comité de prêt obtenue (si requise par l'organisation) *** ## Étape 2 : Création et Décaissement du Prêt **Qui** : Utilisateur avec la permission `loans:write` **Endpoint API** : `POST /loans` ### Requête ```http theme={null} POST /loans Headers: x-organization-id: {organizationId} x-idempotency-key: {unique-key} Body: { "organizationUserId": "orguser-123", "principalAmount": 500000, "period": 12, "interestRate": 10, "interestRateType": "YEARLY", "interestCalculationType": "REDUCING_BALANCE", "interestPaymentTiming": "WITH_INSTALLMENTS", "installmentType": "EQUAL_TOTAL", "paymentAllocationOrder": "INTEREST_FIRST", "startDate": "2026-06-01", "purpose": "Business expansion", "bankAccountId": "bank-456", "loanSecurities": [ { "type": "GUARANTOR", "organizationUserId": "orguser-789", "description": "John Doe - Co-signer" }, { "type": "COLLATERAL", "value": 600000, "description": "Motorcycle - 2020 model" } ], "disbursementFeePercentage": 1.0, "disbursementFeeType": "PERCENTAGE" } ``` **Champs requis** : | Champ | Type | Description | | ------------------------- | ------ | --------------------------------------------------------------------------------------------------------- | | `organizationUserId` | string | Emprunteur (doit avoir le rôle "member", être actif, et n'avoir aucun prêt existant `ACTIVE`/`DEFAULTED`) | | `principalAmount` | number | Montant du prêt | | `period` | number | Durée du prêt en mois | | `interestRate` | number | Pourcentage du taux d'Intérêt | | `interestRateType` | enum | "MONTHLY" ou "YEARLY" | | `interestCalculationType` | enum | "SIMPLE", "COMPOUND" ou "REDUCING\_BALANCE" | | `startDate` | string | Date de début du prêt (format ISO) | | `bankAccountId` | string | Compte Bancaire pour le Décaissement | **Champs optionnels** : | Champ | Type | Défaut | Description | | ---------------------------- | ------- | --------------------------------------- | -------------------------------------------------------- | | `interestPaymentTiming` | enum | Depuis les paramètres de l'organisation | "IN\_ADVANCE" ou "WITH\_INSTALLMENTS" | | `installmentType` | enum | Depuis les paramètres de l'organisation | "EQUAL\_PRINCIPAL" ou "EQUAL\_TOTAL" | | `paymentAllocationOrder` | enum | Depuis les paramètres de l'organisation | "INTEREST\_FIRST", "PRINCIPAL\_FIRST" ou "PROPORTIONAL" | | `purpose` | string | null | Description de l'objet du prêt | | `loanSecurities` | array | \[] | Garants, Nantissements, exigences d'Épargne | | `disbursementFeeType` | enum | Depuis les paramètres de l'organisation | "PERCENTAGE" ou "FIXED\_AMOUNT" | | `disbursementFeePercentage` | number | Depuis les paramètres de l'organisation | Pourcentage des frais (par ex. 1.0 = 1 %) | | `disbursementFeeFixedAmount` | number | Depuis les paramètres de l'organisation | Montant fixe des frais | | `bankChargeAmount` | number | null | Frais de virement bancaire | | `skipNegativeBalanceCheck` | boolean | false | Autoriser les soldes négatifs (à utiliser avec prudence) | *** ### Ce qui se passe automatiquement Lorsque le prêt est créé, le système effectue ces actions **atomiquement** dans une seule transaction de base de données : * Le Membre existe dans l'organisation * Le Membre est actif * Le Membre a le rôle "member" assigné * Le Membre n'a aucun prêt existant `ACTIVE` ou `DEFAULTED` **Erreur si** : le Membre est inéligible ou a déjà un prêt actif * Le montant du Capital est dans les limites configurées * La Période est dans le maximum autorisé (si configuré) * Capital ≤ (Épargne du membre × max\_loan\_percentage) * L'échelle du montant correspond aux paramètres de devise de l'organisation **Erreur si** : les politiques de prêt de l'organisation sont violées * Valeur totale des garanties ≥ montant du prêt * Les Garants sont des membres actifs * L'exigence d'Épargne ne dépasse pas l'Épargne disponible du Membre * Toutes les valeurs de garantie utilisent la bonne précision décimale **Erreur si** : garanties insuffisantes * Calcule l'EMI (échéance mensuelle équivalente) * Génère l'échéancier * Calcule l'Intérêt total * Applique les règles d'arrondi configurées **Échéances créées** avec des dates d'échéance basées sur la Période * Statut défini sur **ACTIVE** (pas PENDING) * Numéro de compte unique assigné au prêt * Échéancier verrouillé * Garanties stockées en JSON **Résultat** : prêt immédiatement actif et décaissé * Compte `LOAN_RECEIVABLE` (suivi du Capital) * Compte `INTEREST_RECEIVABLE` (suivi de l'Intérêt) * Compte `PENALTY_RECEIVABLE` (suivi des Pénalités) **Résultat** : comptes du Grand Livre dédiés à ce prêt **Écriture de base** (Intérêt avec échéances, frais depuis la caisse) : ``` Dr LOAN_RECEIVABLE 500,000 Dr INTEREST_RECEIVABLE total_interest Cr CASH (bank account) 500,000 - fee Cr INTEREST_INCOME total_interest Cr DISBURSEMENT_FEE_INCOME fee_amount ``` **Variantes** : * Si les frais sont déduits de l'Épargne : écriture `DISBURSEMENT_FEE_PAYMENT` séparée * Si l'Intérêt est payé d'avance depuis l'Épargne : écriture `INTEREST_PAID_IN_ADVANCE` séparée * Si l'Intérêt est payé d'avance depuis la caisse : `INTEREST_RECEIVABLE` n'est pas débité, `CASH` est réduit de l'Intérêt * Si frais bancaires : écriture `BANK_CHARGE` supplémentaire **Résultat** : prêt décaissé, comptes mis à jour Si l'organisation a activé l'e-mail/SMS : * E-mail envoyé à l'emprunteur avec les détails du prêt * SMS envoyé avec le message d'approbation du prêt * Le message inclut le montant de l'échéance et l'échéancier **Exemple de message** : "Votre prêt de 500 000 RWF a été approuvé ! 12 échéances mensuelles de 45 000 RWF chacune." *** ### Réponse **Succès (201 Created)** : ```json theme={null} { "message": "Loan created successfully", "data": { "id": "loan-123", "accountNumber": "L-00042", "organizationUserId": "orguser-123", "principalAmount": 500000, "period": 12, "interestRate": 10, "interestRateType": "YEARLY", "status": "ACTIVE", "startDate": "2026-06-01T00:00:00.000Z", "disbursementFee": 5000, "loanReceivableLedgerAccountId": "acc-456", "interestReceivableLedgerAccountId": "acc-457", "penaltyReceivableLedgerAccountId": "acc-458", "createdAt": "2026-06-13T10:30:00.000Z" } } ``` *** ### Erreurs | Statut | Erreur | Cause | | ------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------- | | 400 | "x-idempotency-key header is required" | Clé d'idempotence manquante | | 404 | "Organization user not found, inactive, or does not belong to this organization" | `organizationUserId` invalide ou Membre non actif | | 409 | "Organization user already has an active or defaulted loan" | Le Membre a déjà un prêt `ACTIVE` ou `DEFAULTED` | | 400 | "Loan period cannot exceed X month(s)" | La Période dépasse le paramètre `max_period` de l'organisation | | 400 | "Principal exceeds max allowed from max loan percentage rule" | Capital > (Épargne × `max_loan_percentage`) | | 400 | "Insufficient security coverage" | Total des garanties \< montant du prêt | | 400 | Erreurs de validation diverses | Données invalides, problèmes de précision décimale, etc. | *** ## Étape 3 : Après le Décaissement **Qui** : Agent de crédit, Trésorier ### Actions immédiates **Méthode 1 : déduction depuis l'Épargne** (si frais/Intérêt déduits de l'Épargne) : * Le système a déjà déduit le montant du compte d'Épargne du Membre * Le Membre reçoit en espèces : Capital - (frais si depuis la caisse) - (Intérêt si depuis la caisse et payé d'avance) * Compter l'argent en présence du Membre * Le Membre signe le reçu **Méthode 2 : virement bancaire** : * Virer depuis le Compte Bancaire de l'organisation vers le compte du Membre * Enregistrer le numéro de référence bancaire * Montant : Capital - (frais/Intérêt déduits de la caisse) **Méthode 3 : espèces depuis le bureau** : * Retirer depuis la banque de l'organisation * Remettre l'argent au Membre * Le Membre signe le reçu * Contrat de prêt signé * Documents de Nantissement (titres, évaluations, photos) * Accords de Garant * Reçu de Décaissement * Documents de Garantie * Exporter l'échéancier depuis le système * L'imprimer et le remettre au Membre * Expliquer les méthodes de paiement * Confirmer que les dates d'échéance sont comprises * Fournir les coordonnées du trésorier * Ajouter le prêt à la liste de suivi * Configurer des rappels automatiques de paiement (3 à 5 jours avant l'échéance) * Noter la date de la première échéance * Configurer les règles de Pénalité si applicable *** ### Suivi continu * Surveiller les dates d'échéance * Envoyer des rappels avant les échéances * Enregistrer rapidement les paiements avec `POST /loans/{loanId}/repay` * Mettre à jour le statut de paiement (à temps, en retard, manqué) * Identifier immédiatement les paiements en retard * Relancer le Membre (appel téléphonique, visite) * Appliquer les Pénalités selon la politique de l'organisation * Escalader au comité de prêt si nécessaire * Envisager une restructuration pour les cas difficiles * Examiner régulièrement les arriérés (rapport Prêts en Cours) * Suivre les jours de retard * Classer les prêts (courant, 1-30 jours, 31-90 jours, 90+ jours) * Mettre le statut à `DEFAULTED` si nécessaire *** ## Options de frais de Décaissement et de paiement de l'Intérêt ### Options de déduction des frais **Option 1 : frais déduits de la caisse** (par défaut) : ``` Dr LOAN_RECEIVABLE 500,000 Cr CASH 495,000 (500,000 - 5,000 fee) Cr DISBURSEMENT_FEE_INCOME 5,000 ``` Le Membre reçoit : 495 000 RWF **Option 2 : frais déduits de l'Épargne** (si `disbursementFeeFromSavings: true`) : ``` Main entry: Dr LOAN_RECEIVABLE 500,000 Cr CASH 500,000 Separate fee entry: Dr SAVINGS (member) 5,000 Cr DISBURSEMENT_FEE_INCOME 5,000 ``` Le Membre reçoit : 500 000 RWF en espèces, mais 5 000 sont déduits de l'Épargne *** ### Options de calendrier de paiement de l'Intérêt **Option 1 : Intérêt payé avec les échéances** (par défaut) : ``` Dr LOAN_RECEIVABLE 500,000 Dr INTEREST_RECEIVABLE 60,000 Cr CASH 500,000 Cr INTEREST_INCOME 60,000 ``` Le Membre paie l'Intérêt progressivement avec chaque échéance. **Option 2 : Intérêt payé d'avance depuis la caisse** (si `interestPaymentTiming: "IN_ADVANCE"`) : ``` Dr LOAN_RECEIVABLE 500,000 Cr CASH 440,000 (500,000 - 60,000 interest) Cr INTEREST_INCOME 60,000 ``` Le Membre reçoit : 440 000 RWF (Intérêt déduit à l'avance) **Option 3 : Intérêt payé d'avance depuis l'Épargne** (si `interestPaymentTiming: "IN_ADVANCE"` et `advanceInterestFromSavings: true`) : ``` Main entry: Dr LOAN_RECEIVABLE 500,000 Cr CASH 500,000 Advance interest entry: Dr SAVINGS (member) 60,000 Cr INTEREST_RECEIVABLE 60,000 ``` Le Membre reçoit : 500 000 RWF en espèces, mais 60 000 sont déduits de l'Épargne *** ## Configuration depuis les paramètres de l'organisation Plusieurs paramètres de prêt utilisent par défaut les paramètres globaux de l'organisation (champ `loanSettings`) : | Paramètre | Défaut | Description | | -------------------------------------- | -------------------- | --------------------------------------------------------------------- | | `interest_payment_timing` | "WITH\_INSTALLMENTS" | Moment où l'Intérêt est payé | | `installment_type` | "EQUAL\_PRINCIPAL" | Méthode de calcul des échéances | | `payment_allocation_order` | "INTEREST\_FIRST" | Méthode d'allocation des paiements | | `max_loan_percentage` | (aucun) | Prêt maximum comme multiple de l'Épargne (par ex. 3.0 = 3× l'Épargne) | | `max_period` | (aucun) | Durée maximale du prêt en mois | | `disbursement_fee_percentage` | 0 | Pourcentage de frais par défaut | | `disbursement_fee_type` | "PERCENTAGE" | "PERCENTAGE" ou "FIXED\_AMOUNT" | | `disbursement_fee_fixed_amount` | 0 | Montant fixe des frais | | `deduct_disbursement_fee_from_savings` | false | Déduire les frais de l'Épargne au lieu de la caisse | | `deduct_advance_interest_from_savings` | false | Déduire l'Intérêt payé d'avance de l'Épargne au lieu de la caisse | Ces paramètres s'appliquent automatiquement sauf s'ils sont remplacés dans la requête de création du prêt. *** ## Checklist complète du workflow ### Avant la création * ✅ Éligibilité du Membre vérifiée (Épargne, historique de prêt, statut actif) * ✅ Garanties documentées (Garants, Nantissements, documents) * ✅ Conditions du prêt calculées et conformes aux politiques * ✅ Documents requis collectés * ✅ Approbation du comité de prêt obtenue (si requise par l'organisation) * ✅ Le Membre comprend les conditions de remboursement ### Pendant la création (via API) * ✅ En-tête `x-idempotency-key` fourni * ✅ Tous les champs requis dans le corps de la requête * ✅ Montant du prêt dans les limites de la politique * ✅ Garanties suffisantes pour couvrir le prêt * ✅ Le Membre n'a aucun prêt `ACTIVE`/`DEFAULTED` existant * ✅ L'appel API réussit (réponse 201) ### Après le Décaissement * ✅ Fonds décaissés au Membre (espèces ou virement bancaire) * ✅ Le Membre signe le reçu de Décaissement * ✅ Documents de prêt classés * ✅ Échéancier fourni au Membre * ✅ Membre ajouté à la liste de rappels de paiement * ✅ Premier rappel de paiement planifié ### Suivi continu * ✅ Paiements enregistrés rapidement * ✅ Paiements en retard suivis immédiatement * ✅ Pénalités appliquées selon la politique * ✅ Statut du prêt mis à jour si nécessaire (`COMPLETED`, `DEFAULTED`) *** ## Problèmes courants **Erreur** : "Organization user already has an active or defaulted loan" **Cause** : le Membre a actuellement un prêt avec le statut `ACTIVE` ou `DEFAULTED` **Solution** : * Attendre que le prêt existant soit entièrement remboursé (statut = `COMPLETED`) * Ou déclarer le prêt existant en défaut si approprié (`POST /loans/{id}/default`) * Impossible d'avoir plusieurs prêts simultanés par Membre **Erreur** : "Insufficient security coverage" **Cause** : valeur totale des garanties \< montant du Capital du prêt **Solution** : * Ajouter plus de Garants * Augmenter la valeur du Nantissement * Réduire le montant du prêt * Exiger un solde d'Épargne plus élevé **Erreur** : "Principal exceeds max allowed from max loan percentage rule" **Cause** : montant du prêt > (Épargne du membre × `max_loan_percentage`) **Exemple** : Épargne = 100 000, `max_loan_percentage` = 3.0, maximum autorisé = 300 000 **Solution** : * Réduire le montant du prêt * Demander au Membre d'épargner davantage d'abord * Demander à l'organisation d'augmenter le paramètre `max_loan_percentage` **Erreur** : "Loan period cannot exceed X month(s)" **Cause** : Période du prêt > paramètre `max_period` de l'organisation **Solution** : * Réduire la Période du prêt * Demander à l'organisation d'augmenter le paramètre `max_period` **Situation** : prêt créé, mais le Membre veut annuler **Si créé le même jour** : * Le Membre peut rembourser immédiatement tout le Capital * Enregistrer le paiement : `POST /loans/{id}/repay` * Le statut du prêt passe à `COMPLETED` **Si plusieurs jours/semaines ont déjà passé** : * Le Membre doit rembourser selon l'échéancier * Ou négocier une restructuration avec l'agent de crédit * Impossible de supprimer un prêt décaissé (fonds déjà remis) **Problème** : les valeurs par défaut des paramètres de l'organisation ne sont pas utilisées **À vérifier** : * Les `loanSettings` de l'organisation sont-ils configurés ? * Les champs du corps de requête remplacent-ils les paramètres ? * Vérifier les paramètres avec `GET /organizations/{id}` **Note** : les paramètres du corps de requête ont priorité sur les valeurs par défaut de l'organisation *** ## Amélioration future : workflow en plusieurs étapes Le statut **PENDING** existe dans la base de données, mais n'est pas actuellement utilisé. Une future version pourra implémenter : 1. **POST /loans** avec status=PENDING (demande de prêt en brouillon) 2. Endpoint **PUT /loans/{id}/approve** pour changer PENDING → ACTIVE 3. **DELETE /loans/{id}** pour annuler les prêts PENDING 4. États de workflow et processus d'approbation Cela permettrait : * Demandes de prêt soumises pour examen * Approbation du comité avant Décaissement * Séparation de la demande et du Décaissement * Annulation des prêts non approuvés **Actuellement** : tous les prêts créés via l'API sont immédiatement `ACTIVE` et décaissés. *** ## Sujets connexes Documentation API détaillée des prêts Calculs d'Intérêt et types d'échéances Comment enregistrer les remboursements de prêt Surveiller le portefeuille de prêts