Historiques¶

Ces routes consultent et exportent l'historique général de Maarch Courrier ainsi que l'historique des traitements par lots. L'authentification REST est obligatoire pour toutes les routes de cette page. Une authentification absente ou invalide renvoie 401 avec {"errors":"Authentication Failed"}.

Historique général¶

Lister l'historique¶

Route¶

GET /rest/history

Authentification, privilège et périmètre¶

Le privilège et le périmètre dépendent des paramètres de la requête :

Mode	Contrôle d'accès	Périmètre
Sans `resId`	Privilège `view_history`	Historique général de l'instance
Avec `resId`	Courrier dans le périmètre de l'utilisateur et privilège `view_full_history`	Événements du courrier dans `res_letterbox` ou `res_view_letterbox`
Avec `resId` et `onlyActions`	Courrier dans le périmètre de l'utilisateur et privilège `view_doc_history` ou `view_full_history`	Actions réalisées sur le courrier

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`limit`	integer	Non	Nombre maximal de résultats, `25` par défaut
`offset`	integer	Non	Décalage du premier résultat, `0` par défaut
`users[]`	array	Non	Identifiants techniques numériques ou identifiants de connexion des utilisateurs
`startDate`	string	Non	Conserve les événements strictement postérieurs à cette date
`endDate`	string	Non	Conserve les événements strictement antérieurs à cette date
`resId`	integer	Non	Identifiant du courrier dont l'historique est demandé
`onlyActions`	boolean	Non	Avec une valeur non vide, conserve les événements dont le type commence par `ACTION#`
`actions[]`	array	Non	Identifiants d'actions, convertis en types d'événement `ACTION#{id}`
`systemActions[]`	array	Non	Types d'événements système
`search`	string	Non	Recherche insensible à la casse dans `info` et `remote_ip`
`order`	string	Non	Direction attendue : `asc` ou `desc`
`orderBy`	string	Non	Champ de tri envoyé par le frontend

Tri dans l'implémentation actuelle

Le contrôleur ne lit pas orderBy. Lorsque order est renseigné, le tri appliqué est actuellement event_date DESC.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Propriété `history` paginée et nombre total dans `count`	`{"history":[{"record_id":42,"event_date":"2026-09-01 09:30:00","user_id":12,"info":"Modification du courrier","remote_ip":"192.0.2.10","userLabel":"Jean Dupont"}],"count":1}`
`403`	object	Courrier absent du périmètre ou `resId` invalide	`{"errors":"Document out of perimeter"}`
`403`	object	Privilège requis absent	`{"errors":"Service forbidden"}`

Données d'un événement¶

Valeur	Type	Description
`record_id`	integer ou string	Identifiant de l'objet concerné par l'événement
`event_date`	string	Date et heure de l'événement
`user_id`	integer ou null	Identifiant technique de l'utilisateur à l'origine de l'événement
`info`	string	Description de l'événement
`remote_ip`	string ou null	Adresse IP enregistrée
`userLabel`	string	Nom et prénom de l'utilisateur, chaîne vide si l'utilisateur n'existe plus

Lister les filtres disponibles¶

Route¶

GET /rest/history/availableFilters

Authentification, privilège et périmètre¶

Les contrôles sont identiques à ceux de GET /rest/history : view_history sans resId, ou contrôle du périmètre du courrier avec view_full_history. Avec resId et onlyActions, view_doc_history suffit également.

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`resId`	integer	Non	Limite les filtres aux événements du courrier
`onlyActions`	boolean	Non	Avec une valeur non vide, limite les filtres aux types `ACTION#`

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Actions, événements système et utilisateurs présents dans l'historique ciblé	`{"actions":[{"id":"19","label":"Clôturer"}],"systemActions":[{"id":"LOGIN","label":null}],"users":[{"id":12,"login":"jdupont","label":"Jean Dupont"}]}`
`403`	object	Courrier absent du périmètre ou `resId` invalide	`{"errors":"Document out of perimeter"}`
`403`	object	Privilège requis absent	`{"errors":"Service forbidden"}`

Données des filtres¶

Valeur	Type	Description
`actions[].id`	string	Identifiant de l'action extrait du type `ACTION#{id}`
`actions[].label`	string ou null	Libellé de l'action, `null` lorsqu'elle n'existe plus
`systemActions[].id`	string	Type de l'événement système
`systemActions[].label`	null	Le libellé est traduit par le frontend
`users[].id`	integer ou null	Identifiant technique de l'utilisateur
`users[].login`	string ou null	Identifiant de connexion
`users[].label`	string ou null	Nom et prénom, `null` lorsque l'utilisateur n'existe plus

