Documents & champs de signature

Une fois le parapheur créé à l’état brouillon (la fondation Parapheurs), on y charge les documents et l’on précise où chaque signature doit apparaître — le tout avant de lancer le parapheur.

Le modèle : blob, part, document

Trois niveaux, qui séparent trois préoccupations :

• Blob (blb_) — le transfert : les octets bruts téléversés (le blob les conserve à l’identique, son empreinte = celle du fichier d’origine). Un gros fichier peut être envoyé en plusieurs blobs (section Gros fichiers & limite de taille).
• Part — le fichier : un fichier reconstitué à partir de la séquence de ses blobs, puis normalisé / préparé (conversion éventuelle au format PDF/A ; jokers de signature [SignatureField#i] remplacés par des champs de signature visible, etc.). Sa taille et son empreinte peuvent donc différer du blob — c’est attendu.
• Document (doc_) — le rôle dans le parapheur : à signer ou pièce jointe, ordre d’affichage, confidentialité, champs de signature.

En pratique, vous n’enchaînez pas trois appels manuels. Le cas courant — un fichier = une part = un document — se fait en un seul appel (createDocuments=true, section Téléverser un document : trois méthodes). On ne descend dans les niveaux séparément que pour deux besoins précis : 1. téléverser un gros fichier en morceaux (plusieurs blobs, section Gros fichiers & limite de taille) ou 2. placer explicitement les champs de signature (POST /documents, section Créer les documents : automatique ou explicite). Cette séparation sert donc à découpler le transfert des octets (gros fichiers, reprise) de la préparation du fichier puis de son rôle dans le parapheur.

Un document peut référencer plusieurs parts — par exemple l’original et une version convertie (isOriginal les distingue ; displayedParts désigne ce qui est présenté au signataire). Ce raffinement est géré par la plateforme : l’intégrateur fournit en général une seule part par document.

Téléverser un document : trois méthodes

a) Fichier unique — upload direct. Le plus simple pour un seul fichier : le binaire dans le corps, le nom porté par l’en-tête Content-Disposition :

POST /api/workflows/{workflowId}/parts?createDocuments=true&convertToPdf=true&pdf2pdfa=auto&signatureProfileId=sip_…
Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
%PDF-1.3 … (octets du PDF)

b) Multipart — un ou plusieurs fichiers en une seule requête.

POST /api/workflows/{workflowId}/parts?createDocuments=true&convertToPdf=true&pdf2pdfa=auto&signatureProfileId=sip_…
Content-Type: multipart/form-data; boundary=…
--…
Content-Type: application/pdf
Content-Disposition: form-data; name="document"; filename="document.pdf"
%PDF-1.3 … (octets du PDF)
--…--

c) Blobs → part — téléversement binaire, et voie recommandée pour les gros fichiers. On téléverse d’abord le(s) binaire(s), puis on assemble la part :

POST /api/workflows/{workflowId}/blobs
Content-Type: application/pdf
%PDF-1.3 … (octets du PDF)

Réponse : { "id": "blb_…", "hash": "…", "workflowId": "…" }. On construit ensuite la part à partir de la séquence de blobs :

POST /api/workflows/{workflowId}/blobs/parts?createDocuments=true&convertToPdf=true&pdf2pdfa=auto&signatureProfileId=sip_…
Content-Type: application/json
{ "parts": [ { "filename": "document.pdf", "contentType": "application/pdf", "blobs": [ "blb_…" ] } ] }

Paramètres de requête (communs aux trois méthodes) :

Gros fichiers & limite de taille

• La taille maximale d’un document est fixée par le paramètre tenant maxDocumentSize. Valeurs configurables : 5, 10 (défaut), 25 ou 50 Mo ; les paliers 100 Mo et 200 Mo requièrent une option payante — autrement dit, dépasser 50 Mo nécessite une option. Un dépassement renvoie MaxDocumentSizeExceeded (document) ou MaxDocumentSizeExceededByBlob (blob).
• Pour un gros document (jusqu’à plusieurs centaines de Mo), la méthode c permet de le découper en plusieurs blobs téléversés séparément, puis concaténés dans l’ordre en une seule part ("blobs": [ "blb_1", "blb_2", … ]). On évite ainsi une unique requête de très grande taille.

