> ## 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.
# Relevés de Comptes
> Générer l'historique des transactions et les soldes des comptes du grand livre
## Aperçu
Les **Relevés de Comptes** (aussi appelés **Relevés des Comptes du Grand Livre**) montrent l'historique complet des transactions de tout compte du grand livre, y compris le solde d'ouverture, tous les débits et crédits de la période, et le solde de clôture.
**Autorisation requise** : `ledger:read`
Les relevés peuvent être générés pour tout compte du grand livre : épargne des membres, comptes bancaires, prêts, revenus, dépenses, actifs ou passifs.
***
## Point d'Accès API
**Obtenir les relevés de comptes :**
```http theme={null}
POST /ledger-accounts/statements
Headers:
x-organization-id: {organizationId}
Body:
{
"accountIds": ["acc-123", "acc-456"],
"from": "2026-01-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": false
}
```
**Corps de la requête :**
| Champ | Type | Obligatoire | Description |
| -------------------------------- | ----------------- | ----------- | -------------------------------------------------------------------------------- |
| `accountIds` | string\[] | Oui | Tableau d'UUIDs de comptes du grand livre |
| `from` | string (date ISO) | Oui | Date de début de la période du relevé |
| `to` | string (date ISO) | Oui | Date de fin de la période du relevé |
| `option` | enum | Oui | Option du relevé : `'all'`, `'current'`, `'period'`, `'custom'` |
| `excludeZeroTransactionAccounts` | boolean | Non | Si true, exclut les comptes sans transactions dans la période. Par défaut false. |
**Options de relevé :**
| Option | Description |
| ----------- | ------------------------------------------------------------------------- |
| `'all'` | Toutes les transactions depuis la création du compte jusqu'à la date `to` |
| `'current'` | Période courante (généralement le mois courant) |
| `'period'` | Plage de dates spécifique de `from` à `to` |
| `'custom'` | Plage de dates personnalisée (identique à `'period'`) |
**Exemple de requête :**
```bash theme={null}
curl -X POST "https://api.agatabo.com/ledger-accounts/statements" \
-H "x-organization-id: org-abc123" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"accountIds": ["acc-789"],
"from": "2026-06-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": false
}'
```
***
## Structure de Réponse
```json theme={null}
[
{
"accountId": "acc-789",
"accountName": "Jane Smith - Savings",
"accountRole": "SAVINGS",
"accountType": "LIABILITY",
"accountStatus": "Active",
"periodStart": "2026-06-01T00:00:00.000Z",
"periodEnd": "2026-06-30T00:00:00.000Z",
"rows": [
{
"date": "2026-06-01T00:00:00.000Z",
"description": "Opening Balance",
"debit": null,
"credit": null,
"balance": 500000.00
},
{
"date": "2026-06-05T00:00:00.000Z",
"description": "Savings Deposit",
"debit": null,
"credit": 20000.00,
"balance": 520000.00
},
{
"date": "2026-06-10T00:00:00.000Z",
"description": "Savings Deposit",
"debit": null,
"credit": 15000.00,
"balance": 535000.00
},
{
"date": "2026-06-20T00:00:00.000Z",
"description": "Loan Disbursement",
"debit": 200000.00,
"credit": null,
"balance": 335000.00
},
{
"date": "2026-06-25T00:00:00.000Z",
"description": "Savings Deposit",
"debit": null,
"credit": 10000.00,
"balance": 345000.00
}
],
"totalDebit": 200000.00,
"totalCredit": 45000.00,
"closingBalance": 345000.00
}
]
```
**Champs de réponse :**
| Champ | Type | Description |
| ---------------- | --------------------- | ------------------------------------------------------------------ |
| `accountId` | string | UUID du compte du grand livre |
| `accountName` | string | Nom du compte (ex. "Jane Smith - Savings") |
| `accountRole` | string | Rôle du compte (SAVINGS, CASH, LOAN\_RECEIVABLE, etc.) |
| `accountType` | string | Type de compte (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) |
| `accountStatus` | string | "Active" ou "Inactive" |
| `periodStart` | string (datetime ISO) | Début de la période du relevé |
| `periodEnd` | string (datetime ISO) | Fin de la période du relevé |
| `rows` | array | Lignes de transactions (inclut le solde d'ouverture si applicable) |
| `totalDebit` | number | Somme de tous les débits de la période (hors solde d'ouverture) |
| `totalCredit` | number | Somme de tous les crédits de la période (hors solde d'ouverture) |
| `closingBalance` | number | Solde final |
**Champs de ligne :**
| Champ | Type | Description |
| ------------- | --------------------- | ------------------------------------------------------------------------ |
| `date` | string (datetime ISO) | Date de transaction |
| `description` | string | Description de la transaction (depuis la nature de l'écriture comptable) |
| `debit` | number \| null | Montant débit (null si transaction crédit) |
| `credit` | number \| null | Montant crédit (null si transaction débit) |
| `balance` | number | Solde courant après cette transaction |
***
## Comprendre les Débits et Crédits
**CRITIQUE** : Le sens des débits et crédits dépend du type de compte. Pour les comptes d'épargne des membres (type LIABILITY), les sens sont **opposés** à ce que vous pourriez attendre :
**Pour les comptes SAVINGS (type LIABILITY) :**
* **CREDIT** = Augmentation (les dépôts ajoutent au solde) ✓
* **DEBIT** = Diminution (les retraits, décaissements de prêts réduisent le solde) ✓
**Pour les comptes CASH (type ASSET) :**
* **DEBIT** = Augmentation (argent entrant) ✓
* **CREDIT** = Diminution (argent sortant) ✓
**Pour les comptes LOAN\_RECEIVABLE (type ASSET) :**
* **DEBIT** = Augmentation (prêt accordé) ✓
* **CREDIT** = Diminution (paiement reçu) ✓
**Pour les comptes REVENUE :**
* **CREDIT** = Augmentation (revenu gagné) ✓
* **DEBIT** = Diminution (rare) ✓
**Pour les comptes EXPENSE :**
* **DEBIT** = Augmentation (dépense engagée) ✓
* **CREDIT** = Diminution (rare) ✓
**Conseil** : Concentrez-vous sur la colonne **balance**, pas sur débit/crédit. Le solde montre le montant réel du compte.
***
## Fonctionnement
Le point d'accès des relevés de comptes :
1. **Valide les IDs de comptes**
* Vérifie que tous les accountIds existent dans l'organisation
* Retourne 404 si un compte est introuvable
2. **Pour chaque compte, récupère les écritures comptables dans la plage de dates**
* Filtre par transactionDate entre `from` et `to`
* Inclut uniquement les écritures POSTED (exclut DRAFT)
* Exclut les écritures annulées (reversedEntryId = null)
* Trie par date de transaction croissante
3. **Trouve le solde d'ouverture**
* Recherche l'écriture comptable avec transactionDate = null (écriture de solde d'ouverture)
* Calcule le solde après cette écriture
* L'inclut comme première ligne si approprié
4. **Crée les lignes de transaction**
* Pour chaque écriture comptable :
* Extrait le montant débit ou crédit pour ce compte
* Obtient le solde courant depuis le grand livre
* Formate la description depuis la nature de l'écriture comptable
5. **Calcule les totaux**
* Additionne tous les débits (hors ligne de solde d'ouverture)
* Additionne tous les crédits (hors ligne de solde d'ouverture)
* Obtient le solde de clôture depuis la dernière ligne
6. **Filtre les comptes sans transactions (optionnel)**
* Si `excludeZeroTransactionAccounts = true`
* Retire les comptes sans débit ni crédit pendant la période
***
## Cas d'Utilisation Courants
### Relevés d'Épargne des Membres
**Générer les relevés pour tous les membres :**
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-001", "acc-002", "acc-003"], // All member SAVINGS account IDs
"from": "2026-04-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": true // Exclude members with no activity
}
```
**Cas d'utilisation** : Relevés trimestriels des membres à distribuer pendant les réunions
**Ce que les membres voient :**
* Solde d'ouverture au début du trimestre
* Tous les dépôts effectués
* Tous les retraits (le cas échéant)
* Décaissements de prêts depuis leur épargne
* Distributions de dividendes
* Solde de clôture
***
### Rapprochement de Compte Bancaire
**Générer le relevé bancaire Agatabo :**
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-bank-123"], // Bank CASH account ID
"from": "2026-06-01",
"to": "2026-06-30",
"option": "period"
}
```
**Comparer avec le vrai relevé bancaire :**
1. Télécharger le relevé depuis la banque
2. Générer le relevé Agatabo pour la même période
3. Comparer ligne par ligne :
* DEBITS Agatabo = Dépôts bancaires (argent entrant)
* CREDITS Agatabo = Retraits bancaires (argent sortant)
4. Identifier les différences :
* Chèques non compensés
* Frais bancaires pas encore enregistrés
* Dépôts en transit
* Erreurs
Voir : [Checklist de Clôture Mensuelle](/fr/tontines/workflows/monthly-closing-checklist)
***
### Analyse de Compte de Prêt
**Suivre les variations du capital du prêt :**
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-loan-456"], // Specific LOAN_RECEIVABLE account
"from": "2026-01-01",
"to": "2026-06-30",
"option": "period"
}
```
**Analyse :**
* Solde d'ouverture : Capital au début de la période
* DEBITS : Prêts supplémentaires accordés (augmente la créance)
* CREDITS : Paiements reçus (diminue la créance)
* Solde de clôture : Capital restant dû
***
### Relevés de Revenus/Dépenses
**Suivre le revenu d'intérêt :**
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-interest-income"], // INTEREST_INCOME account
"from": "2026-01-01",
"to": "2026-12-31",
"option": "period"
}
```
**Affiche :**
* Tous les intérêts gagnés pendant l'année
* Détail par date de transaction
* Total du revenu d'intérêt (totalCredit pour les comptes de revenus)
***
## Explication des Options de Relevé
**`option: 'all'`**
* Inclut TOUTES les transactions depuis la création du compte jusqu'à la date `to`
* Ignore le paramètre `from`
* `periodStart` défini sur la date de création du compte ou la transaction la plus ancienne
* À utiliser pour : Historique complet du compte
**`option: 'current'`**
* Généralement le mois courant (l'implémentation peut varier)
* Utilise les dates `from` et `to` fournies
* À utiliser pour : Relevés mensuels
**`option: 'period'`**
* Plage de dates spécifique de `from` à `to`
* À utiliser pour : Périodes personnalisées (trimestrielles, annuelles, etc.)
**`option: 'custom'`**
* Identique à `'period'`
* Plage de dates spécifique de `from` à `to`
***
## Génération Groupée de Relevés
**Générer les relevés pour tous les comptes d'épargne des membres :**
**Étape 1** : Obtenir tous les IDs des comptes d'épargne des membres
```http theme={null}
GET /ledger-accounts?role=SAVINGS
```
**Étape 2** : Extraire les accountIds depuis la réponse
```typescript theme={null}
const accountIds = accounts.map(account => account.id);
```
**Étape 3** : Demander les relevés
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": accountIds,
"from": "2026-04-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": true
}
```
**Étape 4** : Traiter la réponse
La réponse contient un tableau de relevés (un par compte). Utilisez ces données pour :
* Générer des relevés PDF pour impression
* Créer des exports CSV pour analyse
* Envoyer les relevés par email aux membres
* Afficher dans l'interface web
***
## Filtrer les Comptes Sans Transactions
**Problème** : Lors de la génération groupée des relevés membres, certains membres peuvent n'avoir aucune activité pendant la période. Les inclure crée des relevés vides inutiles.
**Solution** : Utilisez `excludeZeroTransactionAccounts: true`
**Exemple :**
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-001", "acc-002", "acc-003", "acc-004"],
"from": "2026-06-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": true // ← Exclude inactive accounts
}
```
**Résultat** : Seuls les comptes avec au moins une transaction débit ou crédit dans la période sont retournés.
**Cas d'utilisation** : Relevés trimestriels - envoyer seulement aux membres qui ont eu de l'activité.
***
## Calcul du Solde d'Ouverture
Le **solde d'ouverture** apparaît comme première ligne si :
1. Le compte possède une écriture de solde d'ouverture (écriture comptable avec transactionDate = null)
2. Le relevé inclut la première transaction datée de ce compte
**Pourquoi est-ce conditionnel ?**
Si la période du relevé commence au milieu de l'année (ex. 1er juin), et que le compte a été créé le 1er janvier :
* Une écriture de solde d'ouverture existe (du 1er janvier)
* Mais le relevé n'inclut pas la première transaction datée (qui était en janvier)
* La ligne de solde d'ouverture n'est donc PAS incluse
* À la place, la première ligne montre le solde au 1er juin
**Quand le solde d'ouverture EST inclus :**
Un relevé avec `option: 'all'` inclut toutes les transactions depuis la création du compte :
* Une écriture de solde d'ouverture existe
* La première transaction datée est incluse
* La ligne de solde d'ouverture apparaît
***
## Descriptions des Transactions
Le champ **Description** vient du champ `kind` de l'écriture comptable, formaté pour être lisible :
| Nature d'Écriture Comptable | Description |
| --------------------------- | --------------------- |
| SAVINGS\_DEPOSIT | Savings Deposit |
| LOAN\_DISBURSEMENT | Loan Disbursement |
| LOAN\_PAYMENT | Loan Payment |
| LOAN\_PENALTY | Loan Penalty |
| EXPENSE\_PAYMENT | Expense Payment |
| DIVIDEND\_DISTRIBUTION | Dividend Distribution |
| RESERVE\_TOP\_UP | Reserve Top Up |
| BANK\_CHARGE | Bank Charge |
| PERIOD\_CLOSE | Period Close |
***
## Bonnes Pratiques
**Génération des relevés de comptes :**
**Pour les membres :**
* ✅ Générer des relevés trimestriels pour tous les membres actifs
* ✅ Utiliser `excludeZeroTransactionAccounts: true` pour ignorer les comptes inactifs
* ✅ Imprimer et distribuer pendant les réunions de membres pour la transparence
* ✅ Vérifier par sondage les relevés avec les enregistrements de dépôts
**Pour le rapprochement :**
* ✅ Générer les relevés bancaires chaque mois après téléchargement des relevés de banque
* ✅ Utiliser la plage de dates exacte du relevé bancaire
* ✅ Documenter toutes les différences (chèques non compensés, frais bancaires, etc.)
* ✅ Publier les écritures d'ajustement avant la clôture de période
**Pour l'analyse :**
* ✅ Utiliser `option: 'all'` pour l'historique complet du compte
* ✅ Utiliser `option: 'period'` pour des plages de dates spécifiques
* ✅ Exporter en CSV pour l'analyse en feuille de calcul
* ✅ Comparer période par période pour identifier les tendances
**Sécurité :**
* ✅ Les relevés d'épargne des membres contiennent des données sensibles
* ✅ Les générer uniquement pour le personnel autorisé
* ✅ Ne pas envoyer de relevés non chiffrés par email
* ✅ Remettre les relevés imprimés en main propre aux membres
* ✅ Stocker les exports dans des dossiers protégés par mot de passe
***
## Dépannage
**Q : Le solde ne correspond pas à ce que j'attends**
R : Vérifiez :
* Le bon compte a-t-il été sélectionné ? (les noms peuvent être similaires)
* La plage de dates inclut-elle toutes les transactions attendues ?
* Comparez avec les dossiers de dépôt/retrait
* Vérifiez avec le total du Bilan pour toute l'épargne des membres
**Q : Des transactions manquent dans le relevé**
R : Causes possibles :
* Date de transaction hors de la plage sélectionnée
* Transaction publiée par erreur sur un autre compte
* Transaction dans une période clôturée (vérifier les plages précédentes)
* Écriture comptable annulée ou supprimée (vérifier les journaux d'audit)
**Q : Je ne trouve pas le compte d'épargne du membre**
R : Solutions :
* Vérifiez que le membre a bien un compte d'épargne créé
* Recherchez par nom partiel (format du nom de compte : "{Name} - Savings")
* Vérifiez que le compte est actif (les comptes inactifs peuvent être masqués)
* Utilisez GET /ledger-accounts?role=SAVINGS pour tout lister
**Q : Le solde d'ouverture semble incorrect**
R : Solde d'ouverture = solde de clôture de la période précédente. S'il est incorrect :
* Vérifiez si les périodes précédentes ont été correctement rapprochées
* Générez le relevé de la période précédente pour tracer l'erreur
* Vérifiez que l'écriture de solde d'ouverture (transactionDate = null) est correcte
* Une écriture comptable d'ajustement peut être nécessaire
**Q : Pourquoi les débits et crédits sont-ils inversés pour l'épargne des membres ?**
R : Les comptes d'épargne des membres sont de type LIABILITY (argent que l'organisation doit aux membres). En comptabilité en partie double :
* Les comptes LIABILITY AUGMENTENT avec CREDIT
* Les comptes LIABILITY DIMINUENT avec DEBIT
C'est correct. Concentrez-vous plutôt sur la colonne de solde.
***
## Exemple : Relevés Membres Mensuels
**Scénario** : Générer les relevés de tous les membres pour juin 2026
**Étape 1** : Obtenir les IDs des comptes d'épargne membres
```http theme={null}
GET /ledger-accounts?role=SAVINGS
```
**Étape 2** : Générer les relevés
```http theme={null}
POST /ledger-accounts/statements
{
"accountIds": ["acc-001", "acc-002", "acc-003", ...],
"from": "2026-06-01",
"to": "2026-06-30",
"option": "period",
"excludeZeroTransactionAccounts": true
}
```
**Étape 3** : Traiter la réponse
```json theme={null}
[
{
"accountId": "acc-001",
"accountName": "Jane Smith - Savings",
"accountRole": "SAVINGS",
"accountType": "LIABILITY",
"periodStart": "2026-06-01T00:00:00.000Z",
"periodEnd": "2026-06-30T00:00:00.000Z",
"rows": [...],
"totalDebit": 0,
"totalCredit": 60000,
"closingBalance": 560000
},
{
"accountId": "acc-002",
"accountName": "Peter Kalisa - Savings",
...
}
]
```
**Étape 4** : Générer les PDFs et distribuer
Utilisez les données de relevé pour créer des PDFs formatés pour chaque membre, les imprimer, puis les remettre pendant la réunion mensuelle.
***
## Sujets Connexes
Comprendre le plan comptable
Détails des transactions derrière les relevés
Procédures de rapprochement et de clôture
Principes comptables des relevés