Relevés de Comptes

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:readLes 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 :

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 :

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

[
  {
    "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 :

Valide les IDs de comptes
- Vérifie que tous les accountIds existent dans l’organisation
- Retourne 404 si un compte est introuvable
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
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é
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
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
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 :

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 :

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 :

Télécharger le relevé depuis la banque
Générer le relevé Agatabo pour la même période
Comparer ligne par ligne :
- DEBITS Agatabo = Dépôts bancaires (argent entrant)
- CREDITS Agatabo = Retraits bancaires (argent sortant)
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

Analyse de Compte de Prêt

Suivre les variations du capital du prêt :

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 :

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

GET /ledger-accounts?role=SAVINGS

Étape 2 : Extraire les accountIds depuis la réponse

const accountIds = accounts.map(account => account.id);

Étape 3 : Demander les relevés

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 :

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 :

Le compte possède une écriture de solde d’ouverture (écriture comptable avec transactionDate = null)
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 : ” - 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

GET /ledger-accounts?role=SAVINGS

Étape 2 : Générer les relevés

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

[
  {
    "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

Comptes du Grand Livre

Comprendre le plan comptable

Écritures Comptables

Détails des transactions derrière les relevés

Checklist de Clôture Mensuelle

Procédures de rapprochement et de clôture

Comprendre la Partie Double

Principes comptables des relevés

​Aperçu

​Point d’Accès API

​Structure de Réponse

​Comprendre les Débits et Crédits

​Fonctionnement

​Cas d’Utilisation Courants

​Relevés d’Épargne des Membres

​Rapprochement de Compte Bancaire

​Analyse de Compte de Prêt

​Relevés de Revenus/Dépenses

​Explication des Options de Relevé

​Génération Groupée de Relevés

​Filtrer les Comptes Sans Transactions

​Calcul du Solde d’Ouverture

​Descriptions des Transactions

​Bonnes Pratiques

​Dépannage

​Exemple : Relevés Membres Mensuels

​Sujets Connexes

Comptes du Grand Livre

Écritures Comptables

Checklist de Clôture Mensuelle

Comprendre la Partie Double

Aperçu

Point d’Accès API

Structure de Réponse

Comprendre les Débits et Crédits

Fonctionnement

Cas d’Utilisation Courants

Relevés d’Épargne des Membres

Rapprochement de Compte Bancaire

Analyse de Compte de Prêt

Relevés de Revenus/Dépenses

Explication des Options de Relevé

Génération Groupée de Relevés

Filtrer les Comptes Sans Transactions

Calcul du Solde d’Ouverture

Descriptions des Transactions

Bonnes Pratiques

Dépannage

Exemple : Relevés Membres Mensuels

Sujets Connexes