Dossiers

Cette page décrit les contrats intégrateur relatifs aux dossiers. Toutes les routes exigent une authentification. L'accès et l'édition sont limités aux dossiers appartenant au compte courant ou partagés avec son périmètre d'entités.

Lister les dossiers

GET /rest/folders

Authentification : obligatoire. Aucun privilège supplémentaire n'est nécessaire, la réponse est limitée au périmètre du compte courant.

Code HTTP	Type	Description
200	object	Objet contenant folders

{
  "folders": [
    {
      "name": "<libellé-dossier>",
      "id": 12,
      "label": "<libellé-dossier>",
      "public": false,
      "user_id": 7,
      "parent_id": null,
      "level": 0,
      "countResources": 0,
      "pinned": false,
      "canEdit": true
    }
  ]
}

Consulter un dossier

GET /rest/folders/{id}

Authentification : obligatoire. Le dossier doit être dans le périmètre du compte courant.

Paramètre URL	Type	Obligatoire	Description
id	integer	Oui	Identifiant du dossier

Code HTTP	Type	Description ou message confirmé
200	object	Objet folder, avec le propriétaire, le partage et l'état épinglé
400	object	Route id is not an integer
400	object	Folder not found or out of your perimeter

{
  "folder": {
    "id": 12,
    "label": "<libellé-dossier>",
    "public": true,
    "user_id": 7,
    "parent_id": null,
    "level": 0,
    "ownerDisplayName": "<nom-utilisateur>",
    "sharing": {"entities": []},
    "pinned": false
  }
}

Créer un dossier

POST /rest/folders

Authentification : obligatoire. Avec un parent, celui-ci doit être modifiable dans le périmètre courant, le nouveau dossier hérite de son propriétaire, de sa visibilité et de son partage.

Champ JSON	Type	Obligatoire	Description
label	string	Oui	Libellé non vide
parent_id	integer	Non	Identifiant du dossier parent

{"label": "<libellé-dossier>", "parent_id": 12}

Code HTTP	Type	Description ou message confirmé
200	object	folder contient l'identifiant créé
400	object	Body label is empty or not a string
400	object	Body parent_id is not an integer
400	object	Parent Folder not found or out of your perimeter

Modifier un dossier

PUT /rest/folders/{id}

Authentification : obligatoire. Le dossier et, lors d'un déplacement, le parent doivent être modifiables dans le périmètre courant.

Élément	Type	Obligatoire	Description
URL id	integer	Oui	Identifiant du dossier
Body label	string	Oui	Nouveau libellé
Body parent_id	integer ou null	Non	Nouveau parent, null place le dossier à la racine

{"label": "<nouveau-libellé>", "parent_id": null}

Code HTTP	Type	Description ou message confirmé
200	vide	Dossier modifié
400	object	Query id is empty or not an integer
400	object	Body label is empty or not a string
400	object	Body parent_id is not an integer
400	object	Parent_id and id can not be the same
400	object	parent_id does not exist or Id is a parent of parent_id
400	object	Folder not found or out of your perimeter
400	object	Parent Folder not found or out of your perimeter
400	object	Cannot move folder because at least one folder is out of your perimeter
400	object	Cannot share/unshare folder because at least one folder is out of your perimeter

Supprimer un dossier

DELETE /rest/folders/{id}

Authentification : obligatoire. Le dossier doit être modifiable et ses descendants doivent rester dans le périmètre courant. Aucun paramètre user_id n'est attendu.

Paramètre URL	Type	Obligatoire	Description
id	integer	Oui	Identifiant du dossier

Code HTTP	Type	Description ou message confirmé
204	vide	Dossier supprimé
400	object	Query id is empty or not an integer
400	object	Folder not found or out of your perimeter
400	object	Cannot delete because at least one folder is out of your perimeter

Partager un dossier avec des entités

PUT /rest/folders/{id}/sharing

Authentification : obligatoire. Le dossier doit être modifiable dans le périmètre courant.

Élément	Type	Obligatoire	Description
URL id	integer	Oui	Identifiant du dossier
Body public	boolean	Oui	Active ou désactive le partage
Body sharing.entities	array	Oui	Entités ou mots-clés de partage
sharing.entities[].entity_id	integer	Selon le partage	Identifiant d'entité
sharing.entities[].keyword	string	Selon le partage	Mot-clé de périmètre
sharing.entities[].edition	boolean	Oui	Autorise l'édition

{"public": true, "sharing": {"entities": [{"entity_id": 4, "edition": false}]}}

Code HTTP	Type	Description ou message confirmé
204	vide	Partage mis à jour
400	object	Query id is empty or not an integer
400	object	Body public is empty or not a boolean
400	object	Body sharing/entities does not exists
400	object	Folder not found or out of your perimeter

Lister les filtres d'un dossier

GET /rest/folders/{id}/filters

Authentification : obligatoire. Le dossier doit être visible dans le périmètre courant.

Paramètre URL	Type	Obligatoire	Description
id	integer	Oui	Identifiant du dossier

