Ajouter un champ de signature/consultation

Un champ est l’objet qui porte l’action à effectuer par un participant. Un champ a un type qui peut être soit :

• signature (pour une demande de signature par une personne physique ou un cachet par une personne morale),
• visa (pour une demande de consultation par une personne physique),
• text (pour un champ de texte à remplir par le participant),
• label (pour un texte en lecture seule ajouté par le créateur de la transaction sur un document),
• checkbox_group (pour un groupe de cases à cocher par le participant),
• checkbox (pour une case à cocher par le participant),
• radio_group (pour un groupe de boutons radio à cocher par le participant),
• radiobutton (pour un bouton radio à cocher par le participant),
• dropdown (pour une liste déroulante dans laquelle le participant doit sélectionner une option).
• image (pour un champ image dans lequel le participant doit importer un fichier image),
• signature_date (pour un champ qui affiche la date et l’heure auxquelles le participant a signé le document),
• full_name (pour un champ qui affiche le nom complet du participant),
• email (pour un champ qui affiche l’email du participant),
• company_name (pour un champ qui affiche le nom de l’entreprise du participant),
• job_title (pour un champ qui affiche la fonction du participant).

Vous pouvez également ajouter des Paraphes.

Créer un champ « signature » ou « visa »

Pour créer un champ, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez l’argument type (soit signature, soit visa) selon que vous demandez une signature ou la consultation du document. Vous pouvez, si vous le souhaitez, définir un nom pour ce champ :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields \
-d type=signature \
-d name=MyFieldName

Notez que la valeur par défaut de type est signature : il n’est donc pas obligatoire de le passer si vous demandez une signature.

L’API renvoie un sous-objet field.

{
    "id": "fld_a998",
    "type": "signature",
    "built_in": false,
    "consents": [],
    "updatable": true,
    "deletable": true
}

Créer un champ de signature avec une position sur la page du document

Un champ de signature peut être visible ou invisible dans le PDF. Lorsque vous créez un champ de signature, il est invisible par défaut, mais vous pouvez spécifier sa position sur la page du document. Pour ce faire, vous pouvez indiquer les coordonnées du champ sur la page du document ou utiliser une ancre.

Notez que les champs visa sont toujours invisibles et ne peuvent pas être positionnés sur la page du document.

Que le champ soit visible ou non dans le document PDF, toutes les informations relatives aux opérations de signature, de visa et de cachet s’affichent toujours dans le panneau de signature d’Adobe.

Via des coordonnées

La position d’un champ peut être définie par son numéro de page ainsi que par ses coordonnées horizontales (x) et verticales (y) en pixels. Pour créer un champ dont la position est définie par des coordonnées, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez les arguments de position (page, x et y) :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields \   
-d type=signature \
-d name=MyFieldName \
-d page=1 \ 
-d x=75 \ 
-d y=200  

Notez que les valeurs des coordonnées x et y ne doivent pas dépasser les dimensions du document importé, sinon l’API renvoie une erreur.

Notez que la taille de la zone de signature est fixée à 200px x 50px et ne peut pas être modifiée. Assurez-vous que la zone de signature est correctement positionnée dans le document. Si l’un des bords de la zone de signature dépasse les limites du document, l’API renvoie une erreur.

Notez que si vous souhaitez positionner automatiquement la zone de signature sur la dernière page du document, la valeur page doit être définie sur -1.

Cas d’usage

Pour un document au format A4 portrait, les dimensions maximales sont de 595 (largeur) et 841 (hauteur). Sachant que les dimensions par défaut d’un champ de signature sont de 200 (largeur) et 50 (hauteur) et que les coordonnées x et y définissent la position du coin inférieur gauche du champ de signature, les valeurs maximales des coordonnées du champ sont :

• x=395
• y=791

Dans ce cas, le champ de signature est placé dans le coin supérieur droit du document.

Pour vous assurer que votre champ de signature est bien positionné dans le document de transaction, voici un rappel des dimensions maximales des formats de document les plus courants :

