> ## 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.
# Clôture de Période
> Verrouiller les périodes comptables et transférer le résultat net vers les résultats reportés
## Aperçu
La **clôture de période** verrouille les périodes comptables passées en créant une écriture comptable `PERIOD_CLOSE` qui transfère tous les soldes des comptes de revenus et de dépenses vers les résultats reportés. Cela empêche les modifications des périodes clôturées et finalise les résultats financiers.
**Autorisation requise** : `periods:close` (pour clôturer/annuler les périodes), `reports:read` (pour prévisualiser)
La clôture de période est un contrôle comptable critique qui garantit que les enregistrements financiers restent exacts et inchangés après revue.
***
## Points d'Accès API
### Clôturer une Période
**Clôturer la prochaine période comptable non clôturée :**
```http theme={null}
POST /period-closing/close
Headers:
x-organization-id: {organizationId}
x-idempotency-key: {uniqueKey}
```
**En-têtes :**
| En-tête | Type | Obligatoire | Description |
| ------------------- | ------ | ----------- | ----------------------------------------------- |
| `x-organization-id` | string | Oui | ID de l'organisation |
| `x-idempotency-key` | string | Oui | Clé unique pour empêcher les clôtures en double |
**Réponse :**
```json theme={null}
{
"message": "Accounting period closed successfully",
"data": {
"periodStart": "2026-06-01T00:00:00.000Z",
"periodEnd": "2026-06-30T00:00:00.000Z",
"accountingPeriod": "MONTHLY",
"journalEntryId": "je-123",
"closedAt": "2026-07-01T10:30:00.000Z"
}
}
```
***
### Prévisualiser la Clôture de Période
**Prévisualiser ce qui se passera lors de la clôture :**
```http theme={null}
GET /period-closing/preview
Headers:
x-organization-id: {organizationId}
```
**Réponse :**
```json theme={null}
{
"message": "Close period preview fetched successfully",
"data": {
"accountingPeriod": "MONTHLY",
"periodStart": "2026-06-01T00:00:00.000Z",
"periodEnd": "2026-06-30T00:00:00.000Z",
"canClose": true,
"netProfitLoss": 125000.00,
"incomeStatement": {
"revenue": [
{
"accountId": "acc-123",
"accountName": "Interest Income",
"accountCode": "4000",
"debit": 0,
"credit": 200000,
"netAmount": 200000
}
],
"expenses": [
{
"accountId": "acc-456",
"accountName": "Operating Expenses",
"accountCode": "5000",
"debit": 75000,
"credit": 0,
"netAmount": 75000
}
],
"totalRevenue": 200000,
"totalExpenses": 75000,
"netIncome": 125000
},
"balanceSheet": { ... },
"transactions": [ ... ],
"validations": {
"hasWarnings": false,
"warnings": []
}
}
}
```
**Si la clôture est impossible :**
```json theme={null}
{
"canClose": false,
"reason": "No completed accounting period available to close",
"periodStart": null,
"periodEnd": null
}
```
***
### Annuler la Dernière Clôture de Période
**Annuler la clôture de période la plus récente :**
```http theme={null}
POST /period-closing/undo
Headers:
x-organization-id: {organizationId}
x-idempotency-key: {uniqueKey}
```
**En-têtes :**
| En-tête | Type | Obligatoire | Description |
| ------------------- | ------ | ----------- | -------------------------------------------------------------- |
| `x-organization-id` | string | Oui | ID de l'organisation |
| `x-idempotency-key` | string | Oui | Clé unique pour empêcher les opérations d'annulation en double |
**Réponse :**
```json theme={null}
{
"message": "Latest accounting period close undone successfully",
"data": {
"undoneJournalEntryId": "je-123",
"reversalJournalEntryId": "je-456",
"periodEnd": "2026-06-30T00:00:00.000Z",
"undoneAt": "2026-07-02T14:20:00.000Z"
}
}
```
**Important** : Seule la **plus récente** clôture de période peut être annulée. Impossible d'annuler une période passée arbitraire.
***
## Fonctionnement de la Clôture de Période
### 1. Détermination de la Période
**Première clôture** (aucune période déjà clôturée) :
* Trouve la date de transaction la plus ancienne (ou la date de création de l'organisation s'il n'y a aucune transaction)
* Détermine la fenêtre de période contenant cette date
* Cette fenêtre devient la première période à clôturer
**Clôtures suivantes** :
* Trouve la date de fin de la dernière période clôturée
* Période suivante = période immédiatement après la dernière période clôturée
* Clôture séquentielle automatique
**Contrôle de période courante** :
* Impossible de clôturer la période courante (période contenant la date d'aujourd'hui)
* Seules les périodes passées terminées peuvent être clôturées
***
### 2. Analyse des Revenus et Dépenses
Pour la période à clôturer, le système :
1. **Trouve toutes les transactions des comptes INCOME et EXPENSE**
* Écritures comptables POSTED uniquement
* Exclut les écritures PERIOD\_CLOSE
* Plage de dates : periodStart à periodEnd
2. **Calcule le solde net par compte**
```
Comptes INCOME : netIncome = credit - debit
Comptes EXPENSE : netExpense = debit - credit
```
3. **Identifie les comptes non nuls**
* Ignore les comptes avec solde net nul
* Seuls les comptes avec activité nécessitent des écritures de clôture
***
### 3. Écriture Comptable PERIOD\_CLOSE
Crée une écriture comptable avec `kind = 'PERIOD_CLOSE'` qui :
**Pour les comptes INCOME** (solde normal créditeur) :
* **DÉBITE** le compte de revenu (le remet à zéro)
* **CRÉDITE** les Résultats Reportés (augmente les capitaux propres)
**Pour les comptes EXPENSE** (solde normal débiteur) :
* **CRÉDITE** le compte de dépense (le remet à zéro)
* **DÉBITE** les Résultats Reportés (diminue les capitaux propres)
**Effet net** : Tous les comptes de revenus et dépenses reviennent à zéro, et le résultat net est transféré aux Résultats Reportés.
**Exemple** :
```
Période : 1-30 juin 2026
Revenu d'Intérêt (solde CRÉDIT) : 200 000
Dépenses Opérationnelles (solde DÉBIT) : 75 000
Résultat Net : 125 000
Écriture Comptable PERIOD_CLOSE (30 juin 2026) :
┌────────────────────────┬────────┬─────────┐
│ Compte │ Débit │ Crédit │
├────────────────────────┼────────┼─────────┤
│ Revenu d'Intérêt │ 200 000│ │ ← Remise à zéro du revenu
│ Dépenses Opération. │ │ 75 000 │ ← Remise à zéro des dépenses
│ Résultats Reportés │ │ 125 000 │ ← Résultat net vers capitaux propres
├────────────────────────┼────────┼─────────┤
│ TOTAL │ 200 000│ 200 000 │
└────────────────────────┴────────┴─────────┘
```
**Résultat** :
* Solde Revenu d'Intérêt : 0 (était 200 000)
* Solde Dépenses Opérationnelles : 0 (était 75 000)
* Solde Résultats Reportés : +125 000
***
### 4. Verrouillage des Transactions
Après publication de l'écriture de clôture :
**Impossible de créer/modifier** des transactions datées dans la période clôturée :
* ❌ Impossible d'enregistrer des dépôts datés du mois clôturé
* ❌ Impossible de modifier des prêts de la période clôturée
* ❌ Impossible de supprimer des dépenses de la période clôturée
* ❌ Impossible de créer des écritures comptables manuelles datées dans la période clôturée
* ❌ Erreur de validation système : "Transaction date in closed period"
**Les données de période clôturée restent accessibles** :
* ✅ Voir les transactions historiques (lecture seule)
* ✅ Générer des rapports pour les périodes clôturées
* ✅ Exporter les données pour les audits
* ✅ Voir les écritures comptables et soldes
**Les transactions en cours fonctionnent normalement** :
* ✅ Paiements de prêts pour des prêts créés dans des périodes clôturées
* ✅ Les rapports peuvent agréger périodes clôturées + ouvertes
***
## Pourquoi Clôturer les Périodes
**Intégrité financière :**
* Empêche les modifications rétroactives des dossiers finalisés
* Crée des instantanés historiques immuables
* Garantit que les rapports ne changent pas après distribution
**Exactitude comptable :**
* Transfère le résultat net aux résultats reportés
* Prépare les comptes de revenus/dépenses pour la nouvelle période
* Remet les comptes temporaires à zéro
**Conformité d'audit :**
* Démontre les contrôles internes sur les dossiers financiers
* Fournit des limites de période claires
* Établit une piste d'audit
**Avantages opérationnels :**
* Assurance que les périodes passées sont finales
* Empêche les antidatations accidentelles
* Arrête les modifications frauduleuses
***
## Types de Périodes Comptables
La période comptable de votre organisation est configurée dans les paramètres :
| Type de Période | Fréquence | Exemples de Dates de Clôture |
| --------------- | --------------- | ----------------------------------- |
| **MONTHLY** | Chaque mois | 31 janv., 28 fév., 31 mars... |
| **QUARTERLY** | Tous les 3 mois | 31 mars, 30 juin, 30 sept., 31 déc. |
| **YEARLY** | Annuellement | 31 déc. (ou fin d'exercice fiscal) |
**Clôture séquentielle** : Les périodes doivent être clôturées dans l'ordre (impossible de sauter des périodes).
***
## Avant de Clôturer une Période
**Checklist critique** - NE PAS clôturer avant finalisation :
**Transactions :**
* ✅ Tous les dépôts, retraits et prêts de la période sont enregistrés
* ✅ Toutes les dépenses et paiements sont publiés
* ✅ Aucune écriture comptable DRAFT en attente
* ✅ Tous les paiements de prêts sont traités
**Rapprochement :**
* ✅ Comptes bancaires rapprochés avec les relevés bancaires
* ✅ Soldes des membres vérifiés (contrôle par sondage des comptes d'épargne)
* ✅ Portefeuille de prêts rapproché (soldes restants corrects)
**Vérification :**
* ✅ La balance de vérification s'exécute et s'équilibre (débits = crédits)
* ✅ L'équation du bilan est respectée (Actifs = Passifs + Capitaux propres)
* ✅ Aucun solde négatif dans les comptes d'actif/passif (sauf attendu)
**Reporting :**
* ✅ États financiers générés (Bilan, Compte de Résultat)
* ✅ Rapports examinés par le trésorier/comptable
* ✅ Éléments inhabituels investigués et documentés
**Approbation :**
* ✅ Approbation de la direction/du conseil obtenue
* ✅ Procès-verbal documentant l'approbation (si requis)
**Sauvegarde :**
* ✅ Sauvegarde de base de données créée
* ✅ Rapports financiers archivés
***
## Flux de Clôture
**Processus recommandé :**
```bash theme={null}
GET /period-closing/preview
```
Examinez les dates de période, le résultat net et les validations
Comparez `netProfitLoss` au rapport Compte de Résultat de la période
Traitez tout avertissement dans le tableau `validations.warnings`
Présentez l'aperçu au trésorier/à la direction pour validation
```typescript theme={null}
const idempotencyKey = `period-close-${Date.now()}-${Math.random()}`;
```
```bash theme={null}
POST /period-closing/close
Headers:
x-idempotency-key: {idempotencyKey}
```
Vérifiez que la réponse contient `journalEntryId` et `closedAt`
Exportez et enregistrez le Bilan, le Compte de Résultat et l'écriture comptable de clôture
***
## Exemple : Clôture Mensuelle
**Scénario** : Clôturer juin 2026
**Calendrier :**
| Date | Action |
| -------- | ------------------------------------------------------------------ |
| 1 juil. | Enregistrer les dernières transactions de juin |
| 2 juil. | Rapprocher les relevés bancaires de juin |
| 3 juil. | Exécuter la balance de vérification de juin (vérifier l'équilibre) |
| 3 juil. | Prévisualiser la clôture : `GET /period-closing/preview` |
| 4 juil. | Générer les états financiers de juin |
| 4 juil. | Revue avec le trésorier, identifier le résultat net : 125 000 RWF |
| 5 juil. | Obtenir l'approbation du conseil pour clôturer juin |
| 5 juil. | **Clôturer la période de juin** : `POST /period-closing/close` |
| 6 juil.+ | Continuer normalement les transactions de juillet |
**Appels API :**
```bash theme={null}
# Preview
curl -X GET "/period-closing/preview" \
-H "x-organization-id: org-abc123"
# Close (after approval)
curl -X POST "/period-closing/close" \
-H "x-organization-id: org-abc123" \
-H "x-idempotency-key: period-close-june-2026"
```
**Résultat** :
* Période de juin verrouillée
* Compte de revenu d'intérêt remis à zéro
* Compte de dépenses opérationnelles remis à zéro
* Résultats reportés augmentés de 125 000 RWF (résultat net)
* Impossible de modifier les transactions de juin
***
## Annuler une Clôture de Période
**À utiliser avec parcimonie** : Annuler seulement pour des erreurs critiques. Des annulations fréquentes indiquent des procédures de clôture faibles.
**Quand annuler :**
* Erreur majeure découverte après clôture (transaction mal publiée)
* L'audit exige un ajustement dans la période clôturée
* Erreur de rapprochement bancaire trouvée après clôture
* Mauvaise période clôturée par erreur
**Limites :**
* ❗ Peut UNIQUEMENT annuler la **plus récente** clôture de période
* ❗ Impossible d'annuler des périodes passées arbitraires (ex. si juin, juillet, août sont clôturés, seul août peut être annulé)
* ❗ Pour annuler juin, il faut d'abord annuler août, puis juillet, puis juin
**Procédure :**
```bash theme={null}
# Undo last period close
curl -X POST "/period-closing/undo" \
-H "x-organization-id: org-abc123" \
-H "x-idempotency-key: undo-period-close-2026-07-02"
```
**Ce qui se passe :**
1. **Trouve l'écriture comptable PERIOD\_CLOSE la plus récente**
2. **La marque comme REVERSED** (status = 'REVERSED')
3. **Crée une écriture comptable REVERSAL** avec les débits/crédits opposés
* Original : DEBIT Revenu d'Intérêt, CREDIT Résultats Reportés
* Annulation : CREDIT Revenu d'Intérêt, DEBIT Résultats Reportés
4. **La période rouvre** - les transactions de cette période peuvent maintenant être modifiées
**Après annulation :**
* Effectuer les corrections nécessaires
* Réexécuter tous les rapports
* Obtenir une nouvelle approbation
* Clôturer à nouveau la période
**Bonne pratique** : Au lieu d'annuler, créez une écriture corrective dans la période courante qui référence l'erreur passée (si l'erreur n'est pas significative).
***
## Clôture Séquentielle
**Le backend impose automatiquement la clôture séquentielle :**
✅ **Séquence correcte** :
1. Clôturer janvier
2. Clôturer février
3. Clôturer mars
4. Clôturer avril
❌ **Impossible de sauter des périodes** :
* Clôturer janvier → Clôturer mars (en sautant février) ❌ NON AUTORISÉ
**Pourquoi séquentiel ?**
* Les états financiers s'appuient sur les périodes précédentes
* Le solde des résultats reportés est reporté
* Les périodes doivent être finalisées en ordre chronologique
**Implémentation** :
Le backend détermine automatiquement la prochaine période non clôturée :
* Si dernière clôture = 31 janvier, prochaine clôture = 1-28 février
* Si aucune période clôturée, prochaine clôture = période de la transaction la plus ancienne
***
## Clôture de Fin d'Année
**Considérations supplémentaires pour la fin d'exercice fiscal :**
Assurez-vous que les 12 mois sont clôturés (si année civile : janv.-déc.)
La clôture de décembre déclenche la fin d'année (ou le dernier mois de l'exercice fiscal)
```bash theme={null}
GET /reports/balance-sheet?asOfDate=2025-12-31
GET /reports/profit-loss?startDate=2025-01-01&endDate=2025-12-31
```
Les Résultats Reportés doivent inclure tout le résultat net de l'année clôturée
Fournissez aux auditeurs les états annuels et annexes justificatives
Conserver 7+ ans selon la réglementation (vérifier les lois locales)
**Remarque** : Les comptes de revenus et dépenses sont remis à zéro après chaque clôture de période (mensuelle, trimestrielle ou annuelle selon votre type de période).
***
## Erreurs Courantes
**"No completed accounting period available to close"**
**Cause** : La période courante (contenant la date d'aujourd'hui) ne peut pas être clôturée.
**Solution** : Attendre la fin de la période. Pour une clôture mensuelle : attendre le début du mois suivant.
***
**"User is not part of this organization"**
**Cause** : L'utilisateur authentifié n'a pas d'appartenance à l'organisation.
**Solution** : Vérifier que l'utilisateur a accès à l'organisation et que l'en-tête `x-organization-id` est correct.
***
**"x-idempotency-key header is required"**
**Cause** : En-tête de clé d'idempotence manquant.
**Solution** : Ajouter un `x-idempotency-key` unique à la requête :
```bash theme={null}
-H "x-idempotency-key: period-close-$(date +%s)"
```
***
**"No closed period available to undo"**
**Cause** : Tentative d'annulation alors qu'aucune période n'a été clôturée.
**Solution** : Vérifier que des périodes ont été clôturées avec le point d'accès preview.
***
**"Last closed period has already been undone"**
**Cause** : Tentative d'annuler la même période plusieurs fois.
**Solution** : Vérifier si la période est déjà rouverte. Impossible d'annuler deux fois.
***
## Bonnes Pratiques
**Checklist de clôture de période :**
**Calendrier :**
* ✅ Clôturer mensuellement dans les 7 jours suivant la fin du mois
* ✅ Ne pas se précipiter - terminer tous les rapprochements d'abord
* ✅ Planifier une date de clôture cohérente (ex. 5 du mois suivant)
**Vérification :**
* ✅ Toujours prévisualiser avant clôture (utiliser `/period-closing/preview`)
* ✅ Comparer le résultat net au rapport Compte de Résultat
* ✅ Faire vérifier par une deuxième personne avant clôture
* ✅ Examiner les avertissements de validation dans la réponse preview
**Documentation :**
* ✅ Documenter tout élément inhabituel avant clôture
* ✅ Maintenir une checklist de clôture (papier ou numérique)
* ✅ Noter la clôture dans le procès-verbal du conseil (si requis)
* ✅ Documenter la raison si une période est annulée
**Sauvegarde :**
* ✅ Créer une sauvegarde de base de données avant chaque clôture de période
* ✅ Archiver les états financiers immédiatement après clôture
* ✅ Conserver les sauvegardes pendant 7+ ans
**Idempotence :**
* ✅ Utiliser une clé d'idempotence unique pour chaque clôture/annulation
* ✅ Format : `period-close-YYYY-MM-DD-timestamp`
* ✅ Empêche les clôtures accidentelles en double
**Réouverture :**
* ✅ Annuler seulement pour les erreurs critiques
* ✅ Obtenir l'approbation de la direction avant annulation
* ✅ Documenter la raison de l'annulation dans la piste d'audit
* ✅ Re-clôturer rapidement après corrections
***
## Dépannage
**Q : Période clôturée trop tôt par erreur (transactions encore à enregistrer)**
R : Annulez immédiatement :
```bash theme={null}
POST /period-closing/undo
```
Terminez les tâches manquantes, puis clôturez à nouveau.
***
**Q : Besoin d'enregistrer une transaction datée dans une période clôturée**
R : **Option 1** (si critique) : Annuler la période, ajouter la transaction, re-clôturer
**Option 2** (recommandée) : Enregistrer dans la période courante avec une note :
```
Description: "Correcting June expense recorded in July -
See receipt dated June 25"
```
***
**Q : L'audit exige des changements dans une année clôturée**
R : Si la période clôturée doit être modifiée :
1. Annuler les périodes séquentiellement jusqu'à la période cible
2. Effectuer les ajustements approuvés par l'auditeur
3. Mettre à jour tous les rapports affectés
4. Re-clôturer toutes les périodes
5. Documenter dans le rapport d'audit
**Remarque** : Cela peut être fastidieux si de nombreuses périodes sont clôturées. Considérez la matérialité avant d'annuler plusieurs périodes.
***
**Q : Comment savoir quelle période sera clôturée ?**
R : Appelez d'abord le point d'accès preview :
```bash theme={null}
GET /period-closing/preview
```
La réponse affiche `periodStart` et `periodEnd` de la prochaine période à clôturer.
***
**Q : Puis-je clôturer les périodes dans le désordre ?**
R : Non. Le backend impose la clôture séquentielle. Les périodes doivent être clôturées chronologiquement.
***
**Q : Que deviennent les comptes INCOME/EXPENSE après clôture ?**
R : Ils sont remis à zéro. Le solde est transféré à RETAINED\_EARNINGS. Les comptes sont réinitialisés pour la période suivante.
***
**Q : Puis-je annuler une clôture de période d'il y a 6 mois ?**
R : Seulement si aucune période n'a été clôturée après elle. Seule la période la plus récente peut être annulée. Pour annuler il y a 6 mois, il faut annuler séquentiellement toutes les périodes clôturées depuis.
***
## Sujets Connexes
Voir le résultat net avant clôture
Vérifier les résultats reportés après clôture
Voir les écritures PERIOD\_CLOSE
Compléter les procédures de fin de période