Ajouter des cases à cocher

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.

A propos des champs « Case à cocher »

Un champ « Case à cocher » est un élément qui doit être coché par le participant lors du parcours de signature.

Lorsque vous ajoutez pour la première fois un champ « Case à cocher » à un document, un groupe de cases à cocher avec un identifiant unique est automatiquement créé.

Notez que vous ne pouvez pas ajouter de champs :

  • sur un document qui a déjà été traité par un participant,
  • sur un document qui contient déjà une signature (avant d’être importé dans la transaction).

Créer un groupe de cases à cocher

Pour ajouter des cases à cocher à une transaction, vous devez d’abord créer un groupe de cases à cocher (sauf si vous envoyez une Full transaction request).

Pour créer un groupe de cases à cocher, envoyez une demande à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez checkbox_group dans l’argument type et le nom unique du groupe de cases à cocher dans l’argument name.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=checkbox_group \
-d name=CheckboxGroup1 \
-d minimum_required=1

L’API renvoie un sous-objet field.

{
 "id": "fld_w4Dw",
 "name": "CheckboxGroup1",
 "type": "checkbox_group",
 "minimum_required": 1,
 "built_in": false,
 "updatable": true,
 "deletable": true
}

Conditions

  • Le nom du groupe de cases à cocher doit être unique dans le même document (y compris les groupes de boutons radio). Si le nom du groupe de cases à cocher existe déjà, l’API renvoie une erreur.
  • Si le nom du groupe de cases à cocher n’est pas spécifié, une valeur unique est automatiquement attribuée.
  • La position et la taille ne sont pas disponibles. Le groupe de cases à cocher n’est pas visible dans le document.
  • Les participants sont attribués à l’ensemble du groupe de cases à cocher et non à des cases à cocher distinctes (cela nous permet de nous assurer que toutes les cases à cocher d’un groupe sont attribuées au même participant).

Éditer un groupe de cases à cocher

Vous pouvez éditer le nom d’un groupe de cases à cocher. Pour ce faire, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id} et transmettez le nouveau nom du groupe de cases à cocher dans l’argument name.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_w4Dw \
-d name=NewCheckboxGroup1 /
-d minimum_required=1

L’API renvoie un sous-objet field mis à jour.

{
 "id": "fld_w4Dw",
 "name": "NewCheckboxGroup1",
 "type": "checkbox_group",
 "minimum_required": 1,
 "built_in": false,
 "updatable": true,
 "deletable": true
}

Notez que vous pouvez mettre à jour le nom d’un groupe de cases à cocher, tant que :

  • le participant désigné n’a pas encore signé le document,
  • le validateur n’a pas encore approuvé le document du signataire.

Ajouter une case à cocher

Pour ajouter un champ case à cocher à un groupe de cases à cocher, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez checkbox dans l’argument type, l’id ou le nom du groupe de cases à cocher dans l’argument parent, ainsi que les arguments de position (page, x et y).

Vous pouvez définir d’autres arguments optionnels :

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields \
-d type=checkbox \
-d parent=CheckboxGroup1 \
-d name=Checkbox1 \
-d page=1 \
-d x=23 \
-d y=20 \
-d checked=false
  • parent : le groupe de cases à cocher auquel la case à cocher est liée, identifié par son name ou son id.
  • name : le nom du champ.
  • page : le numéro de la page sur laquelle vous souhaitez positionner le champ.
  • x : coordonnée horizontale du champ sur la page du document (en pixels).
  • y : coordonnée verticale du champ sur la page du document (en pixels).
  • checked : si défini sur true, la case à cocher est déjà cochée lorsqu’elle est ajoutée au document. La valeur par défaut est false.

L’API renvoie un sous-objet field.

{
 "id": "fld_qOK0",
 "name": "Checkbox1",
 "position": {
 "page": 1,
 "x": 23,
 "y": 20,
 "width": 24,
 "height": 24
 },
 "type": "checkbox",
 "built_in": false,
 "checked": false,
 "updatable": true,
 "deletable": true,
 "parent": "fld_w4Dw"
}

