> ## 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.
# Piste d'Audit
> Suivre toute l'activité système et les changements de données pour la conformité et la sécurité
## Aperçu
La **Piste d'Audit** journalise automatiquement toutes les actions importantes effectuées dans votre organisation, en fournissant un historique complet de qui a fait quoi, quand, et si l'action a réussi ou échoué.
**Autorisation requise** : `audit_logs:read` (portée ANY)
Les journaux d'audit sont automatiquement créés pour toutes les opérations CREATE, UPDATE, DELETE et CONFIGURE. Les opérations en lecture seule (READ, VIEW, SEARCH) sont exclues pour réduire le bruit.
***
## Point d'Accès API
**Obtenir les journaux d'audit :**
```http theme={null}
GET /audit-logs?page=1&limit=20&sortBy=createdAt&sortOrder=desc
Headers:
x-organization-id: {organizationId}
```
**Paramètres de requête :**
| Paramètre | Type | Obligatoire | Défaut | Description |
| -------------- | ----------------- | ----------- | ----------- | ------------------------------------------------------------------------- |
| `actorType` | enum | Non | - | Filtrer par acteur : `organization_admin`, `organization_user` |
| `resourceType` | enum | Non | - | Filtrer par ressource (voir les types de ressources ci-dessous) |
| `actionType` | enum | Non | - | Filtrer par action : `CREATE`, `UPDATE`, `DELETE`, `DEFAULT`, `CONFIGURE` |
| `startDate` | string (date ISO) | Non | - | Filtrer les journaux depuis cette date |
| `endDate` | string (date ISO) | Non | - | Filtrer les journaux jusqu'à cette date |
| `search` | string | Non | - | Rechercher dans le nom de l'acteur et la description |
| `page` | number | Non | 1 | Numéro de page pour la pagination |
| `limit` | number | Non | 20 | Enregistrements par page (max recommandé : 100) |
| `sortBy` | enum | Non | `createdAt` | Trier par : `createdAt`, `actorName`, `actionType`, `resourceType` |
| `sortOrder` | enum | Non | `desc` | Ordre de tri : `asc`, `desc` |
**Types de ressources :**
| Valeur | Description |
| ------------------- | ------------------------------------ |
| `ORGANIZATION` | Paramètres de l'organisation |
| `ORGANIZATION_USER` | Membres/utilisateurs |
| `SAVINGS` | Dépôts et retraits |
| `LOAN` | Création et modifications de prêts |
| `LOAN_INSTALLMENT` | Changements d'échéances de prêt |
| `LOAN_PAYMENT` | Enregistrement des paiements de prêt |
| `EXPENSE` | Enregistrement des dépenses |
| `ASSET` | Gestion des immobilisations |
| `TRANSACTION` | Transactions générales |
| `UPLOAD` | Téléversements de fichiers |
| `CONFIG` | Changements de configuration |
**Exemple de requête :**
```bash theme={null}
curl -X GET "/audit-logs?actorType=organization_admin&actionType=DELETE&page=1&limit=20" \
-H "x-organization-id: org-abc123" \
-H "Authorization: Bearer {token}"
```
***
## Structure de Réponse
```json theme={null}
{
"message": "Audit logs retrieved successfully",
"data": [
{
"id": "log-123",
"actorName": "John Doe",
"actorType": "organization_admin",
"actionType": "CREATE",
"resourceType": "LOAN",
"description": "Created loan for Jane Smith - 500,000 RWF",
"metadata": {
"status": "success",
"memberName": "Jane Smith",
"amount": 500000,
"term": 12,
"interestRate": 10
},
"createdAt": "2026-06-10T14:32:15.000Z"
},
{
"id": "log-124",
"actorName": "Sarah Lee",
"actorType": "organization_user",
"actionType": "CREATE",
"resourceType": "SAVINGS",
"description": "Recorded deposit for Peter Kalisa - 20,000 RWF",
"metadata": {
"status": "success",
"memberName": "Peter Kalisa",
"amount": 20000,
"paymentMethod": "Cash"
},
"createdAt": "2026-06-10T09:15:22.000Z"
},
{
"id": "log-125",
"actorName": "Mark Johnson",
"actorType": "organization_admin",
"actionType": "DELETE",
"resourceType": "EXPENSE",
"description": "Attempted to delete expense",
"metadata": {
"status": "failed"
},
"createdAt": "2026-06-10T16:45:33.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 523,
"totalPages": 27,
"hasNextPage": true,
"hasPreviousPage": false
}
}
```
**Champs de réponse :**
| Champ | Type | Description |
| -------------- | --------------------- | ----------------------------------------------------------------------- |
| `id` | string | ID du journal d'audit |
| `actorName` | string | Nom de la personne qui a effectué l'action |
| `actorType` | enum | Type d'acteur : `organization_admin`, `organization_user` |
| `actionType` | enum | Action effectuée : `CREATE`, `UPDATE`, `DELETE`, `DEFAULT`, `CONFIGURE` |
| `resourceType` | enum | Type de ressource affectée |
| `description` | string | Description lisible de l'action |
| `metadata` | object | Détails supplémentaires incluant `status` (success/failed) |
| `createdAt` | string (datetime ISO) | Moment où l'action a eu lieu |
**Champs de pagination :**
| Champ | Type | Description |
| ----------------- | ------- | ---------------------------------------------------- |
| `page` | number | Numéro de page actuel |
| `limit` | number | Enregistrements par page |
| `totalCount` | number | Total des journaux d'audit correspondant aux filtres |
| `totalPages` | number | Nombre total de pages disponibles |
| `hasNextPage` | boolean | Pages disponibles après la page actuelle |
| `hasPreviousPage` | boolean | Pages disponibles avant la page actuelle |
***
## Ce qui est Journalisé
**Journalisé automatiquement :**
**Opérations CREATE :**
* ✅ Création d'un nouveau prêt
* ✅ Enregistrement d'un nouveau dépôt
* ✅ Enregistrement d'une nouvelle dépense
* ✅ Ajout d'une nouvelle immobilisation
* ✅ Inscription d'un nouveau membre
* ✅ Envoi d'une nouvelle invitation
**Opérations UPDATE :**
* ✅ Modifications de prêts
* ✅ Changements d'informations de membre
* ✅ Mises à jour de configuration
* ✅ Assignations de rôles
**Opérations DELETE :**
* ✅ Suppression de dépense
* ✅ Cession d'actif
* ✅ Désactivation de membre
**Opérations CONFIGURE :**
* ✅ Changements de paramètres de l'organisation
* ✅ Modifications d'autorisations
* ✅ Mises à jour de configuration système
**NON journalisé (pour réduire le bruit) :**
* ❌ Opérations READ (consultation de pages, rapports)
* ❌ Opérations VIEW (parcours des données)
* ❌ Opérations SEARCH (recherche d'enregistrements)
* ❌ Actions d'administrateur système (exclues de la piste d'audit de l'organisation)
***
## Filtrer les Journaux d'Audit
### Filtrer par Type d'Acteur
**Administrateurs de l'organisation uniquement :**
```bash theme={null}
GET /audit-logs?actorType=organization_admin
```
Affiche les actions des administrateurs avec autorisations élevées.
**Utilisateurs de l'organisation uniquement :**
```bash theme={null}
GET /audit-logs?actorType=organization_user
```
Affiche les actions des membres/personnel ordinaires.
***
### Filtrer par Type de Ressource
**Activités liées aux prêts :**
```bash theme={null}
GET /audit-logs?resourceType=LOAN
```
**Dépôts/retraits d'épargne :**
```bash theme={null}
GET /audit-logs?resourceType=SAVINGS
```
**Changements de membres :**
```bash theme={null}
GET /audit-logs?resourceType=ORGANIZATION_USER
```
***
### Filtrer par Type d'Action
**Créations uniquement :**
```bash theme={null}
GET /audit-logs?actionType=CREATE
```
**Suppressions uniquement (sensible) :**
```bash theme={null}
GET /audit-logs?actionType=DELETE
```
**Changements de configuration :**
```bash theme={null}
GET /audit-logs?actionType=CONFIGURE
```
***
### Filtrer par Plage de Dates
**7 derniers jours :**
```bash theme={null}
GET /audit-logs?startDate=2026-06-05&endDate=2026-06-12
```
**Mois spécifique :**
```bash theme={null}
GET /audit-logs?startDate=2026-06-01&endDate=2026-06-30
```
***
### Rechercher par Mots-clés
**Trouver les actions d'un utilisateur spécifique :**
```bash theme={null}
GET /audit-logs?search=John%20Doe
```
**Trouver des descriptions de transactions spécifiques :**
```bash theme={null}
GET /audit-logs?search=Jane%20Smith
```
La recherche se fait dans les champs `actorName` et `description` (insensible à la casse).
***
### Combiner les Filtres
**Suppressions par administrateurs le mois dernier :**
```bash theme={null}
GET /audit-logs?actorType=organization_admin&actionType=DELETE&startDate=2026-05-01&endDate=2026-05-31
```
**Opérations de prêt échouées :**
```bash theme={null}
GET /audit-logs?resourceType=LOAN&search=failed
```
***
## Pagination
**Défaut** : 20 enregistrements par page
**Naviguer entre les pages :**
```bash theme={null}
# Page 1
GET /audit-logs?page=1&limit=20
# Page 2
GET /audit-logs?page=2&limit=20
# Taille de page personnalisée (50 enregistrements)
GET /audit-logs?page=1&limit=50
```
**Utiliser l'objet pagination :**
```json theme={null}
{
"pagination": {
"page": 2,
"limit": 20,
"totalCount": 523,
"totalPages": 27,
"hasNextPage": true,
"hasPreviousPage": true
}
}
```
**Logique de navigation :**
* Si `hasNextPage = true` : Demander `page + 1`
* Si `hasPreviousPage = true` : Demander `page - 1`
***
## Tri
**Plus récent d'abord (par défaut) :**
```bash theme={null}
GET /audit-logs?sortBy=createdAt&sortOrder=desc
```
**Plus ancien d'abord :**
```bash theme={null}
GET /audit-logs?sortBy=createdAt&sortOrder=asc
```
**Trier par nom d'acteur (alphabétique) :**
```bash theme={null}
GET /audit-logs?sortBy=actorName&sortOrder=asc
```
**Trier par type d'action :**
```bash theme={null}
GET /audit-logs?sortBy=actionType&sortOrder=asc
```
**Trier par type de ressource :**
```bash theme={null}
GET /audit-logs?sortBy=resourceType&sortOrder=asc
```
***
## Détection du Statut
**Réussite vs Échec :**
Le backend détermine le statut à partir du code de réponse HTTP :
* **Status = 'success'** : HTTP 200-299 (opération réussie)
* **Status = 'failed'** : HTTP 400+ (erreur survenue)
**Vérifier le statut :**
```json theme={null}
{
"metadata": {
"status": "success"
}
}
```
**Exemple d'opération échouée :**
```json theme={null}
{
"actionType": "DELETE",
"resourceType": "EXPENSE",
"description": "Attempted to delete expense",
"metadata": {
"status": "failed"
}
}
```
**Cas d'utilisation** : Trouver toutes les opérations échouées pour identifier les problèmes :
```bash theme={null}
GET /audit-logs?search=failed
```
***
## Cas d'Utilisation
### Conformité et Audit
**Revue annuelle d'audit :**
```bash theme={null}
GET /audit-logs?startDate=2025-01-01&endDate=2025-12-31&limit=100
```
Exporter et fournir aux auditeurs comme preuve de :
* Toutes les transactions financières
* Autorisation appropriée
* Suivi des changements
***
### Surveillance de Sécurité
**Suivre les suppressions (opérations sensibles) :**
```bash theme={null}
GET /audit-logs?actionType=DELETE
```
**Surveiller les actions d'administrateurs :**
```bash theme={null}
GET /audit-logs?actorType=organization_admin
```
**Détecter les tentatives d'accès non autorisées :**
* Les opérations échouées peuvent indiquer des problèmes d'autorisation
* Les tendances inhabituelles (nombreuses tentatives échouées) méritent investigation
***
### Dépannage
**Trouver qui a créé une entrée erronée :**
```bash theme={null}
GET /audit-logs?resourceType=LOAN&search=Jane%20Smith&startDate=2026-06-01
```
Examinez la séquence d'événements pour comprendre ce qui s'est passé.
**Suivre quand un changement incorrect a eu lieu :**
```bash theme={null}
GET /audit-logs?resourceType=SAVINGS&sortBy=createdAt&sortOrder=asc
```
Triez chronologiquement pour voir la chronologie des changements.
***
### Formation et Contrôle Qualité
**Examiner les actions des nouveaux utilisateurs :**
```bash theme={null}
GET /audit-logs?search=Mark%20Johnson
```
Voir comment les nouveaux membres du personnel utilisent le système.
**Identifier les erreurs fréquentes :**
```bash theme={null}
GET /audit-logs?search=failed
```
Les opérations échouées révèlent des besoins de formation ou des flux de travail confus.
***
## Exemples de Scénarios
### Scénario 1 : Investigation d'une Erreur de Prêt
**Problème** : Un membre affirme que le montant du prêt a été enregistré incorrectement
**Investigation :**
```bash theme={null}
# Find all loan actions for this member
GET /audit-logs?resourceType=LOAN&search=Jane%20Smith
```
**La réponse montre :**
```json theme={null}
{
"actorName": "John Doe",
"actionType": "CREATE",
"resourceType": "LOAN",
"description": "Created loan for Jane Smith - 500,000 RWF",
"metadata": {
"status": "success",
"amount": 500000,
"term": 12
},
"createdAt": "2026-06-10T14:32:15.000Z"
}
```
**Conclusion** : Le prêt a été créé correctement par John Doe le 10 juin. Le montant correspond aux dossiers.
***
### Scénario 2 : Revue Mensuelle de Sécurité
**Objectif** : Vérifier les activités administrateur inhabituelles en juin
**Appel API :**
```bash theme={null}
GET /audit-logs?actorType=organization_admin&startDate=2026-06-01&endDate=2026-06-30&actionType=DELETE
```
**Examiner les suppressions :**
* Les suppressions sont-elles autorisées ?
* Le nombre de suppressions est-il normal ?
* Y a-t-il des tendances suspectes ?
***
### Scénario 3 : Export de Piste d'Audit
**Objectif** : Fournir des preuves d'audit pour un audit externe
**Appels API :**
```bash theme={null}
# Get all financial operations for year
GET /audit-logs?resourceType=LOAN&startDate=2025-01-01&endDate=2025-12-31&limit=100
GET /audit-logs?resourceType=SAVINGS&startDate=2025-01-01&endDate=2025-12-31&limit=100
GET /audit-logs?resourceType=EXPENSE&startDate=2025-01-01&endDate=2025-12-31&limit=100
```
**Processus :**
1. Parcourir tous les résultats avec pagination
2. Exporter vers feuille de calcul ou PDF
3. Fournir aux auditeurs comme documentation justificative
***
## Conservation des Journaux d'Audit
**Stockage** : Les journaux d'audit sont stockés définitivement dans la base de données et ne peuvent pas être supprimés par les utilisateurs.
**Pourquoi permanent ?**
* Exigences de conformité (peut nécessiter 7+ ans)
* Preuve juridique
* Investigation de fraude
* Analyse historique
**Accès** : Récupérable via API avec pagination (20 enregistrements par page par défaut)
**Performance** : Les grandes organisations avec des milliers de journaux doivent utiliser des filtres spécifiques plutôt que récupérer tous les journaux.
***
## Bonnes Pratiques
**Gestion efficace de la piste d'audit :**
**Surveillance régulière :**
* ✅ Examiner les journaux d'audit chaque semaine pour détecter les activités inhabituelles
* ✅ Vérifier les opérations échouées (peuvent indiquer des problèmes)
* ✅ Surveiller les actions DELETE (sensibles)
* ✅ Suivre les actions administrateur (autorisations élevées)
**Filtrage :**
* ✅ Utiliser des filtres de date pour cibler des périodes spécifiques
* ✅ Filtrer par resourceType lors d'une investigation sur une zone spécifique
* ✅ Rechercher par nom d'acteur pour suivre les actions d'un utilisateur précis
* ✅ Combiner les filtres pour des résultats précis
**Investigation :**
* ✅ Trier chronologiquement (sortBy=createdAt) pour voir la chronologie
* ✅ Vérifier metadata pour du contexte supplémentaire
* ✅ Recouper avec les enregistrements réels (prêts, dépôts, etc.)
* ✅ Documenter les conclusions
**Conformité :**
* ✅ Exporter les journaux d'audit pour les audits externes
* ✅ Conserver des copies des exports d'audit avec les rapports financiers
* ✅ Examiner les journaux d'audit avant la clôture de période
* ✅ Démontrer les contrôles d'accès aux auditeurs
**Pagination :**
* ✅ Utiliser une taille de page appropriée (20-50 pour l'interface, 100 pour les exports)
* ✅ Vérifier `hasNextPage` avant de demander la suite
* ✅ Ne pas demander tous les journaux en une seule fois (utiliser les filtres)
***
## Limites
**Impossible de supprimer les journaux d'audit** : Les journaux sont permanents et immuables. Cela garantit l'intégrité de la piste d'audit mais signifie :
* Aucun moyen de retirer des journaux incorrects/de test
* Les journaux s'accumulent dans le temps
* Utilisez les filtres pour trouver les journaux pertinents dans de grands volumes
**Opérations en lecture seule non journalisées** : Pour réduire le bruit :
* Consultation de rapports non journalisée
* Navigation dans les pages non journalisée
* Requêtes de recherche non journalisées
**Actions d'administrateur système exclues** : La piste d'audit de l'organisation montre seulement :
* Actions organization\_admin
* Actions organization\_user
* Actions system admin exclues (piste d'audit différente)
**Pagination requise** : Impossible de récupérer tous les journaux en une seule requête pour les grandes organisations :
* Défaut : 20 enregistrements par page
* Utilisez des filtres pour réduire les résultats
* Paginer dans les résultats selon les besoins
***
## Dépannage
**Q : Impossible de voir les journaux d'audit**
R : Nécessite l'autorisation `audit_logs:read` avec portée ANY. Contactez l'administrateur pour accorder l'autorisation.
***
**Q : Trop de journaux à examiner**
R : Utilisez des filtres pour réduire :
```bash theme={null}
# Example: Only loan deletions in June
GET /audit-logs?resourceType=LOAN&actionType=DELETE&startDate=2026-06-01&endDate=2026-06-30
```
***
**Q : Description du journal peu claire**
R : Vérifiez le champ `metadata` pour des détails supplémentaires :
```json theme={null}
{
"description": "Created loan for Jane Smith",
"metadata": {
"amount": 500000,
"term": 12,
"interestRate": 10,
"memberName": "Jane Smith"
}
}
```
Recoupez avec l'enregistrement réel (prêt, dépôt, etc.) en utilisant la date/l'heure.
***
**Q : Impossible de trouver une action spécifique**
R : Vérifiez :
* L'action est-elle CREATE/UPDATE/DELETE/CONFIGURE ? (READ/VIEW non journalisé)
* L'acteur est-il utilisateur/admin d'organisation ? (system\_admin exclu)
* La plage de dates est-elle correcte ?
* Essayez des termes de recherche plus larges
***
**Q : Je veux exporter les journaux d'audit**
R : Parcourez les résultats avec pagination et enregistrez en CSV/Excel :
```typescript theme={null}
let page = 1;
let hasMore = true;
const allLogs = [];
while (hasMore) {
const response = await fetch(`/audit-logs?page=${page}&limit=100`);
const data = await response.json();
allLogs.push(...data.data);
hasMore = data.pagination.hasNextPage;
page++;
}
// Convert allLogs to CSV or Excel
```
***
## Sujets Connexes
Comprendre le contrôle d'accès
Voir les détails des transactions financières
Examiner la piste d'audit avant clôture
Configurer l'organisation