Aller au contenu

Pièces jointes

Authentification, privilèges et périmètre

Toutes les routes de cette page exigent l'authentification REST et l'autorisation d'accès à la route. La création, le détail, le téléchargement, les imagettes, les bascules d'intégration et le publipostage contrôlent le périmètre du courrier principal. La modification et la suppression exigent en plus les droits calculés par canUpdateAttachment ou canDeleteAttachment. La consultation des types exige seulement l'authentification. La recherche par chrono contrôle le périmètre du courrier principal trouvé. Le téléchargement d'une preuve de signature exige le privilège download_proof_file. Les routes historiques de signature et de désignature des pièces jointes sont documentées dans Parapheur interne.

Création d'une pièce jointe

Route

POST /rest/attachments

Paramètres

Body

Valeur Type Obligatoire Description
title string Non Sujet de la pièce jointe
chrono string Non Numéro chrono, si vide sera généré
resIdMaster int Oui Identifiant du courrier auquel est rattaché la pièce jointe (res_letterbox.res_id)
type string Oui Type de pièce jointe
status string Non Statut de la pièce jointe (A_TRA, TRA ou SEND_MASS)
encodedFile base64 Oui Fichier encodé en base64
format string Oui Format du fichier transmis
originId int Non Identifiant de la pièce jointe originelle (à transmettre lors de la création d'une version ou d'une réponse signée)
recipientId int Non Identifiant du contact de la pièce jointe (users.id ou contacts.id)
recipientType string Non Type du contact ("user" ou "contact")
typist int Non Identifiant du créateur de la pièce jointe (users.id)
validationDate date Non Date de retour attendue
effectiveDate date Non Date de retour effective
externalId array Non Identifiants externes
Exemple

Enregistrement d'une pièce jointe ayant pour sujet "Une lettre à envoyer" :

{
    "title" : "Une lettre à envoyer",
    "chrono" : "MAARCH/2019D/24",
    "resIdMaster" : 92,
    "type" : "response_project",
    "format" : "PDF",
    "encodedFile": "JVBERi0xLjQgLi4u",
    "externalId" : {"companyId" : "123456789"}
}

Retour

Code Http Type Description Exemple
200 array La pièce jointe a bien été créé ['id' => 123]
400 array Un paramètre obligatoire est manquant ['errors' => 'Bad Request']
500 array Une erreur s'est produite ['errors' => '[AttachmentController create] ...']

Consultation d'une pièce jointe

Route

GET /rest/attachments/{id}

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe

Query string

Valeur Type Obligatoire Description
groupId integer Non Identifiant du groupe, utilisé avec basketId pour calculer les droits canUpdate et canDelete
basketId integer Non Identifiant de la bannette, utilisé avec groupId pour prendre en compte le droit canUpdateDocuments

Retour

Code Http Type Description Exemple
200 object Détail de la pièce jointe et droits calculés pour l'utilisateur connecté {"resId":3825,"status":"A_TRA"}
400 object Pièce jointe absente, supprimée ou obsolète {"errors":"Attachment does not exist"}
400 object Courrier principal hors périmètre {"errors":"Attachment out of perimeter"}

Données

Valeur Type Description
resId integer Identifiant de la pièce jointe
resIdMaster integer Identifiant du courrier principal
status string Statut de la pièce jointe
title string ou null Objet de la pièce jointe
chrono string ou null Numéro chrono
typist integer Identifiant du créateur
typistLabel string Libellé du créateur
modifiedBy string ou null Libellé du dernier utilisateur ayant modifié la pièce jointe
relation integer Numéro de version
type string Identifiant du type de pièce jointe
typeLabel string, facultatif Libellé du type lorsqu'il est encore présent dans le référentiel
recipientId integer ou null Identifiant du destinataire
recipientType string ou null Type du destinataire : user ou contact
originId integer ou null Identifiant de la version d'origine
creationDate timestamp Date de création
modificationDate timestamp ou null Date de modification, null lorsqu'elle est identique à la date de création
validationDate timestamp ou null Date de retour attendue
format string Format du fichier
fulltextResult string ou null Résultat de l'indexation plein texte
inSignatureBook boolean Indique l'intégration au parapheur
inSendAttach boolean Indique l'intégration aux envois
external_state object ou null État externe décodé
versions array Anciennes versions, avec leur resId et leur relation
signedResponse integer, facultatif Identifiant de la réponse signée associée lorsque le statut vaut SIGN
signatory string, facultatif Libellé du signataire
signatoryId integer ou null Identifiant du signataire
signDate timestamp, facultatif Date de signature
canUpdate boolean Droit de modification calculé pour l'utilisateur
canDelete boolean Droit de suppression calculé pour l'utilisateur
template object ou null Modèle associé
signaturePositions array Positions de signature résolues
isAnnotated boolean Indique si la version contient des annotations
lastUnannotatedVersionResId integer, facultatif Dernière version non annotée lorsque isAnnotated vaut true
lastUnannotatedVersionFormat string, facultatif Format de la dernière version non annotée

