Parapheur interne¶

Maarch Courrier possède deux implémentations internes distinctes :

le parapheur historique open source, avec la signature via le carré gris
le parapheur électronique, qui utilise la signature griffe et/ou la signature électronique

Ces deux notions ne désignent pas les parapheurs externes.

Choisir l'implémentation du parapheur¶

Le choix est effectué par config.newInternalParaph dans config/config.json :

{
  "config": {
    "newInternalParaph": true
  }
}

Valeur	Parapheur actif
`true`	Parapheur électronique
`false`	Parapheur historique open source
Paramètre absent	Parapheur historique, comme avec `false`

Parapheur historique open source¶

Le contrôleur historique construit localement le contenu du parapheur et gère les versions signées des courriers et des pièces jointes. Les quatre routes sign et unsign de cette page lui appartiennent fonctionnellement.

Nouveau parapheur électronique¶

Le parapheur électronique prend en charge le workflow, la signature et les preuves. Son activation influe aussi sur les actions de circuit et sur la synchronisation des utilisateurs, groupes et privilèges.

Compatibilité des routes¶

Route	Historique/open source	Nouveau/parapheur électronique	Différence de contrat
`GET /rest/signatureBook/config`	disponible	disponible	L'URL n'est présente que pour le nouveau parapheur actif. Route privée frontend.
`GET /rest/signatureBook/users/{userId}/groups/{groupId}/baskets/{basketId}/resources`	disponible	disponible, route historique encore utilisée	Indépendante du sélecteur dans la déclaration actuelle. Route privée frontend.
`GET /rest/signatureBook/users/{userId}/groups/{groupId}/baskets/{basketId}/resources/{resId}`	disponible	disponible avec un autre cas d'usage	Même chemin, identité utilisateur, droits et retours différents. Route privée frontend.
`GET /rest/signatureBook/{resId}/attachments`	disponible	techniquement disponible, route historique	Aucun garde sur `newInternalParaph`. Route privée frontend.
`GET /rest/signatureBook/{resId}/incomingMailAttachments`	disponible	techniquement disponible, route historique	Aucun garde sur `newInternalParaph`. Route privée frontend.
`GET /rest/signatureBook/version`	indisponible	réservée au parapheur électronique	Erreur `400` lorsque le nouveau parapheur est désactivé. Route privée frontend.
`POST /rest/signatureBook/webhook`	non applicable	callback du parapheur électronique	Authentification par JWT métier, hors authentification REST habituelle.
`PUT /rest/attachments/{id}/sign`	route historique	techniquement appelable, hors workflow nominal	Aucun garde ne la désactive avec `true`.
`PUT /rest/attachments/{id}/unsign`	route historique	techniquement appelable, hors workflow nominal	Aucun garde ne la désactive avec `true`.
`PUT /rest/resources/{resId}/sign`	route historique	techniquement appelable, hors workflow nominal	Aucun garde ne la désactive avec `true`.
`PUT /rest/resources/{resId}/unsign`	route historique	techniquement appelable, hors workflow nominal	Aucun garde ne la désactive avec `true`.

L'appartenance fonctionnelle des quatre routes historiques ne signifie pas qu'elles sont techniquement désactivées avec newInternalParaph: true : aucun garde ni test ne le confirme.

Routes du parapheur historique open source¶

Les routes de cette section appartiennent au parapheur historique. Certaines restent techniquement enregistrées lorsque newInternalParaph vaut true, mais elles ne font pas partie du workflow nominal du parapheur électronique.

Routes privées de l'interface historique¶

Ces routes sont consommées par l'interface Angular et ne constituent pas une API intégrateur stable :

Route	Disponibilité	Contrat historique
`GET /rest/signatureBook/users/{userId}/groups/{groupId}/baskets/{basketId}/resources`	Les deux valeurs de `newInternalParaph`	`limit` vaut `25` et `offset` `0` par défaut.
`GET /rest/signatureBook/users/{userId}/groups/{groupId}/baskets/{basketId}/resources/{resId}`	`newInternalParaph: false` ou absent	`userId`, `basketId` et `resId` construisent le retour, `groupId` ne le construit pas.
`GET /rest/signatureBook/{resId}/attachments`	Les deux valeurs de `newInternalParaph`	Retourne les pièces jointes, après contrôle du périmètre.
`GET /rest/signatureBook/{resId}/incomingMailAttachments`	Les deux valeurs de `newInternalParaph`	Retourne le courrier et ses pièces jointes, après contrôle du périmètre.

Pour la route détaillée d'un courrier, le retour historique contient notamment attachments, documents, resList, signatures, listinstance, canSign et canUpdateDocuments. Un courrier absent ou absent de la bannette produit 400 Bad Request, et un courrier hors périmètre 403 Forbidden.

Signer un courrier avec le parapheur historique¶

PUT /rest/resources/{resId}/sign
Content-Type: application/json

{
  "signatureId": 7
}

Élément	Contrat
`resId`	Identifiant entier du courrier
`signatureId`	Identifiant entier d'une signature appartenant à l'utilisateur authentifié
Privilège	`sign_document`
Formats	PDF, ou document bureautique convertible en PDF
Succès	`204 No Content`