Conditions

  • Le nom de la case à cocher doit être unique au sein d’un même groupe. Si le nom de la case à cocher existe déjà, l’API renvoie une erreur.
  • Si le nom de la case à cocher n’est pas spécifié, une valeur unique est automatiquement attribuée.
  • Toutes les cases à cocher doivent être liées à un groupe de cases à cocher (parent).
  • La taille de la case à cocher est fixée à 15px x 15px et ne peut pas être modifiée.
  • La case à cocher ne peut pas être attribuée à un participant (sauf si vous envoyez une Full transaction request). Seuls les groupes de cases à cocher sont attribués aux participants.

Éditer une case à cocher

Pour éditer une case à cocher, envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}.

curl
https://api.universign.com/v1/transactions/tx_AWo949MOq0JE/documents/doc_wWz6/fields/fld_qOK0 \
-d name=Checkbox1Beta \
-d parent=NewCheckboxGroup1 \
-d page=1 \
-d x=50 \
-d y=50 \
-d checked=true

L’API renvoie un sous-objet field mis à jour.

{
 "id": "fld_qOK0",
 "name": "Checkbox1Beta",
 "position": {
 "page": 1,
 "x": 50,
 "y": 50,
 "width": 24,
 "height": 24
 },
 "type": "checkbox",
 "built_in": false,
 "checked": true,
 "updatable": true,
 "deletable": true,
 "parent": "fld_w4Dw"
}

Conditions

  • Le nom mis à jour de la case à cocher doit être unique au sein du même groupe. Si le nom de la case à cocher existe déjà, l’API renvoie une erreur et aucune modification n’est enregistrée.
  • Le nom de la case à cocher ne peut pas être mis à jour avec une valeur nulle, sinon l’API renvoie une erreur.
  • Le nom du groupe de cases à cocher (parent) ne peut pas être mis à jour avec une valeur nulle, sinon l’API renvoie une erreur.
  • Toutes les cases à cocher doivent être liées à un groupe de cases à cocher (parent).
  • La taille de la case à cocher est fixée à 15px x 15px et ne peut pas être modifiée.

Déplacer une case à cocher

Vous pouvez déplacer une case à cocher vers une autre page du même document ou vers un autre document. Envoyez une requête à POST /v1/transactions/{transaction_id}/documents/{document_id}/fields et transmettez le document cible dans l’URL et l’identifiant du champ que vous souhaitez déplacer dans l’argument move_from :

curl
https://api.universign.com/v1/transactions/tx_DwYGle91EQZA/documents/doc_aJ4k/fields \
-d move_from=fld_A0Oz
  • Lorsque vous déplacez un champ case à cocher vers une autre page du même document, le champ conserve ses paramètres d’origine et reste dans le même groupe.
  • Lorsque vous déplacez un champ case à cocher vers un autre document de la transaction :
    • si le document cible contient déjà un groupe de cases à cocher portant le même nom que dans le document d’origine, la case à cocher y est ajoutée et hérite des attributs du groupe (tels que le signataire attribué).
    • si le document cible ne contient aucun groupe de cases à cocher portant le même nom que dans le document d’origine, un nouveau groupe de cases à cocher est créé avec le même nom que dans le document d’origine et le champ de case à cocher y est ajouté.

Notez que vous ne pouvez pas déplacer un groupe de cases à cocher.

Pour plus d’informations, consultez Déplacer un champ.

Supprimer une case à cocher / un groupe de cases à cocher

Pour supprimer un groupe de cases à cocher, vous devez :

  1. Supprimer le participant attribué au groupe de cases à cocher.
  2. Supprimer toutes les cases à cocher liées au groupe de cases à cocher.
  3. Supprimer le groupe de cases à cocher.

Notez que vous ne pouvez pas supprimer un groupe de cases à cocher si le participant attribué a déjà effectué son action (validation ou signature).

Pour supprimer une case à cocher ou un groupe de cases à cocher, envoyez une requête à DELETE /v1/transactions/{transaction_id}/documents/{document_id}/fields/{field_id}.

curl
https://api.universign.com/v1/transactions/tx_qE67Zr640eVX/documents/doc_bd2a/fields/fld_w4Dw \
-X DELETE

Notez que les champs de case à cocher intégrés ne peuvent pas être supprimés.

Ajouter un champ image
← Précédent
Ajouter des boutons radio
Suivant →
Espace Développeur
Guides
Services
Référence API