Recommandés¶

Ces routes administrent les sites d'affranchissement et les plages de numéros, puis traitent les recommandés, accusés de réception et imports en masse. Toutes nécessitent l'authentification REST.

Lister les sites d'affranchissement¶

GET /rest/registeredMail/sites

La réponse 200 OK contient sites. Un site expose id, label, postOfficeLabel, accountNumber, les propriétés d'adresse et les identifiants entities. Aucun privilège spécifique n'est contrôlé par cette méthode.

Consulter un site¶

GET /rest/registeredMail/sites/{id}

id est l'identifiant entier du site. La réponse contient site avec la même structure que la liste. Un site absent produit 400 Bad Request.

Créer un site¶

POST /rest/registeredMail/sites
Content-Type: application/json

Le privilège admin_registered_mail est obligatoire.

{
  "label": "Site principal",
  "postOfficeLabel": "Bureau postal",
  "accountNumber": 123456,
  "addressNumber": "10",
  "addressStreet": "Rue Exemple",
  "addressPostcode": "75000",
  "addressTown": "Paris",
  "addressCountry": "FRANCE",
  "entities": [3]
}

Propriété	Type	Obligatoire
`label`	string non vide	oui
`accountNumber`	integer de 1 à 10 chiffres, unique	oui
`addressNumber`, `addressStreet`, `addressPostcode`, `addressTown`	strings non vides	oui
`postOfficeLabel`, `addressAdditional1`, `addressAdditional2`, `addressCountry`	string	non
`entities`	array d'integers	non

Le succès retourne 200 OK avec {"id": 12}. Les validations produisent 400 Bad Request et l'absence de privilège 403 Forbidden.

Modifier un site¶

PUT /rest/registeredMail/sites/{id}
Content-Type: application/json

Le privilège admin_registered_mail est obligatoire. Le body reprend celui de la création et remplace les rattachements d'entités. Le succès retourne 204 No Content.

Supprimer un site¶

DELETE /rest/registeredMail/sites/{id}

Le privilège admin_registered_mail est obligatoire. La suppression d'un site inexistant est idempotente et retourne 204 No Content. Un site déjà utilisé par un recommandé produit 400 Bad Request.

Lister les plages de numéros¶

GET /rest/registeredMail/ranges

La réponse 200 OK contient ranges. Chaque plage expose id, registeredMailType, trackerNumber, rangeStart, rangeEnd, creator, creationDate, status, currentNumber et fullness. Aucun privilège spécifique n'est contrôlé par cette méthode.

Consulter une plage¶

GET /rest/registeredMail/ranges/{id}

Le privilège admin_registered_mail est obligatoire. La réponse contient rangeet une plage absente produite 400 Bad Request.

Créer une plage¶

POST /rest/registeredMail/ranges
Content-Type: application/json

{
  "registeredMailType": "2D",
  "trackerNumber": "TRACKER-EXAMPLE",
  "rangeStart": 100000,
  "rangeEnd": 199999,
  "status": "SPD"
}

Propriété	Type	Obligatoire	Contrainte
`registeredMailType`	string non vide	oui	Type de recommandé
`trackerNumber`	string non vide	oui	Unique
`rangeStart`	integer	oui	Strictement inférieur à `rangeEnd`
`rangeEnd`	integer	oui	Ne doit pas chevaucher une plage du même type
`status`	string	non	`SPD` par défaut

Le privilège admin_registered_mail est obligatoire. Le succès retourne 200 OK avec id.

Modifier une plage¶

PUT /rest/registeredMail/ranges/{id}
Content-Type: application/json

Le body reprend celui de la création. L'activation au statut OK termine l'ancienne plage active du même type. Une plage déjà sortie de l'état SPD n'accepte plus que le changement d'état prévu par le contrôleur. Le succès retourne 204 No Content ; un chevauchement, un numéro de suivi déjà utilisé ou une transition interdite retourne 400 Bad Request.