Le contrôleur vérifie le périmètre et l'appartenance du courrier au parapheur, convertit si nécessaire, crée une version signée SIGN, supprime la version de travail TNL, marque l'étape signataire et ajoute l'événement resourceSign.

Les paramètres ou formats invalides produisent 400 Bad Request, l'absence de privilège ou de périmètre 403 Forbidden, et une signature inexistante 404 Not Found.

Retirer la signature d'un courrier avec le parapheur historique¶

PUT /rest/resources/{resId}/unsign

La route est réservée au dernier signataire ou à l'utilisateur ayant le rôle de rédacteur, dans le périmètre du courrier. Elle supprime les versions SIGN et TNL de la version courante, restaure la version documentaire, annule l'état signataire du circuit, vide external_id, retire le proofBundle de external_state et trace resourceUnsign. Le succès retourne 204 No Content.

Signer une pièce jointe avec le parapheur historique¶

PUT /rest/attachments/{id}/sign
Content-Type: application/json

{
  "signatureId": 7
}

Élément	Contrat
`id`	Identifiant entier de la pièce jointe
`signatureId`	Signature appartenant à l'utilisateur
Privilège	`sign_document`
Succès	`200 OK` avec l'identifiant de la version signée

Le courrier principal doit appartenir au parapheur. Le fichier doit être un PDF ou un document bureautique convertible. Le contrôleur crée une version signed_response au statut TRA, place la source au statut SIGN, met à jour l'étape signataire et écrit l'historique.

Les paramètres ou formats invalides produisent 400 Bad Request, l'absence de privilège ou de périmètre 403 Forbidden, et une signature inexistante 404 Not Found.

Retirer la signature d'une pièce jointe avec le parapheur historique¶

PUT /rest/attachments/{id}/unsign

La route vérifie le périmètre, le dernier signataire ou le rôle de rédacteur. Une pièce signée par défaut ne peut pas être désignée. La source revient à A_TRA, les versions signées passent à DEL, l'état signataire est annulé, external_id est vidé et le proofBundle est retiré de external_state. L'opération est historisée sur la pièce et le courrier principal. Le succès retourne 204 No Content.

Routes du nouveau parapheur électronique¶

Les routes de cette section utilisent le contrat du parapheur électronique lorsque newInternalParaph vaut true. Elles ne doivent pas être confondues avec les routes historiques qui restent éventuellement appelables pour des raisons de compatibilité technique.

Routes privées de l'interface du parapheur électronique¶

Ces routes sont consommées par l'interface Angular et ne constituent pas une API intégrateur stable :

Route	Disponibilité	Contrat du parapheur électronique
`GET /rest/signatureBook/config`	Les deux valeurs de `newInternalParaph`	Indique l'implémentation active avec `isNewInternalParaph`. La propriété `url` est présente uniquement lorsque le parapheur électronique est actif.
`GET /rest/signatureBook/users/{userId}/groups/{groupId}/baskets/{basketId}/resources/{resId}`	`newInternalParaph: true`	Utilise le cas d'usage du parapheur électronique malgré un chemin identique à celui du parapheur historique.
`GET /rest/signatureBook/version`	`newInternalParaph: true` uniquement	Retourne `version`, `build` et `time`. La route produit `400 Bad Request` lorsque le parapheur électronique est désactivé.

Pour la route détaillée d'un courrier, l'utilisateur authentifié remplace le paramètre userId et les droits sont calculés avec groupId et basketId. Le retour contient resourcesToSign, resourcesAttached, canSignResources, canAddAttachments, canUpdateResources, hasActiveWorkflow, isCurrentWorkflowUser et currentWorkflowRole. Un courrier absent ou absent de la bannette produit 400 Bad Request, et un courrier hors périmètre 403 Forbidden.

Le détail de l'implémentation de ces routes est privé et n'est pas publié dans la documentation intégrateur.

Recevoir le webhook du parapheur électronique¶

POST /rest/signatureBook/webhook
Content-Type: application/json

Cette route est un callback d'interopérabilité configurable. Elle est exclue de l'authentification REST habituelle, mais le body doit contenir un JWT HS256 vérifié avec la clé de l'instance.

{
  "retrieveDocUri": "https://parapheur.example.invalid/documents/42",
  "token": "<jwt-signé>"
}

Le JWT porte l'identifiant idParapheur. Le callback lit l'état distant, sa date de mise à jour, l'éventuel message, les indicateurs de signature ou de cachet et le proofBundle. Un état validé enregistre la version signée et retourne son identifiant ; un refus ou une erreur met à jour le workflow et retourne un message. Les bodies incomplets, jetons invalides et données incohérentes produisent 400 Bad Request.

Cette route ne doit être exposée qu'au service de parapheur configuré.

Effets conditionnels dans les autres domaines¶

Lorsque newInternalParaph vaut true :

la modification d'un visaCircuit synchronise le workflow avant la validation de la transaction ; voir Circuits ;
certaines actions de visa pilotent le workflow du parapheur électronique ;
la création, la modification et la suppression d'utilisateurs, de groupes, de rattachements, de suppléances et de privilèges peuvent être synchronisées avec le parapheur électronique.

Ces effets ne transforment pas les routes historiques sign et unsign en routes du nouveau parapheur. Leur enregistrement technique subsiste sans garde explicite, mais elles sont hors du workflow nominal du parapheur électronique.