Champs Conditionnels : Créez des Flux de Signature Intelligents et Ramifiés Via l'API

La plupart des documents de signature ne sont pas statiques. Un champ de nom de conjoint ne doit apparaître que lorsque quelqu'un sélectionne « Marié ». Une section de divulgation supplémentaire doit devenir obligatoire lorsqu'une transaction dépasse un certain montant. Un bloc d'adresse de livraison n'a d'importance que lorsque le signataire coche « Envoyer à une adresse différente ».

Sans les champs conditionnels, vous devez intégrer toute cette logique dans votre propre couche d'interface utilisateur. Vous gérez les boutons de visibilité, les règles de validation et les cas limites côté client, en espérant que rien ne soit contourné. Cela fonctionne, jusqu'au jour où ce n'est plus le cas.

L'API de Firma.dev prend désormais en charge les champs conditionnels de manière native. Vous définissez les règles dans le schéma de vos champs, et l'API gère la visibilité, le statut requis et l'application côté serveur lors de la soumission. Aucune logique d'interface utilisateur personnalisée n'est requise.

Deux types de conditions

Chaque objet de champ de l'API Firma.dev accepte désormais deux nouvelles propriétés nullable : required_conditions et visibility_conditions.

required_conditions remplace la balise statique required d'un champ. Lorsque vous définissez required_conditions, le champ ne devient obligatoire que lorsque les conditions sont évaluées comme vraies en fonction de la valeur d'autres champs au moment de la soumission. Si les conditions sont évaluées comme fausses, le champ est facultatif, peu importe ce qu'indique la balise required.

visibility_conditions contrôle si le signataire voit ou non le champ. Lorsqu'elle est définie, le champ reste masqué à moins que les conditions ne soient évaluées comme vraies. Les champs masqués sont totalement ignorés lors de la validation, vous n'aurez donc pas d'erreurs sur des champs que le signataire n'a jamais vus.

Les deux propriétés sont de type nullable. Lorsqu'elles sont laissées à null (par défaut), le champ se comporte exactement comme auparavant : la balise statique required détermine s'il est obligatoire, et le champ est toujours visible. Les intégrations existantes n'ont besoin d'aucune modification.

Le schéma de condition

Les conditions utilisent une structure imbriquée à trois niveaux : ConditionSet, ConditionGroup et Condition. C'est la partie qu'il convient de bien comprendre, car c'est elle qui vous permet d'obtenir une logique booléenne composable sans arborescence profondément imbriquée.

ConditionSet est le conteneur de premier niveau. Il possède deux propriétés : un opérateur de logic (soit and, soit or) et un tableau de groups (objets ConditionGroup). L'opérateur logique détermine la façon dont les groupes se combinent. Si logic est and, tous les groupes doivent être évalués comme vrais. Si logic est or, il suffit qu'un seul groupe soit évalué comme vrai.

ConditionGroup contient un tableau de conditions (objets Condition individuels). Voici le détail clé : les conditions au sein d'un groupe sont combinées en utilisant la logique opposée du ConditionSet parent. Si le ConditionSet utilise and, les conditions à l'intérieur de chaque groupe sont combinées avec or. Si le ConditionSet utilise or, les conditions de chaque groupe utilisent and.

Ce modèle de logique inversée est ce qui rend le schéma expressif sans nécessiter d'imbrication profonde. Il vous permet de construire des instructions telles que « (montant > 50000 OR type de client égal à Entreprise) AND région n'est pas vide » avec seulement deux groupes à l'intérieur d'un ConditionSet and. Le premier groupe contiendrait deux conditions (le montant et le type de client, combinés avec or car le parent est and), et le second groupe contiendrait une condition pour la vérification de la région.

Condition représente une évaluation unique. Elle fait référence à un field_id (l'UUID d'un autre champ du document), un operator, et une valeur facultative (value) pour la comparaison.

Référence des opérateurs

Firma.dev prend en charge 10 opérateurs de comparaison pour l'ensemble des champs conditionnels :

is_filled vérifie si un champ contient une valeur quelconque. Utile pour afficher des champs de suivi lorsqu'un signataire commence à remplir une section. is_empty est l'inverse, et fonctionne bien pour exiger un champ de secours lorsqu'un champ principal est laissé vide.

equals et not_equals effectuent une correspondance de valeur exacte. Affichez les champs relatifs au conjoint lorsque le statut matrimonial est égal à « Marié », ou masquez une section lorsque le pays n'est pas égal à « US » (États-Unis).

contains et not_contains recherchent des sous-chaînes. Vous pouvez afficher des champs liés à la conformité lorsqu'un champ de description contient « réglementé », ou ignorer une section lorsque les notes ne mentionnent pas un mot-clé spécifique.