Supprimer une plage¶

DELETE /rest/registeredMail/ranges/{id}

Le privilège admin_registered_mail est obligatoire. La suppression d'une plage inexistante retourne 204 No Content. Une plage active au statut OK ne peut pas être supprimée et produit 400 Bad Request.

Lire le dernier numéro d'un type¶

GET /rest/registeredMail/ranges/type/{type}/last

type est le type de recommandé. Le privilège admin_registered_mail est obligatoire. La réponse 200 OK contient lastNumber, égal à 1 lorsque aucune plage OK ou SPD n'existe.

Lister les pays¶

GET /rest/registeredMail/countries

La réponse 200 OK contient countries, liste issue du référentiel embarqué. Aucun privilège spécifique n'est contrôlé par cette méthode.

Enregistrer un accusé de réception¶

PUT /rest/registeredMails/acknowledgement
Content-Type: application/json

Le privilège registered_mail_receive_ar est obligatoire.

Propriété	Type	Obligatoire	Description
`type`	string	oui	`distributed` ou `notDistributed`
`number`	string	oui	Numéro `2C`, `2D` ou `RW` au format validé
`returnReason`	string	si non distribué	Motif
`receivedDate`	datetime non future	si non distribué	Date de retour

{
  "type": "distributed",
  "number": "2D 000 000 000 00"
}

La réponse 200 OK contient previousStatus et canRescan. Le contrôleur met à jour la date de réception, le statut paramétré du courrier et l'historique. Un recommandé inconnu, hors liste de dépôt, déjà reçu ou un body invalide produit 400 Bad Request.

Annuler la réception d'un accusé¶

PUT /rest/registeredMails/acknowledgement/rollback
Content-Type: application/json

Le privilège registered_mail_receive_ar est obligatoire. Le body contient type, number et éventuellement status, appliqué au courrier. La date et le motif de réception sont remis à null. Le succès retourne 204 No Content.

Importer des courriers enregistrés¶

PUT /rest/registeredMails/import
Content-Type: application/json

Le privilège registered_mail_mass_import est obligatoire.

{
  "registeredMails": [
    {
      "modelId": 4,
      "departureDate": "2026-08-21 00:00:00",
      "registeredMail_type": "2D",
      "registeredMail_warranty": "R1",
      "registeredMail_issuingSite": 12,
      "registeredMail_reference": "Dossier exemple",
      "company": "Société Exemple",
      "firstname": "",
      "lastname": "",
      "addressNumber": "10",
      "addressStreet": "Rue Exemple",
      "addressPostcode": "75000",
      "addressTown": "Paris"
    }
  ]
}

modelId, departureDate, le type parmi 2D, 2C, RW, la garantie parmi R1, R2, R3 et le site sont obligatoires. R3 est interdit avec RW. Le destinataire doit fournir soit company, soit prénom et nom, ainsi que rue, code postal et ville.

La réponse 200 OK fournit success, puis les compteurs et détails de warnings et errors. Une erreur sur un élément n'interrompt pas le traitement des autres.

Modifier les données d'un recommandé¶

PUT /rest/registeredMails/{resId}
Content-Type: application/json

Le courrier doit appartenir au périmètre de l'utilisateur et ne doit pas déjà appartenir à une liste de dépôt.

Propriété	Type	Obligatoire	Description
`type`	string	oui	`2D`, `2C` ou `RW`
`warranty`	string	oui	`R1`, `R2` ou `R3`. `R3` interdit avec `RW`
`recipient`	object	oui	Destinataire et adresse
`reference`	string	utilisée par le contrôleur	Référence complétée par la date de départ
`letter`	boolean	non	Indicateur de lettre

Le contrôleur réserve un numéro si le type change, met à jour le recommandé et régénère son PDF. Le succès retourne 204 No Content. Les erreurs de périmètre, de données, de site ou de plage produisent 400 Bad Request.