Export et fiches de liaison¶

Ces routes permettent d'exporter les données de courriers en CSV ou PDF, de relire les préférences d'export de l'utilisateur et de générer des fiches de liaison au format PDF.

Exporter les données de courriers¶

Cette action génère un tableau CSV ou PDF à partir des courriers et des colonnes demandés. Elle enregistre également la sélection comme préférence d'export de l'utilisateur pour le format choisi.

PUT /rest/resourcesList/exports

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

L'authentification REST est obligatoire. Aucun privilège fonctionnel particulier n'est contrôlé par l'api. Pour un compte en mode REST dont les routes sont restreintes, PUT/resourcesList/exports doit appartenir à authorized_api.

Chaque courrier doit être accessible par au moins l'un des périmètres suivants :

périmètre normal de consultation du courrier ;
bannette accessible à l'utilisateur ;
dossier accessible à l'utilisateur, à l'une de ses entités ou à toutes les entités.

L'accès par le périmètre normal ou par une bannette donne accès à toutes les colonnes demandées. Pour un courrier accessible uniquement par un dossier, seules les valeurs getStatus, alt_identifier, subject et getFolder sont exportées ; les autres colonnes contiennent Hors périmètre. Si aucun de ces périmètres ne donne accès au courrier, la requête est refusée.

Body JSON¶

Valeur	Type	Obligatoire	Description
`format`	string	Oui	Format de sortie : `csv` ou `pdf`.
`delimiter`	string	Pour `csv`	Séparateur CSV : `,`, `;` ou `TAB`.
`data`	array d'object	Oui	Colonnes à exporter. Le tableau doit contenir au moins un élément.
`resources`	array d'integer	Oui	Identifiants des courriers, dans l'ordre attendu dans l'export. Le tableau doit contenir au moins un élément.

Chaque élément de data possède la structure suivante.

Valeur	Type	Obligatoire	Description
`value`	string	Oui	Colonne autorisée, fonction d'export ou identifiant `custom_{id}`. Une chaîne vide produit une colonne vide.
`label`	string	Oui	En-tête non vide de la colonne dans le fichier.
`isFunction`	boolean	Oui	`true` pour une fonction ou un champ personnalisé ; `false` pour une colonne autorisée.

Lorsque isFunction vaut false, les colonnes autorisées sont les suivantes.

Valeur	Description
`res_id`	Identifiant du courrier.
`type_label`	Libellé du type de courrier.
`doctypes_first_level_label`	Libellé du premier niveau de classement.
`doctypes_second_level_label`	Libellé du deuxième niveau de classement.
`format`	Format du document principal.
`barcode`	Code-barres du courrier.
`confidentiality`	Valeur de confidentialité enregistrée.
`alt_identifier`	Numéro chrono.
`subject`	Objet du courrier.
`doc_date`	Date du document.
`departure_date`	Date de départ.
`admission_date`	Date d'arrivée.
`process_limit_date`	Date limite de traitement.
`opinion_limit_date`	Date limite d'avis.
`closing_date`	Date de clôture.
`abstract`	Résumé du document principal.
`tone`	Libellé de la tonalité, lorsque la tonalité est configurée.

Lorsque isFunction vaut true, les valeurs prises en charge sont les suivantes.

Valeur	Description
`getStatus`	Libellé du statut.
`getPriority`	Libellé de la priorité.
`getCopies`	Utilisateurs et entités en copie dans la liste de diffusion.
`getDetailLink`	Lien vers la fiche détaillée du courrier.
`getCategory`	Libellé de la catégorie.
`getInitiatorEntity`	Libellé court de l'entité initiatrice.
`getDestinationEntity`	Libellé court de l'entité traitante.
`getDestinationEntityType`	Type de l'entité traitante.
`getSenders`	Expéditeurs du courrier.
`getRecipients`	Destinataires du courrier.
`getTypist`	Libellé du rédacteur.
`getAssignee`	Libellé de l'attributaire de la liste de diffusion.
`getFolder`	Dossiers du courrier.
`getParentFolder`	Dossiers parents des dossiers du courrier.
`getTags`	Mots-clés du courrier.
`getSignatories`	Signataires.
`getSignatureDates`	Dates de signature.
`getDepartment`	Départements des expéditeurs.
`getAcknowledgementSendDate`	Dates d'envoi des accusés de réception.
`getRetentionFrozen`	`Y` si la durée d'utilité courante est gelée, sinon `N`.
`getBinding`	`Y` pour un courrier engageant, `N` pour un courrier non engageant, sinon une valeur vide.
`getVisaCircuit`	Circuit de visa.
`getOpinionCircuit`	Circuit d'avis.
`custom_{id}`	Valeur du champ personnalisé dont l'identifiant est `{id}`.