greater_than, less_than, greater_than_or_equal et less_than_or_equal gèrent les comparaisons numériques. Ce sont les opérateurs vers lesquels vous vous tournerez pour élaborer une logique basée sur des seuils, comme exiger l'approbation d'un responsable lorsqu'un montant dépasse 10 000, ou appliquer des conditions simplifiées lorsque la valeur d'un contrat tombe en dessous d'un certain chiffre.

À quoi ressemblent les conditions en pratique

Le journal des modifications de l'API comprend un exemple du modèle conditionnel le plus simple : rendre un champ obligatoire uniquement lorsqu'un autre champ a été rempli. La propriété required_conditions prend un ConditionSet avec une logique and, un groupe unique et une condition unique utilisant l'opérateur is_filled :

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

{
  "required_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "operator": "is_filled"
          }
        ]
      }
    ]
  }
}

Le field_id fait référence à l'UUID du champ que vous évaluez. Dans ce cas, dès que ce champ référencé contient une valeur, le champ actuel devient obligatoire. Lorsqu'il est vide, le champ redevient facultatif.

Vous pouvez exploiter ce modèle de plusieurs façons. Pour la visibilité conditionnelle, vous utiliseriez la même structure ConditionSet sous visibility_conditions au lieu de required_conditions. Un champ de texte « Nom du conjoint » qui n'apparaît que lorsqu'une case à cocher « Marié » est cochée utiliserait visibility_conditions avec une seule condition is_filled pointant vers l'UUID du champ de la case à cocher.

Pour une logique multiconditionnelle, vous ajoutez d'autres groupes ou d'autres conditions au sein des groupes. Si vous avez besoin qu'un champ de certification de conformité soit obligatoire uniquement lorsque le montant de la transaction est supérieur à 10 000 AND que le pays est égal à « US », vous créerez un ConditionSet avec une logique and contenant deux groupes, chacun avec une condition. Le premier groupe vérifie le montant avec greater_than, le second vérifie le pays avec equals.

Le modèle le plus expressif utilise la règle de la logique inversée. Supposons que vous souhaitiez afficher une section « Conditions particulières » lorsque (montant > 50 000 OR type de client égal à « Entreprise ») AND région n'est pas vide. Vous devez définir la logic du ConditionSet sur and avec deux groupes. Le premier groupe contient deux conditions (le montant et le type de client), qui sont automatiquement combinées avec or car le parent utilise and. Le second groupe contient l'unique condition de région. Le résultat est une structure propre et lisible qui nécessiterait sinon des arborescences booléennes imbriquées.

Application côté serveur

Toutes les conditions sont évaluées côté serveur lorsque le signataire soumet le document. Ce processus n'est pas facultatif et ne peut pas être contourné par une manipulation côté client.

Si un champ est requis de manière conditionnelle et que la condition s'avère vraie au moment de la soumission, l'API renvoie une erreur de validation lorsque ce champ est vide. Si les visibility_conditions d'un champ sont évaluées comme fausses, le champ est masqué et totalement ignoré lors de la validation. Pas de cas limites, pas de conflits de synchronisation entre votre interface utilisateur et le backend.

Pour les processus de conformité, cela compte. Les conditions que vous définissez dans l'API sont celles qui sont appliquées, un point c'est tout. Votre interface utilisateur côté client peut afficher les états de visibilité et d'obligation en temps réel pour offrir une bonne expérience au signataire, mais la source de vérité se trouve côté serveur.

Où fonctionnent les conditions

Les champs conditionnels sont disponibles sur l'ensemble des interfaces de Firma.dev : l'interface utilisateur de l'éditeur de modèles, l'interface de l'éditeur de demandes de signature, l'éditeur de modèles intégré, l'éditeur de demandes de signature intégré, ainsi que l'API REST complète pour les modèles et les demandes de signature.

Les conditions définies via l'API apparaissent et sont évaluées correctement dans toutes les interfaces utilisateur, et les conditions configurées via les éditeurs sont entièrement accessibles via l'API. Il n'y a aucun écart fonctionnel entre les outils visuels et l'interface de programmation.

Prise en main

Les champs conditionnels ont été introduits avec la version v1.10.0 de l'API Firma.dev. Ils s'ajoutent de manière totalement transparente, sans aucune modification disruptive. Les champs sans conditions continuent de fonctionner exactement comme avant, et les intégrations existantes ne nécessitent aucun changement.

Vous pouvez commencer à utiliser required_conditions et visibility_conditions sur n'importe quel objet de champ dès aujourd'hui. Consultez le journal des modifications de l'API pour obtenir la référence complète du schéma, et la documentation de l'API pour les spécifications complètes des champs.

Firma.dev facture 0,049 € par enveloppe, sans minimum mensuel, sans frais d'utilisateur et sans engagement préalable. Si vous concevez des processus de signature qui doivent s'adapter en fonction des saisies du signataire, les champs conditionnels vous permettent de déplacer cette logique là où elle doit être : dans l'API, appliquée à chaque soumission.

Commencez à utiliser Firma.dev gratuitement, sans carte de crédit requise.