Notifications¶

Ces routes gèrent les définitions globales de notifications électroniques. Les opérations d'administration sont authentifiées et exigent admin_notif. La page décrit également les routes privées de planification et le callback Maileva, qui suit un mécanisme d'authentification distinct.

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

Ces règles s’appliquent aux actions d'administration et de planification : authentification requise, privilège admin_notif et portée globale à l’instance, sans filtre par entité.

La création et la modification génèrent automatiquement le script associé sous Linux. La programmation directe de la crontab et la génération manuelle de scripts sont des opérations privées d'exploitation. Le callback Maileva est exempté de l'authentification REST habituelle et contrôle à la place le paramètre auth_token.

Structure d’une notification¶

Valeur	Type	Description
`notification_sid`	integer	Identifiant technique
`notification_id`	string	Identifiant fonctionnel
`description`	string	Description, de 1 à 254 caractères
`is_enabled`	string	`Y` ou `N`
`event_id`	string	Événement déclencheur, 254 caractères au maximum
`notification_mode`	string	Mode, la création force `EMAIL`
`template_id`	integer	Identifiant du modèle de notification
`diffusion_type`	string	Type de destinataires
`diffusion_properties`	array en entrée, string en stockage	Identifiants de destinataires
`attachfor_type`	string ou null	Type de rattachement
`attachfor_properties`	array en entrée, string en stockage	Identifiants de rattachement
`send_as_recap`	boolean	Mode récapitulatif, applicable à l’événement `baskets`

Lister les notifications¶

Route¶

GET /rest/notifications

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Définitions stockées	`{"notifications":[{"notification_sid":12,"notification_id":"courrier_exemple","description":"Notification d'exemple","is_enabled":"Y","event_id":"users%","notification_mode":"EMAIL","template_id":4}]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Lire une notification¶

Route¶

GET /rest/notifications/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	`notification_sid`

La réponse convertit diffusion_properties en tableau, indexe attachfor_properties par valeur et ajoute les référentiels nécessaires à l’édition dans notification.data. scriptcreated indique uniquement si le script attendu existe, aucun chemin n’est renvoyé.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Notification enrichie pour l’administration	`{"notification":{"notification_sid":12,"notification_id":"courrier_exemple","diffusion_properties":["ADMINISTRATEUR"],"attachfor_properties":{"COU":"COU"},"scriptcreated":true,"data":{"event":[],"template":[],"diffusionType":[],"groups":[],"users":[],"entities":[],"status":[]}}}`
`400`	object	Identifiant non numérique	`{"errors":"Id is not a numeric"}`
`400`	object	Notification absente	`{"errors":"Notification not found"}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Créer une notification¶

Route¶

POST /rest/notifications

Body¶

Valeur	Type	Obligatoire	Description
`notification_id`	string	Oui	Identifiant unique
`description`	string	Oui	De 1 à 254 caractères
`is_enabled`	string	Oui	`Y` ou `N`
`event_id`	string	Oui	Événement déclencheur
`template_id`	integer	Oui	Modèle ciblant les notifications
`diffusion_type`	string	Oui	Type de diffusion
`diffusion_properties`	array	Oui	Destinataires ou groupes ciblés
`attachfor_type`	string	Non	Type de rattachement
`attachfor_properties`	array	Oui	Éléments de rattachement
`send_as_recap`	boolean	Pour `baskets`	Autorise le récapitulatif, forcé à `false` pour les autres événements