Lire l'historique d'un utilisateur¶

Route¶

GET /rest/history/users/{userSerialId}

Authentification, privilège et périmètre¶

Un utilisateur peut consulter son propre historique sans privilège fonctionnel supplémentaire. La consultation de l'historique d'un autre utilisateur exige view_history.

Paramètres d'URL¶

Valeur	Type	Obligatoire	Description
`userSerialId`	integer	Oui	Identifiant technique de l'utilisateur

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`startDate`	string	Non	Conserve les événements strictement postérieurs à cette date
`adminMode`	boolean	Non	Avec une valeur non vide, ajoute `remote_ip` et supprime la limite de `500` résultats

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Historique de l'utilisateur dans `histories`	`{"histories":[{"info":"Connexion à Maarch Courrier","record_id":"jdupont","event_date":"2026-09-01 08:45:00","remote_ip":"192.0.2.10"}]}`
`403`	object	Consultation d'un autre utilisateur sans `view_history`	`{"errors":"Service forbidden"}`

La propriété remote_ip n'est présente que lorsque adminMode est renseigné.

Exporter l'historique général¶

Route¶

PUT /rest/history/export

Authentification, privilège et périmètre¶

L'implémentation actuelle exige le privilège admin_contacts. Elle n'applique ni view_history, ni le périmètre d'un courrier. L'export porte sur l'historique général de l'instance.

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`limit`	integer	Non	Nombre maximal de lignes exportées, `1000` par défaut

Body¶

Valeur	Type	Obligatoire	Description
`delimiter`	string	Oui	Séparateur CSV : `;`, `,` ou `TAB`
`format`	string	Oui	Format demandé, toute chaîne non vide est acceptée, mais le contrôleur produit toujours un CSV
`data`	array	Oui	Colonnes à exporter, sous la forme `{value, label}`
`parameters`	object	Oui	Filtres de l'export
`parameters.startDate`	string	Non	Conserve les événements strictement postérieurs à cette date
`parameters.endDate`	string	Non	Conserve les événements strictement antérieurs à cette date
`parameters.filterUsed.users`	array	Non	Utilisateurs sous la forme `{login}`
`parameters.filterUsed.actions`	array	Non	Actions sous la forme `{id}`
`parameters.filterUsed.systemActions`	array	Non	Événements système sous la forme `{id}`

Les valeurs de colonne utilisées par l'interface sont event_date, record_id, userLabel, info et remote_ip. label devient l'en-tête de la colonne CSV.