{
  "format": "csv",
  "delimiter": ",",
  "resources": [101, 123, 231],
  "data": [
    {
      "isFunction": true,
      "label": "Statut",
      "value": "getStatus"
    },
    {
      "isFunction": true,
      "label": "Priorité",
      "value": "getPriority"
    },
    {
      "isFunction": false,
      "label": "Sujet",
      "value": "subject"
    }
  ]
}

Retours et erreurs¶

Code HTTP	Type	Description	Exemple
`200`	binaire	CSV avec `Content-Type: application/vnd.ms-excel` et `Content-Disposition: attachment; filename=export_maarch.csv`.	Non applicable.
`200`	binaire	PDF retourné en ligne avec le nom `maarch.pdf`.	Non applicable.
`400`	object	`format` est absent ou différent de `pdf` et `csv`.	`{"errors":"Data format is empty or not a string between ['pdf', 'csv']"}`
`400`	object	Le séparateur CSV est absent ou invalide.	`{"errors":"Delimiter is empty or not a string between [',', ';', 'TAB']"}`
`400`	object	`data` est absent ou vide.	`{"errors":"Data data is empty or not an array"}`
`400`	object	Un élément de `data` ne possède pas les propriétés attendues.	`{"errors":"One data is not set well"}`
`400`	object	Une colonne avec `isFunction: false` n'appartient pas à la liste autorisée.	`{"errors":"Export field is not allowed"}`
`403`	object	`resources` est absent ou vide.	`{"errors":"Data resources is empty or not an array"}`
`403`	object	Au moins un courrier n'est accessible par aucun périmètre accepté.	`{"errors":"Document out of perimeter"}`
`403`	object	La route n'est pas autorisée pour le compte REST.	`{"errors":"This route is not authorized for this user"}`

Consulter ses préférences d'export¶

Cette action retourne les dernières colonnes enregistrées par l'utilisateur pour les formats PDF et CSV.

GET /rest/resourcesList/exportTemplate

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

L'authentification REST est obligatoire. Aucun privilège fonctionnel ni périmètre documentaire supplémentaire n'est contrôlé. Pour un compte en mode REST dont les routes sont restreintes, GET/resourcesList/exportTemplate doit appartenir à authorized_api.

Retour¶

Code HTTP	Type	Description	Exemple
`200`	object	Objet `templates` contenant les préférences `pdf` et `csv`.	Voir l'exemple.
`403`	object	La route n'est pas autorisée pour le compte REST.	`{"errors":"This route is not authorized for this user"}`

{
  "templates": {
    "pdf": {
      "data": []
    },
    "csv": {
      "delimiter": ";",
      "data": [
        {
          "value": "subject",
          "label": "Sujet",
          "isFunction": false
        }
      ]
    }
  }
}

En l'absence de préférence CSV, l'objet csv contient uniquement data avec un tableau vide.

Générer les fiches de liaison des courriers¶

Cette action génère un seul PDF contenant une fiche de liaison par courrier, dans l'ordre des identifiants transmis et regroupées par modèle d'indexation.

POST /rest/resourcesList/summarySheets

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

L'authentification REST est obligatoire. Aucun privilège fonctionnel général n'est contrôlé, mais tous les courriers transmis doivent appartenir au périmètre normal de l'utilisateur. Pour un compte en mode REST dont les routes sont restreintes, POST/resourcesList/summarySheets doit appartenir à authorized_api.

Certaines parties du PDF appliquent en plus leurs propres privilèges :

