Courriers¶

Création d'un courrier¶

Route¶

POST /rest/resources

Paramètres¶

Body¶

Valeur	Type	Obligatoire	Description
modelId	integer	Oui	Identifiant du modèle d'indexation (Voir l'administration des modèles)
doctype	integer	Non	Identifiant du type du courrier (Voir l'administration des typologies)
subject	string	Non	Sujet du courrier
chrono	boolean	Non	Si true, un numéro chrono sera généré (false par défaut)
typist	integer	Non	Identifiant du rédacteur (Voir l'administration des utilisateurs)
status	string	Oui	Statut du courrier
destination	integer	Non	Identifiant de l'entité traitante du courrier (Voir l'administration des entités)
diffusionList	array	Non	Liste de diffusion du courrier : [{id: 19, mode: "dest", type: "user"}, {id: 7, mode: "cc", type: "entity"},…]
initiator	integer	Non	Identifiant de l'entité initiatrice du courrier (Voir l'administration des entités)
confidentiality	boolean	Non	Si true, le courrier sera confidentiel (false par défaut)
documentDate	date	Non	Date du courrier
arrivalDate	date	Non	Date d'arrivée du courrier
departureDate	date	Non	Date de départ du courrier
processLimitDate	date	Non	Date limite de traitement du courrier
priority	string	Non	Identifiant de la priorité (Voir l'administration des priorités)
barcode	string	Non	Code barre du courrier
encodedFile	base64	Non	Fichier encodé en base64
format	string	Non	Format du fichier transmis (Obligatoire si un fichier est transmis)
externalId	array	Non	Identifiants externes
customFields	array	Non	Champs personnalisés
senders	array	Non	Expéditeur(s) (peut être un contact, un utilisateur ou une entité)
recipients	array	Non	Destinataires(s) (peut être un contact, un utilisateur ou une entité)
folders	array	Non	Identifiants des dossiers dans lesquels le courrier sera visible
tags	array	Non	Identifiants des mot-clés qui seront attachés au courrier

Exemple¶

Enregistrement d'un courrier ayant pour sujet "Un courrier à enregistrer" :

{
    "modelId" : 1,
    "doctype" : 102,
    "subject" : "Un courrier à enregistrer",
    "chrono" : true,
    "typist" : 19,
    "status" : "COU",
    "destination" : 21,
    "initiator" : 13,
    "priority" : "poiuytre1357nbvc",
    "documentDate" : "2020-01-01 17:18:47",
    "format" : "PDF",
    "encodedFile": "JVBERi0xLjQgLi4u",
    "externalId" : {"companyId" : "123456789"},
    "customFields" : {"2" : "ma valeur custom"},
    "senders" : [{"id" : 10, "type" : "contact"}],
    "recipients" : [{"id" : 32, "type" : "user"}, {"id" : 17, "type" : "entity"}],
    "folders" : [47, 56],
    "tags" : [2, 98, 20]
}

Dans le cas où vous utilisez MaarchCapture, un exemple de paramétrage exploitant ce WS est disponible ici : https://docs.maarch.org/gitbook/html/MaarchCapture.

Retour¶

Code Http	Type	Description	Exemple
200	array	Le courrier a bien été créé	['resId' => 123]
`400`	array	Un paramètre obligatoire est manquant	['errors' => 'Data is not set or empty']
`500`	array	Une erreur s'est produite	['errors' => '[ResController create] ...']

Récupération des courriers¶

Route¶

POST /rest/res/list

Paramètres¶

Body¶

Valeur	Type	Obligatoire	Description
select	string	Oui	Partie select de la clause SQL. N'importes quelles colonnes de la vue res_view_letterbox peuvent être renseignées
clause	string	Oui	Partie where de la clause SQL. N'importes quelles colonnes de la vue res_view_letterbox peuvent être renseignées
withFile	boolean	Non	Indique si l’on souhaite récupérer les fichiers encodés en base64. Si true, la valeur fileBase64Content sera ajoutée dans le retour
orderBy	array	Non	Partie « order by » de la clause SQL
limit	integer	Non	Nombre maximum de résultats que l’on souhaite obtenir

Exemple¶

Récupération de l'identifiant GED, type de courrier et service traitant des courriers au statut 'COU', trié par ordre de l'identifiant GED décroissant.
Les fichiers seront retournés. 100 résultats au maximum seront retournés :

{
    "select" : "res_id, type_label, entity_label",
    "clause" : "status='COU'",
    "withFile" : true,
    "orderBy" : ["res_id desc"],
    "limit" : 100
}

Retour¶

Code Http	Type	Description	Exemple
`200`	array	Le courrier a bien été créé	* Voir l'exemple de retour ci-dessous
`400`	array	Un paramètre obligatoire est manquant ou dans le mauvais format	['errors' => 'Bad Request: select is not valid']

Exemple de retour :

{
  "resources": [
    {
      "res_id": 234,
      "type_label": "Abonnements – documentation – archives",
      "entity_label": "CAB:Cabinet du Maire",
      "fileBase64Content": "JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXYOwyER"
    },
    {
      "res_id": 233,
      "type_label": "Abonnements – documentation – archives",
      "entity_label": "DGSDSGCOU:Service Courrier",
      "fileBase64Content": "JVBERi0xLjUNJeLjz9MNCjYgMCBvYmoNPDwvTGVPRg0K"
    }
  ],
  "count": 2
}

Récupération du contenu de la ressource au format PDF¶

Route¶

GET /rest/resources/{resId}/content

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
resId	int	Oui	Identifiant de la ressource
mode	string	Non	Format du fichier retourné. Valeurs possibles : base64, view 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 retournées dans une chaîne	Flux pdf
`403`	array	Document hors du périmètre de l'utilisateur	['errors' => 'Document out of perimeter']
`400`	array	La ressource n'existe pas	['errors' => 'Document 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']
`400`	array	La ressource recherchée n'a pas de document	['errors' => 'Document has no file']
`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']
`404`	array	Zone de stockage des ressources non trouvée	['errors' => 'Docserver does not exist']
`404`	array	Document non trouvé dans la zone de stockage	['errors' => 'Document not found in docserver']
`500`	array	Erreur de récupération du document dans la zone de stockage	['errors' => 'Failed to get document on docserver']
`500`	array	Erreur lors de la récupération de la version convertie (PDF) de la ressource	['errors' => 'Conversion error : xxx ']

Données¶

Si mode est view :

Valeur	Type	Description
Flux pdf	flux	Flux pdf (fichier ouvert dans le navigateur si possible)

Si mode est vide :

Valeur	Type	Description
Flux pdf	flux	Flux pdf (le fichier est téléchargé)

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 ressource
mimeType	string	Mime type du fichier retourne
originalCreatorId	int	Identifiant du créateur
signatoryId	int	Identifiant du signataire (si ressource signée)

Récupération du contenu original de la ressource¶

Route¶

GET /rest/resources/{resId}/originalContent

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
resId	int	Oui	Identifiant de la ressource
mode	string	Non	Mode de retour de la ressource : base64 ou vide
signedVersion	boolean	Non	Choix si on veut la version signée ou non

Retour¶

Code Http	Type	Description	Exemple
`200`	flux	Données du fichier retourné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	Paramètre signedVersion invalide	['errors' => 'signedVersion param is not a boolean']
`400`	array	Le paramètre doit être supérieur à 0	['errors' => 'Parameter resId must be greater than 0']
`400`	array	La ressource n'existe pas	['errors' => 'Document 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']
`400`	array	La ressource recherchée n'a pas de document	['errors' => 'Document has no file']
`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']
`404`	array	Zone de stockage des ressources non trouvée	['errors' => 'Docserver does not exist']
`404`	array	Document non trouvé dans la zone de stockage	['errors' => 'Document not found in docserver']
`500`	array	Erreur de récupération du document dans la zone de stockage	['errors' => 'Failed to get document on docserver']

Données¶

Si mode est différent de base64 ou n'existe pas :

Valeur	Type	Description
Flux	flux	Flux de la ressource demandée (le fichier est 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 ressource
mimeType	string	Mime type du fichier retourne

Récupération du contenu d'une version spécifique d'une ressource¶

Route¶

GET /rest/resources/{resId}/content/{version}

Paramètres¶

URL¶

Valeur	Type	Obligatoire	Description
resId	int	Oui	Identifiant de la ressource
type	string	Non	Type de la pièce voulue. Valeurs possibles : PDF, SIGN ou NOTE. Si vide, PDF est choisi par défaut
version	int	Oui	Numéro de version

Retour¶

Code Http	Type	Description	Exemple
`200`	array	Fichier encodé en base64 et nom du fichier	['encodedDocument' => 'encodedContent', 'filename' => 'filename_V1.pdf']
`400`	array	Le paramètre doit être supérieur à 0	['errors' => 'Parameter version must be greater than 0']
`400`	array	Paramètre vide ou pas d'une bonne valeur	['errors' => 'Parameter type can not be empty and should be PDF, TYPE, NOTE']
`400`	array	La ressource n'existe pas	['errors' => 'Document does not exist']
`400`	array	La ressource n'a pas de document attaché	['errors' => 'Document has no file']
`400`	array	Le numéro de version est incorrect	['errors' => 'Incorrect version']
`400`	array	L'empreinte du document retrouvé ne correspond pas à celle enregistrée	['errors' => 'Fingerprints do not match']
`403`	array	Document hors du périmètre de l'utilisateur	['errors' => 'Document out of perimeter']
`404`	array	La zone de stockage n'existe pas	['errors' => 'Docserver does not exist']
`404`	array	La ressource n'a pas été retrouvée dans la zone de stockage	['errors' => 'Document not found in docserver']
`500`	array	Erreur de récupération du document dans la zone de stockage	['errors' => 'Failed to get document on docserver']

Données¶

Valeur	Type	Description
encodedDocument	string	Contenu fichier encodé en base64
filename	string	Nom de la ressource

Modification du statut des courriers¶

Route¶

PUT /rest/res/resource/status

Paramètres¶

Body¶

Valeur	Type	Obligatoire	Description
status	string	Oui	Identifiant du statut cible. Visible dans la table status.id
historyMessage	string	Non	Message renseigné dans l'historique des messages, justifiant le changement de statut
resId	array	Oui (si chrono vide)	Tableau contenant les identifiants uniques du courrier dans MaarchCourrier (res_letterbox.res_id)
chrono	array	Oui (si resId vide)	Tableau contenant les identifiants uniques du courrier dans MaarchCourrier (res_letterbox.alt_identifier)

Exemple¶

Modification du statut du courrier 1671, avec un message dans l'historique :

{
    "status" : "COU",
    "historyMessage" : "On change tout !",
    "resId" : [1671]
}

Retour¶

Code Http	Type	Description	Exemple
200	array	Le statut a bien été modifié	['success' => 'success']
`400`	array	Un paramètre obligatoire est manquant ou dans le mauvais format	['errors' => 'status not found']
`403`	array	Le document ne fait pas partie du périmètre	['errors' => 'Document out of perimeter']