Docservers¶

Les docservers sont les zones de stockage utilisées par Maarch Courrier. Toutes les routes de cette page exigent le privilège admin_docservers et portent sur l’instance complète.

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

Ces règles s’appliquent à toutes les actions de la page : authentification requise, privilège admin_docservers et portée globale à l’instance, sans filtre par entité.

Structure d’un docserver¶

Valeur	Type	Description
`id`	integer	Identifiant technique
`docserver_id`	string	Identifiant fonctionnel du docserver
`docserver_type_id`	string	Type de docserver
`device_label`	string	Libellé
`path_template`	string	Chemin absolu de stockage
`coll_id`	string	Collection associée
`size_limit_number`	integer	Limite en octets
`actual_size_number`	integer	Taille calculée en octets
`is_readonly`	boolean ou string	Indique si la zone est en lecture seule, la liste la convertit en booléen
`is_encrypted`	boolean	Indique si le stockage est chiffré
`actualSizeFormatted`	string	Taille formatée, ajoutée par la liste
`limitSizeFormatted`	number	Limite formatée en Go, ajoutée par la liste
`percentage`	number	Pourcentage d’occupation, ajouté par la liste

Lister les docservers¶

Route¶

GET /rest/docservers

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`getEncryptionStatus`	string	Non	Avec la valeur exacte `true`, ajoute l’état global du chiffrement

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Docservers regroupés par type et liste des types	Voir l’exemple ci-dessous
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

{
  "docservers": {
    "DOC": [
      {
        "id": 1,
        "docserver_id": "DOCSERVER_EXEMPLE",
        "docserver_type_id": "DOC",
        "device_label": "Stockage principal",
        "path_template": "<chemin-du-docserver>",
        "coll_id": "letterbox_coll",
        "size_limit_number": 50000000000,
        "actual_size_number": 1000000,
        "is_readonly": false,
        "is_encrypted": false,
        "actualSizeFormatted": "1 Mo",
        "limitSizeFormatted": 50,
        "percentage": 0
      }
    ]
  },
  "types": [
    {"docserver_type_id": "DOC", "docserver_type_label": "Documents"}
  ],
  "docserverEncryptionStatus": false
}

Lire un docserver¶

Route¶

GET /rest/docservers/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Ligne du docserver telle que stockée	`{"id":1,"docserver_id":"DOCSERVER_EXEMPLE","path_template":"<chemin-du-docserver>"}`
`400`	object	Docserver absent	`{"errors":"Docserver not found"}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Créer un docserver¶

Route¶

POST /rest/docservers

Body¶

Valeur	Type	Obligatoire	Description
`docserver_id`	string	Oui	32 caractères au maximum. lettres, `_` et `-`
`docserver_type_id`	string	Oui	Type existant
`device_label`	string	Oui	Libellé
`size_limit_number`	integer	Oui	Limite en octets
`path_template`	string	Oui	Répertoire existant, lisible et accessible en écriture
`coll_id`	string	Oui	Collection
`is_encrypted`	boolean	Oui	Activation du chiffrement pour cette zone

{
  "docserver_id": "DOCSERVER_EXEMPLE",
  "docserver_type_id": "DOC",
  "device_label": "Stockage principal",
  "size_limit_number": 50000000000,
  "path_template": "<chemin-du-docserver>",
  "coll_id": "letterbox_coll",
  "is_encrypted": false
}

Le premier docserver d’un couple type/collection devient actif, les suivants sont créés en lecture seule. Les types FULLTEXT et MIGRATION ne peuvent pas être chiffrés.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Docserver créé	`{"docserver":12}`
`400`	object	Corps invalide	`{"errors":"Bad Request"}`
`400`	object	Type absent	`{"errors":"Docserver type does not exist"}`
`400`	object	Chiffrement interdit pour ce type	`{"errors":"Docserver type is forbidden for encryption"}`
`400`	object	Chemin inaccessible	Message traduit correspondant au chemin de docserver inaccessible
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Modifier un docserver¶

Route¶

PUT /rest/docservers/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique

Body¶

Valeur	Type	Obligatoire	Description
`device_label`	string	Oui	Libellé
`size_limit_number`	integer	Oui	Limite en octets
`path_template`	string	Oui	Répertoire existant, lisible et accessible en écriture
`is_readonly`	boolean	Oui	État de lecture seule
`is_encrypted`	boolean	Non	État du chiffrement, `false` si omis ou désactivé globalement

{
  "device_label": "Stockage secondaire",
  "size_limit_number": 50000000000,
  "path_template": "<chemin-du-docserver>",
  "is_readonly": true,
  "is_encrypted": false
}

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Docserver modifié et formaté	`{"docserver":{"id":12,"device_label":"Stockage secondaire","is_readonly":true}}`
`400`	object	Corps invalide	`{"errors":"Bad Request"}`
`400`	object	Docserver absent	`{"errors":"Docserver not found"}`
`400`	object	Chemin inaccessible ou autre docserver déjà actif	Message traduit correspondant au contrôle
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Supprimer un docserver¶

Route¶

DELETE /rest/docservers/{id}

Paramètres d’URL¶

Valeur	Type	Obligatoire	Description
`id`	integer	Oui	Identifiant technique

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Docserver supprimé	`{"success":"success"}`
`400`	object	Docserver absent	`{"errors":"Docserver does not exist"}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Recalculer les tailles¶