Récupération des pièces jointes associées à un courrier (triées par date de modification décroissante)

Route

GET /rest/resources/{resId}/attachments

Paramètres

URL

Valeur Type Obligatoire Description
resId int Oui Identifiant du courrier
limit int Non Nombre de pièces jointes retournées au maximum

Retour

Code Http Type Description Exemple
200 array Informations liées aux pièces jointes du courrier ['attachments' => '[...]']
403 array Document hors du périmètre de l'utilisateur ['errors' => 'Document out of perimeter']
403 array Le paramètre 'limit' n'est pas un entier ['errors' => 'Query limit is not an integer']

Données

Valeur Type Description
attachments array Liste des pièces jointes du courrier
Données attachments
Valeur Type Description
resId int Identifiant de la pièce jointe
chrono string Numéro chrono de la pièce jointe
title string Objet de la pièce jointe
format string Extension de la pièce jointe
creationDate timestamp without time zone Date de création de la pièce jointe
modificationDate timestamp without time zone Date de dernière modification de la pièce jointe
modifiedBy string Nom de la dernière personne ayant modifié la pièce jointe
relation int Numéro de version de la pièce jointe
status string Statut de la pièce jointe
type string Identifiant du type de la pièce jointe
typeLabel string Libellé du type de la pièce jointe
typistLabel string Prénom Nom du créateur de la pièce jointe
typist integer Identifiant du créateur de la pièce jointe
inSignatureBook boolean Indique si la pièce jointe est intégrée au parapheur
inSendAttach boolean Indique si la pièce jointe est intégrée aux envois Maileva
Exemple
{
  "attachments": [
    {
      "resId": 3825,
      "chrono": "MAARCH/2020D/112",
      "title": "Un courrier à enregistrer",
      "typist": 19,
      "modifiedBy": "",
      "creationDate": "2020-03-20 15:49:51.595809",
      "modificationDate": null,
      "relation": 1,
      "status": "A_TRA",
      "type": "response_project",
      "inSignatureBook": true,
      "inSendAttach": false,
      "typistLabel": "Barbara BAIN",
      "typeLabel": "Projet de réponse",
      "canConvert": true
    }
  ],
  "mailevaEnabled": false
}

Récupération de la pièce jointe au format PDF

Route

GET /rest/attachments/{id}/content

Paramètres

URL

Valeur Type Obligatoire Description
id int Oui Identifiant de la pièce jointe
mode string Non Format du fichier retourné. Valeurs possibles : base64 ou vide
watermark boolean Non Indique si un watermark doit être apposé ou non sur le document PDF récupéré. Si le paramètre n'existe pas, celui-ci est considéré à true par défaut.

Retour

Code Http Type Description Exemple
200 flux Données du fichier rétournées dans une chaîne Flux pdf
403 array Document hors du périmètre de l'utilisateur ['errors' => 'Document out of perimeter']
403 array La pièce jointe n'existe pas ['errors' => 'Attachment not found']
400 array La zone de stockage des pièces jointes n'existe pas ['errors' => 'Docserver does not exist']
400 array L'empreinte numérique du fichier ne correspond pas à celle de la base de données ['errors' => 'Fingerprints do not match']
404 array Le fichier de la pièce jointe est introuvable ['errors' => 'Attachment not found on docserver']
404 array La fichier pdf de la pièce jointe n'a pas pu être renvoyé ['errors' => 'Document not found on docserver']

Données

Si mode est vide :

Valeur Type Description
Flux pdf flux Flux pdf

Si mode est base64 :

Valeur Type Description
encodedDocument string Contenu fichier encodé en base64
originalFormat string Extension du fichier original
filename string Nom de la pièce jointe
mimeType string Mime type du fichier retourne
signatoryId int Identifiant du signataire (si pièce jointe signée)