• Document A4 portrait : largeur = 595 / hauteur = 841
• Document A4 paysage : largeur = 841 / hauteur = 595
• Document A3 portrait : largeur = 841 / hauteur = 1190
• Document A3 paysage : largeur = 1190 / hauteur = 841

Via une ancre

Universign peut rechercher une chaîne de caractères dans le document et positionner automatiquement le champ de signature juste en dessous. Pour créer un champ avec une ancre, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez la valeur de la chaîne de caractères en tant qu’argument anchor :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields \  
-d type=signature 
-d name=MyFieldName
-d page=1 
-d anchor=client signature  

Il n’est pas obligatoire de préciser le numéro de page lorsque l’on utilise une ancre. Cela peut toutefois s’avérer utile si la chaîne de caractères fournie apparaît plusieurs fois dans le document. Si cette chaîne apparaît plusieurs fois au sein d’une même page, le système positionnera l’ancre uniquement sous la première occurrence.

Si vous ne définissez aucune coordonnée x et y, la cartouche de signature est automatiquement positionnée sur le premier caractère de l’ancre.

Notez que dans ce cas, les coordonnées x et y définissent la position de la cartouche de signature par rapport à l’ancre.

La position d’un champ dans le document peut être définie lors de la création du champ ou via une mise à jour. Si vous souhaitez mettre à jour la position du champ, transmettez l’identifiant du champ dans l’URL de la requête et définissez la position comme indiqué ci-dessus. Voici un exemple de requête de mise à jour :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields/fld_a998 \  
-d type=signature \
-d name=MyNewFieldName \
-d page=2 \ 
-d x=75 \ 
-d y=200    

Créer un champ de signature avec des dimensions personnalisées

Lorsque vous créez un champ signature, vous pouvez définir sa position ainsi que ses dimensions (hauteur et largeur). Vous devez toutefois respecter les conditions suivantes :

• La valeur minimale de height est 23,
• La valeur minimale de width est 92,
• Le ratio height doit être 4 x width,
• Vous devez transmettre les arguments page, x et y.

Pour créer un champ de signature avec des dimensions personnalisées, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields comme suit :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_4dn/fields \   
-d type=signature \
-d name=MyFieldName \
-d page=1 \ 
-d x=75 \ 
-d y=200 \
-d height=25 \
-d width=100

Utiliser un champ intégré (built-in)

Il peut arriver que vous deviez importer un document contenant déjà des champs vides.

Ces champs sont appelés champs built-in et sont identifiés par leur nom et/ou leur identifiant.

Un champ built-in peut être un champ de signature, un champ de saisie de texte ou n’importe quel champ de formulaire (case à cocher, bouton radio ou liste déroulante).

Notez que les champs ‘built-in’ ne peuvent être ni déplacés ni supprimés ni modifiés. Dans le cas d’un champ de signature built-in, ses dimensions sont respectées dans le rendu du cartouche de signature.

Vous pouvez attribuer un participant aux champs built-in de la même manière que pour les champs ajoutés lors de la création de la transaction.

Lorsque vous importez un document contenant des champs built-in, la réponse de l’API est la suivante.

Notez que dans cet exemple, le document importé contient déjà un champ signature et un checkbox_group avec 4 options.