Créer les documents : automatique ou explicite

• Automatique — avec createDocuments=true (méthodes a, b ou c) : la plateforme crée directement le(s) document(s).
• Explicite — POST /api/workflows/{workflowId}/documents : indispensable pour placer les champs de signature (pdfSignatureFields, section Positionner le champ de signature). On construit le document à partir de parts déjà enregistrées :

POST /api/workflows/{workflowId}/documents
Content-Type: application/json
{
  "parts": [ { "filename": "Document", "contentType": "application/pdf", "size": 18667, "hash": "…", "isOriginal": true } ],
  "signatureProfileId": "sip_…",
  "pdfSignatureFields": [ { "imagePage": -1, "imageX": 390, "imageY": 710, "imageWidth": 150, "imageHeight": 80 } ],
  "confidentiality": false,
  "orderIndex": 10
}

Enregistrer la part d’abord. Les parts référencées ici (par hash + size) doivent avoir été enregistrées au préalable via POST /api/workflows/{id}/blobs/parts (méthode c, sans createDocuments), appel qui renvoie chaque part avec son hash et sa size. Référencer directement un blob non assemblé en part échoue avec WorkflowPartNotFound.

Autres champs du document (corps de POST /documents) :

À signer ou pièce jointe : signatureProfileId

Le paramètre signatureProfileId détermine la nature du document créé :

• renseigné → document à signer avec ce profil de signature (le profil personnalise notamment le cartouche) ;
• vide → le document est une pièce jointe ;
• absent → la plateforme tente de trouver un profil de signature approprié.

Recommandation. Précisez toujours un signatureProfileId explicite (voir la fondation Profils de signature > Rôle & cycle de vie : ne vous reposez pas sur la résolution automatique du profil par défaut (un même type de document peut compter plusieurs profils par défaut, et la prise en compte d’un changement peut être différée).

Positionner le champ de signature

Il existe trois façons d’indiquer où une signature doit apparaître sur un PDF.

a) Joker (ancre texte) — [SignatureField#i]. On insère, à la génération du PDF, une chaîne de la forme [SignatureField#i], où i est le rang de la signature qui sera apposée sur le document. [SignatureField#3] désigne ainsi le champ de la 3ᵉ signature ; si le parapheur ne prévoit que 2 signatures, ce champ n’est pas utilisé. La plateforme remplace le joker par un champ de signature PAdES dont le coin haut-gauche correspond à la position du premier crochet [ du joker. C’est idéal pour les documents de longueur variable, puisque l’ancre suit le texte.

b) Coordonnées — pdfSignatureFields (lors de la création explicite du document, section Créer les documents : automatique ou explicite) :

Repère. L’origine est en haut à gauche de la page et imageY descend vers le bas (convention « écran »), à la différence du repère PDF natif (origine en bas). Unité = points (1/72 pouce), cohérente avec les dimensions du cartouche (Profils de signature > Le cartouche (signature visible PAdES)).

c) Champ existant — fieldId : identifiant d’un champ de signature déjà présent dans le PDF (AcroForm). fieldId est prioritaire : s’il est défini, les coordonnées (imagePage / imageX / imageY / imageWidth / imageHeight) sont ignorées.

⚠️ Signatures en parallèle. Le rang i d’un joker (comme l’ordre des champs) fixe où chaque signature se pose, mais pas qui la pose lorsque plusieurs signataires signent en parallèle dans une même étape. Il ne faut donc jamais imprimer de libellé nominatif au-dessus d’une zone de signature : c’est le cartouche (pavé) de signature apposé par la plateforme qui identifie le signataire. Voir la fondation Règles d’intégration technico-juridiques.