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

La plupart des documents à signer ne sont pas statiques. Un champ de nom de conjoint ne devrait 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 en dollars. Un bloc d'adresse de livraison n'est pertinent que lorsque le signataire coche "Expédier à une adresse différente".

Sans champs conditionnels, vous construisez toute cette logique dans votre propre couche UI. Vous gérez les bascules 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'à ce que ça ne fonctionne plus.

L'API de Firma.dev prend maintenant en charge les champs conditionnels nativement. Vous définissez les règles dans votre schéma de champs, et l'API gère la visibilité, le statut requis et l'application côté serveur lors de la soumission. Aucune logique UI personnalisée n'est nécessaire.

Deux types de conditions

Chaque objet champ dans l'API Firma.dev accepte maintenant deux nouvelles propriétés pouvant être nulles : required_conditions et visibility_conditions.

required_conditions remplace le drapeau statique required sur un champ. Lorsque vous définissez required_conditions, le champ devient obligatoire uniquement lorsque les conditions s'évaluent à vrai en fonction des autres valeurs de champ au moment de la soumission. Si les conditions s'évaluent à faux, le champ est facultatif, peu importe ce que dit le drapeau required.

visibility_conditions contrôle si le signataire voit le champ ou non. Lorsqu'il est défini, le champ reste caché à moins que les conditions ne s'évaluent à vrai. Les champs cachés sont entièrement ignorés lors de la validation, donc vous n'obtenez pas d'erreurs sur les champs que le signataire n'a jamais vus.

Les deux propriétés peuvent être nulles. Lorsqu'on les laisse à null (le défaut), le champ fonctionne exactement comme avant : le drapeau statique required détermine s'il est requis, et le champ est toujours visible. Les intégrations existantes n'ont besoin d'aucun changement.

Le schéma de conditions

Les conditions utilisent une structure imbriquée à trois niveaux : ConditionSet, ConditionGroup et Condition. C'est la partie à comprendre soigneusement, car c'est ce qui vous permet d'avoir une logique booléenne composable sans arbres profondément imbriqués.

ConditionSet est le conteneur de niveau supérieur. Il a deux propriétés : un opérateur logic (soit and, soit or) et un tableau de groups (objets ConditionGroup). L'opérateur de logique détermine comment les groupes se combinent. Si logic est and, tous les groupes doivent s'évaluer à vrai. Si logic est or, n'importe quel groupe évaluant à vrai suffit.

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 parent ConditionSet. 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 à l'intérieur de chaque groupe utilisent and.

Ce modèle de logique opposée est ce qui rend le schéma expressif sans nécessiter d'imbrications profondes. Il vous permet de construire des déclarations comme "(montant > 50000 OU type de client égal Entreprise) ET la région n'est pas vide" avec seulement deux groupes à l'intérieur d'un ConditionSet and. Le premier groupe contiendrait deux conditions (montant et type de client, combinées avec or parce que le parent est and), et le second groupe contiendrait une condition pour la vérification de la région.

Condition est une évaluation unique. Elle référence un field_id (l'UUID d'un autre champ sur le document), un operator, et une value optionnelle pour la comparaison.

Référence d'opérateur

Firma.dev prend en charge 10 opérateurs de comparaison sur les champs conditionnels :

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

equals et not_equals effectuent une correspondance exacte de valeur. Montrer les champs du conjoint lorsque l'état matrimonial est égal à "Marié", ou cacher une section lorsque le pays n'est pas égal à "US".

contains et not_contains vérifient les sous-chaînes. Vous pourriez montrer des champs liés à la conformité lorsqu'un champ de description contient "réglementé", ou sauter 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 que vous utiliseriez pour construire une logique basée sur des seuils, comme exiger l'approbation du gestionnaire lorsqu'un montant dépasse 10 000 ou appliquer des termes simplifiés lorsqu'une valeur de contrat tombe en dessous d'un certain nombre.

Comment les conditions apparaissent en pratique

Le changelog de l'API inclut 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 seul groupe et une seule condition 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 référence l'UUID du champ que vous êtes en train d'évaluer. Dans ce cas, chaque fois que ce champ référencé a une valeur, le champ actuel devient obligatoire. Lorsqu'il est vide, le champ redevient facultatif.

Vous pouvez construire ce modèle dans plusieurs directions. Pour la visibilité conditionnelle, vous utiliseriez la même structure ConditionSet sous visibility_conditions au lieu de required_conditions. Un champ 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 de la case.

Pour une logique multi-conditions, vous ajoutez plus de groupes ou plus de conditions à l'intérieur 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 ET que le pays est égal à "US", vous créeriez 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 opposée. Supposons que vous vouliez montrer une section "Termes spéciaux" lorsque (montant > 50 000 OU type de client est "Entreprise") ET la région n'est pas vide. Vous définissez la logic du ConditionSet sur and avec deux groupes. Le premier groupe contient deux conditions (montant et type de client), qui sont automatiquement combinées avec or car le parent utilise and. Le second groupe contient la seule condition régionale. Le résultat est une structure propre et lisible qui nécessiterait autrement des arbres booléens imbriqués.

Application côté serveur

Toutes les conditions sont évaluées côté serveur lorsque le signataire soumet. Ce n'est pas optionnel, et ce n'est pas quelque chose que l'on peut contourner par une manipulation côté client.

Si un champ est conditionnellement requis et que la condition s'évalue à vrai au moment de la soumission, l'API renvoie une erreur de validation lorsque ce champ est vide. Si les visibility_conditions d'un champ s'évaluent à faux, le champ est caché et entièrement ignoré lors de la validation. Aucun cas limite, aucune condition de course entre votre UI et le backend.

Pour les workflows de conformité, cela compte. Les conditions que vous définissez dans l'API sont les conditions qui sont appliquées, point final. Votre UI côté client peut rendre en temps réel les états de visibilité et de nécessité pour une bonne expérience de signataire, mais la source de vérité réside côté serveur.

Où les conditions fonctionnent

Les champs conditionnels sont disponibles sur toutes les surfaces de Firma.dev : l'interface de l'éditeur de modèle, l'interface de l'éditeur de demande de signature, l'éditeur de modèles intégré, l'éditeur de demandes de signature intégré, et l'API REST complète pour les modèles et les demandes de signature.

Les conditions définies via l'API apparaissent et s'évaluent correctement sur toutes les surfaces UI, et les conditions configurées via les éditeurs sont pleinement accessibles via l'API. Il n'y a pas d'écart de fonctionnalité entre les outils visuels et l'interface programmatique.

Démarrer

Les champs conditionnels ont été déployés dans la version v1.10.0 de l'API de Firma.dev. Ils sont entièrement additifs sans changement pouvant casser les fonctionnalités existantes. Les champs sans conditions continuent de fonctionner exactement comme avant, et les intégrations existantes ne nécessitent aucune modification.

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

Firma.dev facture 0,029 € par enveloppe sans minimum mensuel, sans frais par utilisateur, et sans engagements préalables. Si vous développez des workflows 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 gratuitement avec Firma.dev, aucune carte de crédit requise.