{
  "id" : "doc_WEaB",
  "name" : "Doc_test_built-in.pdf",
  "editable" : true,
  "updatable" : true,
  "deletable" : false,
  "fields" : [ {
    "id" : "fld_m9",
    "name" : "CustomerZoneEsignatureBDC",
    "position" : {
      "page" : 3,
      "x" : 302,
      "y" : 60,
      "width" : 200,
      "height" : 50
    },
    "type" : "signature",
    "built_in" : true,
    "consents" : [ ],
    "optional_consents" : [ ],
    "updatable" : true,
    "deletable" : false
  }, {
    "id" : "fld_q11V",
    "name" : "marketingConsentEmail",
    "type" : "checkbox_group",
    "built_in" : false,
    "updatable" : true,
    "deletable" : false,
    "minimum_required" : 0
  }, {
    "id" : "fld_5eQ5",
    "name" : "marketingConsentEmail",
    "type" : "checkbox",
    "position" : {
      "page" : 2,
      "x" : 139,
      "y" : 90,
      "width" : 10,
      "height" : 10
    },
    "built_in" : true,
    "updatable" : true,
    "deletable" : false,
    "parent" : "fld_q11V",
    "checked" : false
  }, {
    "id" : "fld_Qz5m",
    "name" : "marketingConsentPostalMail",
    "type" : "checkbox_group",
    "built_in" : false,
    "updatable" : true,
    "deletable" : false,
    "minimum_required" : 0
  }, {
    "id" : "fld_VbvL",
    "name" : "marketingConsentPostalMail",
    "type" : "checkbox",
    "position" : {
      "page" : 2,
      "x" : 220,
      "y" : 89,
      "width" : 10,
      "height" : 10
    },
    "built_in" : true,
    "updatable" : true,
    "deletable" : false,
    "parent" : "fld_Qz5m",
    "checked" : false
  }, {
    "id" : "fld_J2qn",
    "name" : "marketingConsentTelephone",
    "type" : "checkbox_group",
    "built_in" : false,
    "updatable" : true,
    "deletable" : false,
    "minimum_required" : 0
  }, {
    "id" : "fld_9lW1",
    "name" : "marketingConsentTelephone",
    "type" : "checkbox",
    "position" : {
      "page" : 2,
      "x" : 306,
      "y" : 89,
      "width" : 10,
      "height" : 10
    },
    "built_in" : true,
    "updatable" : true,
    "deletable" : false,
    "parent" : "fld_J2qn",
    "checked" : false
  }, {
    "id" : "fld_6A4Q",
    "name" : "marketingConsentSMS",
    "type" : "checkbox_group",
    "built_in" : false,
    "updatable" : true,
    "deletable" : false,
    "minimum_required" : 0
  }, {
    "id" : "fld_b7Ad",
    "name" : "marketingConsentSMS",
    "type" : "checkbox",
    "position" : {
      "page" : 2,
      "x" : 390,
      "y" : 89,
      "width" : 10,
      "height" : 10
    },
    "built_in" : true,
    "updatable" : true,
    "deletable" : false,
    "parent" : "fld_6A4Q",
    "checked" : false
  }, {
    "id" : "fld_eEDw",
    "name" : "CocheSocieteSignataireHabilite",
    "type" : "checkbox_group",
    "built_in" : false,
    "updatable" : true,
    "deletable" : false,
    "minimum_required" : 0
  }, {
    "id" : "fld_WE3n",
    "name" : "CocheSocieteSignataireHabilite",
    "type" : "checkbox",
    "position" : {
      "page" : 3,
      "x" : 44,
      "y" : 677,
      "width" : 10,
      "height" : 10
    },
    "built_in" : true,
    "updatable" : true,
    "deletable" : false,
    "parent" : "fld_eEDw",
    "checked" : false
  } ],
  "big_file" : false,
  "available" : true
}

Vous pouvez attribuer un participant à des champs built-in de la même manière que pour les champs de signature ou de formulaire. Nous vous recommandons toutefois d’utiliser le nom du champ built-in (plutôt que son identifiant) afin de distinguer facilement chaque champ built-in.

Lorsque vous attribuez un participant à un champ de signature built-in, il vous suffit d’indiquer le nom du champ dans votre requête. L’API détectera et conservera automatiquement la position d’origine (page, x, y) et les dimensions (largeur, hauteur) du champ de signature intégré, telles qu’elles apparaissent dans le PDF source.

Important : lorsqu’un champ de signature built-in présente des dimensions très réduites, les éléments du cartouche de signature (texte, id de transaction, date) s’adapteront pour s’y insérer et pourront être tronqués ou complétés afin de respecter exactement les dimensions spécifiées.

Pour plus d’informations sur l’attribution d’un participant à un champ, consultez Demander une signature.

---

Empêcher le téléchargement de documents

← Précédent

Ajouter un champ Paraphe

Suivant →