{
  "notification_id": "courrier_exemple",
  "description": "Notification d'exemple",
  "is_enabled": "Y",
  "event_id": "users%",
  "template_id": 4,
  "diffusion_type": "group",
  "diffusion_properties": ["ADMINISTRATEUR"],
  "attachfor_type": "entity",
  "attachfor_properties": ["COU"]
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Notification créée	`{"notification_sid":12,"notification_id":"courrier_exemple","notification_mode":"EMAIL","diffusion_properties":"ADMINISTRATEUR","attachfor_properties":"COU"}`
`400`	object	Identifiant déjà utilisé	Message traduit correspondant à la notification déjà existante
`400`	object	Échec de création	`{"errors":"Notification Create Error"}`
`500`	object	Erreurs de validation	`{"errors":["wrong format for template_id"]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Modifier une notification¶

Route¶

PUT /rest/notifications/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	`notification_sid`

Body¶

Le body reprend les propriétés de création. notification_mode doit être fourni et ne doit pas dépasser 30 caractères. La propriété de présentation scriptcreated, si elle est renvoyée par la lecture, est ignorée pendant la mise à jour.

{
  "notification_id": "courrier_exemple",
  "description": "Notification d'exemple modifiée",
  "is_enabled": "N",
  "event_id": "users%",
  "notification_mode": "EMAIL",
  "template_id": 4,
  "diffusion_type": "group",
  "diffusion_properties": ["ADMINISTRATEUR"],
  "attachfor_type": "entity",
  "attachfor_properties": ["COU"]
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Notification modifiée	`{"notification":{"notification_sid":12,"notification_id":"courrier_exemple","is_enabled":"N"}}`
`500`	object	Identifiant ou body invalide	`{"errors":["notification does not exists"]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Supprimer une notification¶

Route¶

DELETE /rest/notifications/{id}

La suppression retire aussi le script et l’entrée de crontab associés lorsqu’ils existent sous Linux.

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	`notification_sid`

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Notification supprimée et liste restante	`{"notifications":[]}`
`500`	object	Identifiant non numérique	`{"errors":"Id is not a numeric"}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Initialiser l'écran de création d'une notification¶

Route privée d'interface

Cette route agrège les référentiels nécessaires au formulaire du frontend. Sa structure peut évoluer avec l'interface.

Route¶

GET /rest/administration/notifications/new

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

L'authentification et le privilège admin_notif sont obligatoires. Aucun paramètre ni body n'est attendu.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Notification vide et référentiels du formulaire	`{"notification":{"diffusion_properties":[],"attachfor_properties":[],"data":{"event":[],"template":[],"diffusionType":[],"groups":[],"users":[],"entities":[],"status":[]}}}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Lire la planification des notifications¶

Route technique d'exploitation

Cette route retourne les commandes de la crontab et les chemins absolus des scripts autorisés. Ne pas exposer sa réponse à un utilisateur non-administrateur.

Route¶

GET /rest/notifications/schedule

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

L'authentification et le privilège admin_notif sont obligatoires. La réponse concerne la crontab de l'hôte applicatif.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Crontab courante et scripts de notifications autorisés	Voir l'exemple ci-dessous
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

{
  "crontab": [
    {
      "m": "0",
      "h": "8",
      "dom": "*",
      "mon": "*",
      "dow": "*",
      "cmd": "<chemin-du-script-de-notification>",
      "state": "normal"
    }
  ],
  "authorizedNotification": [
    {
      "description": "Notification d'exemple",
      "path": "<chemin-du-script-de-notification>"
    }
  ]
}

Enregistrer la planification des notifications¶

Route technique modifiant la crontab

Envoyer la représentation complète retournée par la lecture. Une commande inventée ou un chemin externe au répertoire des scripts de notifications est refusé.

Route¶

POST /rest/notifications/schedule

Body¶

Le body est un tableau d'entrées de crontab.

Valeur	Type	Obligatoire	Description
`m`	string ou integer	Oui	Minute
`h`	string ou integer	Oui	Heure
`dom`	string ou integer	Oui	Jour du mois
`mon`	string ou integer	Oui	Mois
`dow`	string ou integer	Oui	Jour de la semaine
`cmd`	string	Oui	Chemin d'un script sous le répertoire interne des notifications
`state`	string	Oui	État utilisé par le gestionnaire, notamment `new`, `normal`, `deleted` ou `hidden`
`description`	string	Non	Description libre, ignorée par la validation du format cron

[
  {
    "m": "0",
    "h": "8",
    "dom": "*",
    "mon": "*",
    "dow": "*",
    "cmd": "<chemin-du-script-de-notification>",
    "state": "normal"
  }
]

Retour¶

Code HTTP	Type	Description	Exemple
`200`	boolean	Crontab enregistrée	`true`
`500`	object	Commande ou transition d'état refusée	`{"errors":"Problem with crontab"}`
`500`	object	Champ vide ou expression cron invalide	`{"errors":["wrong format for dom"]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Générer manuellement le script d'une notification¶

Route technique d'exploitation

La création et la modification d'une notification génèrent déjà ce script. Cette route est principalement utilisée comme commande de réparation par l'interface.

Route¶

POST /rest/scriptNotification

Body¶

Valeur	Type	Obligatoire	Description
`notification_sid`	integer	Oui	Identifiant technique de la notification
`notification_id`	string	Oui	Identifiant fonctionnel non vide
`event_id`	string	Oui	Événement non vide

{
  "notification_sid": 12,
  "notification_id": "courrier_exemple",
  "event_id": "users"
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	boolean	Script généré	`true`
`500`	object	Identifiant non numérique ou propriété vide	`{"errors":["notification_sid is not a numeric","one of arguments is empty"]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Recevoir un callback de suivi Maileva¶

Callback privé Maileva

Cette route appartient fonctionnellement aux envois Maileva. Elle est regroupée ici uniquement parce qu'elle reçoit leurs notifications. Elle n'est pas destinée à être appelée par un intégrateur ni par le frontend.

Route¶

POST /rest/administration/shippings/{id}/notifications?auth_token=<token>

Authentification et périmètre¶

Cette route figure parmi les routes sans authentification REST. Elle exige toutefois le JWT auth_token généré par Maarch Courrier lors de l'abonnement Maileva. Le jeton est signé en HS256, lié au domaine Maileva et à l'identifiant du modèle d'envoi, et doit être postérieur à la date minimale enregistrée pour ce modèle.

Paramètres¶

Emplacement	Valeur	Type	Obligatoire	Description
URL	`id`	integer	Oui	Identifiant du modèle d'envoi Maileva
Query string	`auth_token`	string	Oui	JWT de callback généré par Maarch Courrier

Body¶

Valeur	Type	Obligatoire	Description
`source`	string	Oui	Domaine Maileva correspondant à la configuration enregistrée
`user_id`	string	Oui	Identifiant fourni par Maileva, de 1 à 256 caractères
`client_id`	string	Oui	Identifiant client identique à celui de la configuration Maileva
`event_type`	string	Oui	`ON_STATUS_ACCEPTED`, `ON_STATUS_REJECTED`, `ON_STATUS_PROCESSED`, `ON_DEPOSIT_PROOF_RECEIVED` ou `ON_STATUS_ARCHIVED`
`resource_type`	string	Oui	Type de ressource autorisé pour l'événement reçu
`event_date`	string	Oui	Date et heure valides
`event_location`	string	Non	Lorsqu'elle est fournie, la valeur doit être `FR`
`resource_id`	string	Oui	Identifiant d'envoi, de 1 à 256 caractères
`resource_location`	string	Oui	URL Maileva de la ressource

{
  "source": "<domaine-maileva>",
  "user_id": "<identifiant-maileva>",
  "client_id": "<identifiant-client>",
  "event_type": "ON_STATUS_PROCESSED",
  "resource_type": "mail/v2/sendings",
  "event_date": "2026-01-15T10:30:00+01:00",
  "event_location": "FR",
  "resource_id": "<identifiant-envoi>",
  "resource_location": "https://<domaine-maileva>/<ressource>"
}

Retour¶

Code HTTP	Type	Description	Exemple
`201`	vide	Notification traitée, historique et statut mis à jour	Aucune réponse
`201`	object	Preuve de dépôt ignorée par ce traitement	`{"errors":"Body event_type is ignored"}`
`400`	object	Configuration, modèle, body ou envoi invalide	Message exact du contrôle en échec
`403`	object	Jeton absent, invalide ou ne correspondant pas au modèle	`{"errors":"Authentication failed"}`
`500`	object	Action, utilisateur REST ou pièce jointe technique indisponible	Message exact du traitement en échec