Piste d'Audit - Agatabo

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 :

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 :

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

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

GET /audit-logs?actorType=organization_admin

Affiche les actions des administrateurs avec autorisations élevées. Utilisateurs de l’organisation uniquement :

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 :

GET /audit-logs?resourceType=LOAN

Dépôts/retraits d’épargne :

GET /audit-logs?resourceType=SAVINGS

Changements de membres :

GET /audit-logs?resourceType=ORGANIZATION_USER

Filtrer par Type d’Action

Créations uniquement :

GET /audit-logs?actionType=CREATE

Suppressions uniquement (sensible) :

GET /audit-logs?actionType=DELETE

Changements de configuration :

GET /audit-logs?actionType=CONFIGURE

Filtrer par Plage de Dates

7 derniers jours :

GET /audit-logs?startDate=2026-06-05&endDate=2026-06-12

Mois spécifique :

GET /audit-logs?startDate=2026-06-01&endDate=2026-06-30

Rechercher par Mots-clés

Trouver les actions d’un utilisateur spécifique :

GET /audit-logs?search=John%20Doe

Trouver des descriptions de transactions spécifiques :

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 :

GET /audit-logs?actorType=organization_admin&actionType=DELETE&startDate=2026-05-01&endDate=2026-05-31

Opérations de prêt échouées :

GET /audit-logs?resourceType=LOAN&search=failed

Pagination

Défaut : 20 enregistrements par page Naviguer entre les pages :

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

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

GET /audit-logs?sortBy=createdAt&sortOrder=desc

Plus ancien d’abord :

GET /audit-logs?sortBy=createdAt&sortOrder=asc

Trier par nom d’acteur (alphabétique) :

GET /audit-logs?sortBy=actorName&sortOrder=asc

Trier par type d’action :

GET /audit-logs?sortBy=actionType&sortOrder=asc

Trier par type de ressource :

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 :

{
  "metadata": {
    "status": "success"
  }
}

Exemple d’opération échouée :

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

GET /audit-logs?search=failed

Cas d’Utilisation

Conformité et Audit

Revue annuelle d’audit :

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

GET /audit-logs?actionType=DELETE

Surveiller les actions d’administrateurs :

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 :

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 :

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 :

GET /audit-logs?search=Mark%20Johnson

Voir comment les nouveaux membres du personnel utilisent le système. Identifier les erreurs fréquentes :

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 :

# Find all loan actions for this member
GET /audit-logs?resourceType=LOAN&search=Jane%20Smith

La réponse montre :

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

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 :

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

Parcourir tous les résultats avec pagination
Exporter vers feuille de calcul ou PDF
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 :

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

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

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

Autorisations

Comprendre le contrôle d’accès

Écritures Comptables

Voir les détails des transactions financières

Clôture de Période

Examiner la piste d’audit avant clôture

Paramètres de l'Organisation

Configurer l’organisation

​Aperçu

​Point d’Accès API

​Structure de Réponse

​Ce qui est Journalisé

​Filtrer les Journaux d’Audit

​Filtrer par Type d’Acteur

​Filtrer par Type de Ressource

​Filtrer par Type d’Action

​Filtrer par Plage de Dates

​Rechercher par Mots-clés

​Combiner les Filtres

​Pagination

​Tri

​Détection du Statut

​Cas d’Utilisation

​Conformité et Audit

​Surveillance de Sécurité

​Dépannage

​Formation et Contrôle Qualité

​Exemples de Scénarios

​Scénario 1 : Investigation d’une Erreur de Prêt

​Scénario 2 : Revue Mensuelle de Sécurité

​Scénario 3 : Export de Piste d’Audit

​Conservation des Journaux d’Audit

​Bonnes Pratiques

​Limites

​Dépannage

​Sujets Connexes

Autorisations

Écritures Comptables

Clôture de Période

Paramètres de l'Organisation

Aperçu

Point d’Accès API

Structure de Réponse

Ce qui est Journalisé

Filtrer les Journaux d’Audit

Filtrer par Type d’Acteur

Filtrer par Type de Ressource

Filtrer par Type d’Action

Filtrer par Plage de Dates

Rechercher par Mots-clés

Combiner les Filtres

Pagination

Tri

Détection du Statut

Cas d’Utilisation

Conformité et Audit

Surveillance de Sécurité

Dépannage

Formation et Contrôle Qualité

Exemples de Scénarios

Scénario 1 : Investigation d’une Erreur de Prêt

Scénario 2 : Revue Mensuelle de Sécurité

Scénario 3 : Export de Piste d’Audit

Conservation des Journaux d’Audit

Bonnes Pratiques

Limites

Dépannage

Sujets Connexes