{
  "delimiter": ";",
  "format": "csv",
  "data": [
    {"value": "event_date", "label": "Événement"},
    {"value": "userLabel", "label": "Utilisateur"},
    {"value": "info", "label": "Information"}
  ],
  "parameters": {
    "startDate": "2026-09-01 00:00:00",
    "endDate": "2026-09-02 00:00:00",
    "filterUsed": {
      "actions": [{"id": "19"}],
      "systemActions": [],
      "users": []
    }
  }
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	fichier	Contenu CSV, avec `Content-Type: application/vnd.ms-excel` et le nom `export_maarch.csv`	Fichier CSV
`400`	object	Séparateur absent ou invalide	`{"errors":"Delimiter is empty or not a string between [',', ';', 'TAB']"}`
`400`	object	Format absent ou invalide	`{"errors":"Format data is empty or not an array"}`
`400`	object	Liste des colonnes absente ou vide	`{"errors":"Data data is empty or not an array"}`
`400`	object	Paramètres absents ou vides	`{"errors":"Parameters data is empty or not an array"}`
`403`	object	Privilège `admin_contacts` absent	`{"errors":"Service forbidden"}`

Historique des traitements des scripts¶

Lister l'historique des traitements¶

Route¶

GET /rest/batchHistory

Authentification, privilège et périmètre¶

Le privilège view_history_batch est obligatoire. La route consulte l'historique global des traitements des scripts, sans filtre par entité.

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`limit`	integer	Non	Nombre maximal de résultats, `25` par défaut
`offset`	integer	Non	Décalage du premier résultat, `0` par défaut
`startDate`	string	Non	Conserve les traitements strictement postérieurs à cette date
`endDate`	string	Non	Conserve les traitements strictement antérieurs à cette date
`modules[]`	array	Non	Noms des modules à conserver
`totalErrors`	string ou boolean	Non	Avec une valeur non vide, conserve uniquement les traitements dont `total_errors` est supérieur à `0`
`search`	string	Non	Recherche insensible à la casse dans `info` et `module_name`
`order`	string	Non	Direction du tri : `asc` ou `desc`
`orderBy`	string	Non	Champ de tri : `event_date`, `module_name`, `total_processed`, `total_errors` ou `info`

Un champ orderBy invalide applique le tri event_date DESC.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Propriété `history` paginée et nombre total dans `count`	`{"history":[{"event_date":"2026-09-01 02:00:00","module_name":"notifications","total_processed":120,"total_errors":2,"info":"Traitement terminé"}],"count":1}`
`403`	object	Privilège `view_history_batch` absent	`{"errors":"Service forbidden"}`

Données d'un traitement¶

Valeur	Type	Description
`event_date`	string	Date et heure d'exécution
`module_name`	string	Nom du module ou du traitement
`total_processed`	integer ou null	Nombre d'éléments traités
`total_errors`	integer ou null	Nombre d'erreurs
`info`	string	Informations enregistrées par le traitement

Lister les modules disponibles¶

Route¶

GET /rest/batchHistory/availableFilters

Authentification, privilège et périmètre¶

Le privilège view_history_batch est obligatoire. Aucun paramètre ni body n'est attendu.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Modules distincts présents dans l'historique des traitements	`{"modules":[{"id":"notifications","label":"notifications"}]}`
`403`	object	Privilège `view_history_batch` absent	`{"errors":"Service forbidden"}`

Chaque élément de modules contient le nom du module dans id et label.

Exporter l'historique des traitements¶

Route¶

PUT /rest/batchHistory/export

Authentification, privilège et périmètre¶

L'implémentation actuelle exige le privilège admin_contacts. Elle n'applique pas view_history_batch. L'export porte sur l'ensemble de l'historique des traitements des scripts.

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`limit`	integer	Non	Nombre maximal de lignes exportées, `1000` par défaut

Body¶

Valeur	Type	Obligatoire	Description
`delimiter`	string	Oui	Séparateur CSV : `;`, `,` ou `TAB`
`format`	string	Oui	Format demandé, toute chaîne non vide est acceptée, mais le contrôleur produit toujours un CSV
`data`	array	Oui	Colonnes à exporter, sous la forme `{value, label}`
`parameters`	object	Oui	Filtres de l'export
`parameters.startDate`	string	Non	Conserve les traitements strictement postérieurs à cette date
`parameters.endDate`	string	Non	Conserve les traitements strictement antérieurs à cette date
`parameters.filterUsed.modules`	array	Non	Modules sous la forme `{id}`
`parameters.filterUsed.totalProcessed`	array	Non	Nombres d'éléments traités sous la forme `{id}`
`parameters.filterUsed.totalErrors`	array	Non	Nombres d'erreurs sous la forme `{id}`

Les valeurs de colonne utilisées par l'interface sont event_date, total_processed, total_errors, info et module_name. label devient l'en-tête de la colonne CSV.

{
  "delimiter": ";",
  "format": "csv",
  "data": [
    {"value": "event_date", "label": "Événement"},
    {"value": "module_name", "label": "Module"},
    {"value": "total_errors", "label": "Nombre d'erreurs"}
  ],
  "parameters": {
    "startDate": "2026-09-01 00:00:00",
    "endDate": "2026-09-02 00:00:00",
    "filterUsed": {
      "modules": [{"id": "notifications"}],
      "totalProcessed": [],
      "totalErrors": []
    }
  }
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	fichier	Contenu CSV, avec `Content-Type: application/vnd.ms-excel` et le nom `export_maarch.csv`	Fichier CSV
`400`	object	Séparateur absent ou invalide	`{"errors":"Delimiter is empty or not a string between [',', ';', 'TAB']"}`
`400`	object	Format absent ou invalide	`{"errors":"Format data is empty or not an array"}`
`400`	object	Liste des colonnes absente ou vide	`{"errors":"Data data is empty or not an array"}`
`400`	object	Paramètres absents ou vides	`{"errors":"Parameters data is empty or not an array"}`
`403`	object	Privilège `admin_contacts` absent	`{"errors":"Service forbidden"}`