Route¶

POST /rest/docservers/calculateSize

Cette opération ne prend aucun body utile. Elle parcourt les zones accessibles et met à jour leur taille. Deux calculs sont espacés d’au moins deux heures.

Retour¶

Code HTTP	Type	Description	Exemple
`204`	vide	Calcul terminé	Aucune réponse
`200`	object	Calcul déjà actif	`{"error":"Process already running"}`
`200`	object	Dernier calcul trop récent	`{"error":"Last calculation is too early"}`
`400`	object	Échec du calcul d’une zone	`{"error":"Size calculation error for docserver DOCSERVER_EXEMPLE"}`
`403`	object	Privilège absent	`{"error":"Service forbidden"}`

Lister les types de docservers¶

Route¶

GET /rest/docserverTypes

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Types triés par libellé	`{"docserverTypes":[{"docserver_type_id":"DOC","docserver_type_label":"Documents","enabled":"Y"}]}`
`403`	object	Privilège absent	`{"errors":"Service forbidden"}`

Données¶

Valeur	Type	Description
`docserver_type_id`	string	Identifiant du type
`docserver_type_label`	string	Libellé
`enabled`	string	État stocké dans le référentiel

Vérifier un chemin pendant l'installation¶

Route¶

GET /rest/installer/docservers

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

Pendant l'installation, le middleware peut autoriser cette route sans authentification. Lorsqu'un utilisateur est authentifié, l'api exige le privilège create_custom. Le contrôle porte directement sur le système de fichiers du serveur.

Paramètres de query string¶

Valeur	Type	Obligatoire	Description
`path`	string	Oui	Chemin à vérifier, les caractères `"`, `'`, `<`, `>`, `\\|`, `*`, `:`, `?` sont refusés

L'api remonte jusqu'au premier répertoire existant et vérifie qu'il est accessible en lecture et en écriture.

Retour¶

Code HTTP	Type	Description	Exemple
`204`	vide	Chemin ou parent existant accessible	Aucune réponse
`400`	object	Paramètre absent ou chemin invalide	`{"errors":"Query params path is empty or not a string"}`
`400`	object	Répertoire inaccessible	`{"errors":"Query params path is not readable or writable"}`
`403`	object	Installation terminée ou privilège absent	`{"errors":"Route forbidden"}`

Créer l'arborescence des docservers pendant l'installation¶

Route d'installation avec effets sur le système de fichiers

Cette opération crée les répertoires de stockage et modifie tous les path_template du custom en cours d'installation. Elle ne doit pas être appelée sur une instance en exploitation.

Route¶

POST /rest/installer/docservers

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

Les règles d'accès sont identiques à celles de la vérification du chemin : accès possible sans authentification pendant l'installation, sinon privilège create_custom. Le customId doit désigner un custom possédant encore son verrou initializing.lck.

Body¶

Valeur	Type	Obligatoire	Description
`path`	string	Oui	Répertoire racine des docservers, créé si nécessaire
`customId`	string	Oui	Identifiant du custom en cours d'installation

{
  "path": "<chemin-du-docserver>",
  "customId": "<identifiant-du-custom>"
}

La route crée les sous-répertoires nécessaires aux courriers, pièces jointes, conversions, miniatures, plein texte, modèles, transferts d'archives, accusés de réception et migrations. Elle copie aussi les modèles d'installation puis remplace les chemins initiaux dans la table des docservers.

Retour¶

Code HTTP	Type	Description	Exemple
`204`	vide	Arborescence créée et chemins mis à jour	Aucune réponse
`200`	object	Docservers créés mais échec du dossier des modèles	`{"success":"Docservers created but templates folder creation failed"}`
`400`	object	Body, custom ou chemin invalide	Message exact du contrôle en échec
`400`	object	Création ou accès à un répertoire impossible	Message contenant le répertoire concerné
`403`	object	Custom déjà installé ou privilège absent	`{"errors":"Custom is already installed"}` ou `{"errors":"Route forbidden"}`