Récupération du contenu original la pièce jointe

Route

GET /rest/attachments/{id}/originalContent

Paramètres

URL

Valeur Type Obligatoire Description
id int Oui Identifiant de la pièce jointe
mode string Non Format du fichier retourné. Valeurs possibles : base64 ou vide

Retour

Code Http Type Description Exemple
200 flux Données du fichier rétournées dans une chaîne Flux de la pièce jointe
400 array Format de l'id incorrect ['errors' => 'Route id is not an integer']
400 array Pièce jointe non trouvée ['errors' => 'Attachment not found']
400 array La zone de stockage n'existe pas ['errors' => 'Docserver does not exist']
403 array Document hors du périmètre de l'utilisateur ['errors' => 'Document out of perimeter']
404 array Pièce jointe non trouvée dans la zone de stockage ['errors' => 'Attachment not found on docserver']
400 array L'empreinte numérique du fichier ne correspond pas à celle de la base de données ['errors' => 'Fingerprints do not match']
400 array La fichier pdf de la pièce jointe n'a pas pu être renvoyé ['errors' => 'Document not found on docserver']
400 array Erreur à la lecture du fichier ['errors' => 'could not decode encoded data, or open target file']
400 array Erreur lors du calcul de la taille du fichier ou récupération du mime/type ['errors' => 'could not compute mime type or file size']

Données

Si mode est vide :

Valeur Type Description
Flux flux Flux du document qui sera téléchargé

Si mode est base64 :

Valeur Type Description
encodedDocument string Contenu fichier encodé en base64
extension string Extension du fichier original
filename string Nom de la pièce jointe
mimeType string Mime type du fichier retourne

Récupération de l'imagette de la pièce jointe

Route

GET /rest/attachments/{id}/thumbnail

Paramètres

URL

Valeur Type Obligatoire Description
id int Oui Identifiant de la pièce jointe

Retour

Code Http Type Description Exemple
200 flux Données du fichier rétournées dans une chaîne Flux image
403 array Document hors du périmètre de l'utilisateur ['errors' => 'Document out of perimeter']
403 array La pièce jointe n'existe pas ['errors' => 'Attachment not found']
400 array La zone de stockage des imagettes n'existe pas ['errors' => 'Docserver does not exist']
404 array Le fichier imagette de la pièce jointe est introuvable ['errors' => 'Thumbnail not found on docserver']

Données

Valeur Type Description
Flux image flux Flux image

Récupération des types de pièce jointe

Route

GET /rest/attachmentsTypes

Retour

Code Http Type Description Exemple
200 array Informations des types ['attachment_types' => '[...]']
500 array Erreur serveur ['errors' => '...']

Données

Valeur Type Description
attachmentTypes array Liste des types de pièce jointe disponibles pour l'application

[identifiant du type de pièce jointe] →

Valeur Type Description
id integer Identifiant technique du type de pièce jointe
typeId string Identifiant texte du type de pièce jointe
label string Nom du type de pièce jointe
icon string Lettre icone (Utilisé dans le parapheur)
signable boolean Flag si le type de pièce jointe peut être signé dans le parapheur
visible boolean Flag si le type de pièce peut être utilisé graphiquement dans le logiciel
chrono boolean Flag indiquant si un numéro chrono sera généré à la création d'une pièce jointe avec ce type
emailLink boolean Flag indiquant que les pièces jointes de ce type seront ajoutées par défaut à l'envoi d'un mail
versionEnabled boolean Flag indiquant s'il est possible de créér une nouvelle version
newVersionDefault boolean Permet de cocher par défaut une nouvelle version
Exemple
{
  "attachmentsTypes": {
    "response_project": {
      "id": 1,
      "typeId": "response_project",
      "label": "Projet de réponse",
      "visible": true,
      "emailLink": true,
      "signable": true,
      "icon": "R",
      "chrono": true,
      "versionEnabled": true,
      "newVersionDefault": true
    },
    "signed_response": {
      "id": 2,
      "typeId": "signed_response",
      "label": "Réponse signée",
      "visible": false,
      "emailLink": true,
      "signable": false,
      "icon": "",
      "chrono": true,
      "versionEnabled": true,
      "newVersionDefault": true
    }
  }
}