systemTechnicalFields et customTechnicalFields exigent view_technical_infos ;
workflowHistory exige view_doc_history ou view_full_history ;
les notes sont filtrées selon leur auteur et leurs entités de diffusion.

Paramètre de query string¶

Valeur	Type	Obligatoire	Description
`mode`	string	Non	Avec la valeur `base64`, retourne un objet JSON au lieu du PDF binaire. Les autres valeurs conservent le retour binaire.

Body JSON¶

Valeur	Type	Obligatoire	Description
`resources`	array d'integer	Oui	Identifiants des courriers. Le tableau ne doit pas être vide. Tous les identifiants sont contrôlés avant que la génération soit limitée aux 500 premiers.
`units`	array d'object	Non	Parties à intégrer dans la fiche. Un tableau vide génère uniquement l'en-tête de chaque fiche.
`units[].unit`	string	Oui	Identifiant de la partie.
`units[].label`	string	Selon la partie	Libellé du chapitre. Il est ignoré pour `qrcode` et `aiAbstractInformations`.

Les identifiants de partie reconnus par le générateur sont les suivants.

Valeur	Description
`qrcode`	QR code du courrier, selon le paramètre `QrCodePrefix`.
`primaryInformations`	Dates, type de courrier, rédacteur, entité initiatrice et tonalité disponibles dans le modèle.
`secondaryInformations`	Catégorie, statut, priorité, échéances, gel de la durée d'utilité courante, caractère engageant et champs personnalisés.
`aiAbstractInformations`	Résumé du document principal lorsque le champ `abstract` est disponible et renseigné.
`systemTechnicalFields`	Métadonnées techniques, sous réserve du privilège `view_technical_infos`.
`customTechnicalFields`	Champs personnalisés techniques, sous réserve du privilège `view_technical_infos`.
`senderRecipientInformations`	Expéditeurs et destinataires disponibles dans le modèle.
`diffusionList`	Attributaire, utilisateurs et entités en copie.
`visaWorkflow`	Circuit de visa interne.
`opinionWorkflow`	Circuit d'avis.
`notes`	Notes visibles par l'utilisateur.
`freeField`	Zone vide destinée à un commentaire manuscrit. Cette partie peut apparaître plusieurs fois.
`trafficRecords`	Texte du paramètre `traffic_record_summary_sheet`, lorsqu'il est renseigné.
`visaWorkflowMaarchParapheur`	Circuit récupéré auprès de Maarch Parapheur lorsque le connecteur et les identifiants externes sont disponibles.
`workflowHistory`	Historique des actions, sous réserve de `view_doc_history` ou `view_full_history`.

{
  "units": [
    {
      "unit": "qrcode",
      "label": ""
    },
    {
      "unit": "primaryInformations",
      "label": "Informations principales"
    },
    {
      "unit": "senderRecipientInformations",
      "label": "Informations de destination"
    },
    {
      "unit": "secondaryInformations",
      "label": "Informations secondaires"
    },
    {
      "unit": "diffusionList",
      "label": "Liste de diffusion"
    },
    {
      "unit": "notes",
      "label": "Annotations"
    },
    {
      "unit": "freeField",
      "label": "Commentaires"
    }
  ],
  "resources": [2350, 2351]
}

Retours et erreurs¶

Sans mode=base64, la réponse est le PDF binaire :

Code HTTP	Type	Description	Exemple
`200`	binaire	PDF retourné en ligne avec le nom `maarch.pdf`.	Non applicable.
`403`	object	`resources` est absent ou vide.	`{"errors":"Parameter array 'resources' cannot be empty"}`
`403`	object	Un courrier est hors périmètre.	`{"errors":"Document out of perimeter"}`
`403`	object	La route n'est pas autorisée pour le compte REST.	`{"errors":"This route is not authorized for this user"}`
`500`	object	Une exception interne s'est produite. L'api reprend le message de l'exception, aucun message unique n'est défini.

Avec mode=base64, une réponse réussie possède la structure suivante :

{
  "encodedDocument": "JVBERi0xLjcK...",
  "mimeType": "application/pdf"
}

Le comportement de mode=base64 et les contrôles d'autorisation de chacune des parties optionnelles ne disposent pas actuellement d'un test de contrat dédié.