Les paramètres de query string sont transmis au formateur commun des filtres de listes. Leur contrat exhaustif n'est couvert par aucun test de contrat dédié.

Code HTTP	Type	Description ou message confirmé
200	object	Facettes entities, priorities, categories, statuses, entitiesChildren, doctypes et folders
400	object	Route id is not an integer
400	object	Folder out of perimeter

{"entities": [], "priorities": [], "categories": [], "statuses": [], "entitiesChildren": [], "doctypes": [], "folders": []}

Lister les courriers d'un dossier

GET /rest/folders/{id}/resources

Authentification : obligatoire. Le dossier doit être visible. Chaque courrier expose aussi allowed selon le périmètre courrier du compte courant.

Élément	Type	Obligatoire	Description
URL id	integer	Oui	Identifiant du dossier
Query offset	integer	Non	Décalage, 0 par défaut
Query limit	integer	Non	Taille de page, 10 par défaut

Code HTTP	Type	Description ou message confirmé
200	object	resources, countResources, allResources et templateColumns
400	object	Route id is not an integer
400	object	Folder out of perimeter

{"resources": [{"resId": 42, "subject": "<objet-courrier>", "allowed": true}], "countResources": 1, "allResources": [42], "templateColumns": []}

La structure détaillée de chaque courrier dépend de la configuration admin_folders. Un test de contrat manque pour figer la liste exhaustive des champs.

Ajouter des courriers à un dossier

POST /rest/folders/{id}/resources

Authentification : obligatoire. Le dossier et tous les courriers doivent être dans le périmètre courant.

Élément	Type	Obligatoire	Description
URL id	integer	Oui	Identifiant du dossier
Body resources	array d'integers	Oui	Identifiants des courriers à classer

{"resources": [42]}

Code HTTP	Type	Description ou message confirmé
200	object	Nombre total dans countResources
400	object	Route id is not an integer
400	object	Body resources is empty or not an array
400	object	Folder out of perimeter
400	object	Resources out of perimeter

Retirer des courriers d'un dossier

DELETE /rest/folders/{id}/resources

Authentification : obligatoire. Le dossier et tous les courriers doivent être dans le périmètre courant. Le body JSON est nécessaire malgré la méthode DELETE.

Élément	Type	Obligatoire	Description
URL id	integer	Oui	Identifiant du dossier
Body resources	array d'integers	Oui	Identifiants des courriers à retirer

{"resources": [42]}

Code HTTP	Type	Description ou message confirmé
200	object	Nombre restant dans countResources
400	object	Route id is not an integer
400	object	Body resources is empty or not an array
400	object	Folder out of perimeter
400	object	Resources out of perimeter

Services publics de configuration et de préférences

Ces routes font partie de l'API publique. Elles nécessitent une authentification et restent limitées au périmètre du compte courant.

Méthode et route	Authentification et périmètre	Consommateur connu	Motif
GET /rest/folders/configuration	Utilisateur authentifié, autorisation de route	Administration des dossiers de courrier suivi	Configuration de présentation admin_folders
GET /rest/pinnedFolders	Utilisateur authentifié	Menu des dossiers et tableau de bord	Préférence personnelle
POST /rest/folders/{id}/pin	Utilisateur authentifié, dossier visible	Service frontend des dossiers	Préférence personnelle
DELETE /rest/folders/{id}/unpin	Utilisateur authentifié, dossier visible	Service frontend des dossiers	Préférence personnelle
GET /rest/autocomplete/folders	Utilisateur authentifié	Formulaire d'indexation	Autocomplétion propre à l'interface

Ces routes sont aussi recensées dans l'inventaire du domaine.

Charger la configuration des dossiers

GET /rest/folders/configuration

Le retour 200 contient configuration, valeur JSON enregistrée sous l'identifiant de configuration admin_folders.

Lister les dossiers épinglés

GET /rest/pinnedFolders

Le retour 200 contient folders, limité au compte courant. Chaque entrée expose name, id, label, public, user_id, parent_id, level et countResources.

Épingler un dossier

POST /rest/folders/{id}/pin

Le paramètre URL id est un integer. Le dossier doit être visible par le compte courant.

Code HTTP	Description ou message confirmé
204	Préférence créée
400	Route id not found or is not an integer
400	Folder not found or out of your perimeter
400	Folder is already pinned

Désépingler un dossier

DELETE /rest/folders/{id}/unpin

Le paramètre et le périmètre sont identiques à l'épinglage.

Code HTTP	Description ou message confirmé
204	Préférence supprimée
400	Route id not found or is not an integer
400	Folder not found or out of your perimeter
400	Folder is not pinned

Rechercher des dossiers pour l'autocomplétion

GET /rest/autocomplete/folders?search=<texte>

Le paramètre query string search est une chaîne obligatoire. La recherche est limitée aux dossiers visibles par le compte courant.

Le retour 200 est un tableau d'objets contenant id, idToDisplay, isPublic et otherInfo. Une recherche vide retourne 400 avec Query params search is empty.