Récupération d'une pièce jointe en fonction du numéro chrono

Route

GET /rest/attachmentsInformations

Paramètres

URL

Valeur Type Obligatoire Description
chrono string Oui Numéro chrono de la pièce jointe

Retour

Code Http Type Description Exemple
200 array Informations liées à la pièce jointe ['resId' => 3825, ...]
400 array Numéro chrono non défini ['errors' => 'Query chrono is not set']
403 array Document hors du périmètre de l'utilisateur ['errors' => 'Document out of perimeter']

Données

Valeur Type Description
resId int Identifiant de la pièce jointe
resIdMaster int Identifiant du courrier principal
title string Objet de la pièce jointe
status string Statut de la pièce jointe
Exemple
{
  "resId": 3825,
  "resIdMaster": 2349,
  "status": "A_TRA",
  "title": "Réponse à votre demande"
}

Modification d'une pièce jointe

La pièce jointe doit avoir le statut A_TRA, TRA ou SEND_MASS. L'utilisateur doit disposer du droit de modification calculé pour la pièce jointe ou du droit canUpdateDocuments dans le parapheur, et le courrier principal doit appartenir à son périmètre.

Les pièces jointes de type acknowledgement_record_management ou reply_record_management ne sont pas modifiables par cette route.

Route

PUT /rest/attachments/{id}

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe

Query string

Valeur Type Obligatoire Description
onlyDocument boolean Non Si la valeur n'est pas vide, remplace uniquement le fichier. encodedFile et format sont requis

Body

En modification complète, type est obligatoire. Les autres métadonnées omises parmi title, recipientId, recipientType, validationDate et effectiveDate sont enregistrées à null.

Valeur Type Obligatoire Description
type string Oui, hors onlyDocument Identifiant d'un type de pièce jointe existant
title string Non Objet non vide de la pièce jointe
encodedFile string base64 Oui avec onlyDocument Nouveau contenu, sa présence remet isAnnotated à false
format string Oui avec encodedFile Format du nouveau contenu
recipientId integer Non Identifiant d'un utilisateur actif ou d'un contact existant
recipientType string Oui avec recipientId user ou contact
validationDate datetime Non Date de retour attendue
effectiveDate datetime Non Date de retour effective
inSignatureBook boolean Non La valeur true ajoute la pièce jointe au parapheur, utiliser la route de bascule pour la retirer
Exemple
{
  "title": "Réponse mise à jour",
  "type": "response_project",
  "validationDate": "2026-09-15 12:00:00"
}

Retour

Code Http Type Description Exemple
204 vide Pièce jointe modifiée
400 object Identifiant, body, type, fichier, destinataire ou date invalide {"errors":"Body type does not exist"}
400 object Pièce jointe absente, statut non modifiable, type d'archivage ou courrier hors périmètre {"errors":"Attachment does not exist"}
403 object Droit de modification insuffisant {"errors":"Insufficient privilege"}
500 object Échec du stockage du nouveau contenu {"errors":"[AttachmentController update] ..."}

Suppression d'une pièce jointe

La suppression retire physiquement la version d'origine et toutes les versions qui lui sont rattachées. Elle retire également ces identifiants des courriels encore au statut brouillon.

Les pièces jointes de type acknowledgement_record_management ou reply_record_management ne peuvent pas être supprimées par cette route.

Route

DELETE /rest/attachments/{id}

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe

Retour

Code Http Type Description Exemple
204 vide Pièce jointe et versions associées supprimées
400 object Identifiant invalide, pièce jointe absente ou type d'archivage protégé {"errors":"Attachment does not exist"}
403 object Droit de suppression insuffisant {"errors":"Insufficient privilege"}
403 object Courrier principal hors périmètre {"errors":"Document out of perimeter"}

Récupération d'une page d'imagette

La route utilise la pièce jointe fille active liée par origin lorsqu'elle existe, avant de générer ou lire l'imagette demandée. Contrairement à la route d'imagette simple, elle renvoie le contenu en base64 dans un objet JSON.

Route

GET /rest/attachments/{id}/thumbnail/{page}

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe
page integer Oui Numéro de la page PDF à récupérer

Retour

