> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.goodflag.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goodflag.com/_mcp/server. # Uploader les documents > Ajouter des documents au parapheur # Documents & champs de signature Une fois le parapheur créé à l'état brouillon (la fondation [*Parapheurs*](/wm/guides/integration/creer-un-parapheur)), 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*](#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*](#televerser-un-document-trois-methodes)). 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*](#gros-fichiers-limite-de-taille)) ou 2. **placer explicitement les champs de signature** (`POST /documents`, section [*Créer les documents : automatique ou explicite*](#creer-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` : ```http 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.** ```http 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 : ```http 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 : ```http 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) : | Paramètre | Rôle | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createDocuments` | Créer directement le(s) **document(s)** à partir des parts (`true`), ou se contenter d'**enregistrer les parts** (`false` — pour la création explicite, section [*Créer les documents : automatique ou explicite*](#creer-les-documents-automatique-ou-explicite)). | | `signatureProfileId` | **Profil de signature** des documents créés → fixe leur **nature** (à signer / pièce jointe), section [*À signer ou pièce jointe : signatureProfileId*](#a-signer-ou-piece-jointe-signatureprofileid). | | `convertToPdf` | Convertir (si possible) un fichier **non-PDF en PDF** après traitement (par exemple Microsoft Word, Excel ou Powerpoint si l'option est disponible). | | `pdf2pdfa` | Convertir les PDF en **PDF/A** : `disabled` / `forced` / `auto` (défaut `auto`). | | `unzip` | **Décompresser une archive zip** : chaque fichier interne devient un **document distinct**, et **l'arborescence des sous-dossiers est préservée** — le chemin est conservé dans le nom du document et **restitué sous forme de dossiers** dans le parapheur. `orderIndex` suit **l'ordre des fichiers** de l'archive. *(Sans `unzip`, le `.zip` reste un seul document.)* | | `ignoreAttachments` | **N'a d'effet que si `signatureProfileId` est vide** (fichier qui deviendrait une **pièce jointe**) : `ignoreAttachments=true` fait alors **ignorer purement et simplement** le fichier (aucun document créé). Avec un profil renseigné (document à signer) — ou absent (profil résolu automatiquement) — le paramètre est **sans effet**. Utile comme garde-fou lors d'un import en lot / générique pour **écarter les pièces jointes**. | ## 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*](#positionner-le-champ-de-signature)). On construit le document à partir de parts **déjà enregistrées** : ```http 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`) : | Champ | Rôle | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confidentiality` | Marque le document comme **pièce jointe confidentielle** : visible uniquement des destinataires dont l'étape l'autorise (`viewConfidentialAttachments`, fondation [*Parapheurs > Les étapes — steps (niveau 2)*](/wm/guides/integration/creer-un-parapheur#les-etapes-steps-niveau-2)). | | `orderIndex` | Personnalise l'**ordre d'affichage** des documents. | | `subOrderIndex` | Ordre d'affichage **secondaire** (regroupement / dossier). | ## À 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*](/wm/api-reference/concepts/profils-de-signature#role-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*](#creer-les-documents-automatique-ou-explicite)) : | Champ | Rôle | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `imagePage` | Page (à partir de 1 ; **négatif = depuis la dernière page**, `-1` = dernière). | | `imageX` / `imageY` | Position du **coin haut-gauche** du champ, en **points** : `imageX` depuis la **gauche**, `imageY` depuis le **haut** de la page. | | `imageWidth` / `imageHeight` | Dimensions du champ, en **points** (la référence les note « in pixel » = pixels à 72 dpi = points). | > **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)*](/wm/api-reference/concepts/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*](/wm/guides/integration/bonnes-pratiques-juridiques).