Code Http Type Description Exemple
200 object Imagette encodée en base64 et nombre de pages du document PDF {"fileContent":"iVBORw0...","pageCount":3}
400 object Identifiant invalide ou pièce jointe absente {"errors":"Document does not exist"}
400 object Zone de stockage absente, conversion ou lecture PDF impossible {"errors":"Docserver does not exist"}
403 object Courrier principal hors périmètre {"errors":"Document out of perimeter"}
404 object Page ou document PDF absent de la zone de stockage {"errors":"Page not found on docserver"}

Données

Valeur Type Description
fileContent string Contenu de l'imagette encodé en base64
pageCount integer Nombre total de pages du document PDF

Bascule de l'intégration aux envois

La route inverse la valeur inSendAttach. Lorsqu'une pièce jointe possède une chaîne de versions ou une réponse signée, la dernière pièce jointe de cette chaîne est mise à jour. Aucun body n'est attendu.

Route

PUT /rest/attachments/{id}/inSendAttachment

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe

Retour

Code Http Type Description Exemple
200 object Valeur inversée et historiques enregistrés {"success":"success"}
400 object Pièce jointe absente {"errors":"Attachment not found"}
403 object Courrier principal hors périmètre {"errors":"Document out of perimeter"}

Bascule de l'intégration au parapheur

La route inverse la valeur inSignatureBook et enregistre les historiques de la pièce jointe et du courrier principal. Aucun body n'est attendu. Le format du document doit être autorisé et convertible pour le parapheur.

Route

PUT /rest/attachments/{id}/inSignatureBook

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe

Retour

Code Http Type Description Exemple
200 object Valeur inversée et historiques enregistrés {"success":"success"}
400 object Identifiant invalide ou pièce jointe absente {"errors":"Pièce jointe non trouvée : 3825"}
403 object Courrier principal hors périmètre {"errors":"Document attaché en dehors du périmètre"}
404 object Extension non autorisée ou non convertible {"errors":"Cette extension du document n'est pas autorisée..."}

Génération d'un publipostage

La pièce jointe source doit avoir le statut SEND_MASS. La route fusionne le modèle une fois par contact concerné, crée les nouvelles pièces jointes en demandant leur intégration au parapheur, puis marque la pièce jointe source comme supprimée. Lorsqu'aucun contact n'est associé, une seule pièce jointe fusionnée est créée. Aucun body n'est attendu.

Route

POST /rest/attachments/{id}/mailing

Paramètres

URL

Valeur Type Obligatoire Description
id integer Oui Identifiant de la pièce jointe de publipostage

Retour

Code Http Type Description Exemple
204 vide Documents de publipostage générés et source marquée supprimée
400 object Identifiant invalide, stockage ou fichier source indisponible {"errors":"Attachment not found on docserver"}
403 object Pièce jointe absente {"errors":"Attachment does not exist"}
403 object Courrier hors périmètre {"errors":"Document out of perimeter"}
403 object Statut différent de SEND_MASS {"errors":"Attachment is not candidate to mailing"}

Téléchargement de la preuve de signature d'une pièce jointe

Cette route exige le privilège download_proof_file. La pièce jointe doit avoir le statut SIGN, ne plus être liée au parapheur et contenir un dossier de preuves dans son état externe.

L'archive ZIP produite contient une preuve XML et une preuve PDF qui décrivent le document et les étapes du circuit de visa et de signature.

Route

GET /rest/attachments/{resId}/proofSignature

Paramètres

URL

Valeur Type Obligatoire Description
resId integer Oui Identifiant de la pièce jointe signée

Query string

Valeur Type Obligatoire Description
mode string Non Avec la valeur base64, renvoie un objet JSON, sinon renvoie l'archive ZIP

Retour

Code Http Type Description Exemple
200 flux ZIP Archive ZIP envoyée avec le type application/zip
200 object JSON Archive encodée lorsque mode=base64 {"encodedProofDocument":"UEsDB...","format":"zip"}
400 object Pièce jointe absente {"errors":"Document introuvable"}
400 object Pièce jointe non signée {"errors":"Le document n'est pas signé"}
400 object Pièce jointe encore liée au parapheur {"errors":"Resource "Attachment|..." is still linked..."}
400 object Dossier de preuves absent {"errors":"La ressource signée ne comporte pas de dossier..."}
403 object Privilège download_proof_file absent {"errors":"Privilège interdit : download_proof_file"}

Données avec mode=base64

Valeur Type Description
encodedProofDocument string Archive ZIP encodée en base64
format string Toujours zip