Guides
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 pour le nom du conjoint ne devrait apparaître que lorsqu’une personne sélectionne « Married ». Une section de divulgation supplémentaire devrait 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 « Ship to different address ».
Sans champs conditionnels, vous implémentez toute cette logique dans votre propre couche d’interface utilisateur. 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 passe entre les mailles du filet. Ça fonctionne, jusqu’à ce que ça ne fonctionne plus.
L’API de Firma.dev prend désormais 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 obligatoire et l’application côté serveur lors de la soumission. Aucune logique d’interface personnalisée n’est nécessaire.
Deux types de conditions
Chaque objet de champ dans l’API de Firma.dev accepte désormais deux nouvelles propriétés nullables : 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 sont évaluées à true en fonction des valeurs des autres champs au moment de la soumission. Si les conditions sont évaluées à false, le champ est facultatif, quelle que soit la valeur indiquée par le drapeau required.
visibility_conditions contrôle si le signataire voit le champ ou non. Lorsqu’elle est définie, le champ reste masqué sauf si les conditions sont évaluées à true. Les champs masqués sont entièrement ignorés pendant la validation, vous n’obtenez donc pas d’erreurs pour des champs que le signataire n’a jamais vus.
Les deux propriétés sont nullables. Lorsqu’elles sont laissées à null (la valeur par défaut), le champ se comporte exactement comme auparavant : le drapeau statique required détermine s’il est obligatoire, 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 qui mérite d’être bien comprise, car c’est elle qui vous offre une logique booléenne composable sans arbres profondément imbriqués.
ConditionSet est le conteneur de niveau supérieur. Il possède deux propriétés : un opérateur logic (soit and soit or) et un tableau de groups (objets ConditionGroup). L’opérateur logique détermine comment les groupes se combinent. Si logic est and, tous les groupes doivent être évalués à true. Si logic est or, qu’un seul groupe évalué à true suffit.
ConditionGroup contient un tableau de conditions (objets Condition individuels). Voici le détail clé : les conditions à l’intérieur d’un groupe sont combinées à l’aide de la logique opposée de celle 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 à l’intérieur de chaque groupe utilisent and.
Ce schéma de logique opposée est ce qui rend le schéma expressif sans nécessiter d’imbrication profonde. Il vous permet de construire des expressions comme « (amount > 50000 OR customer type equals Enterprise) AND region is not empty » avec seulement deux groupes à l’intérieur d’un and ConditionSet. Le premier groupe contiendrait deux conditions (amount et customer type, combinées avec or parce que le parent est and), et le second groupe contiendrait une seule condition pour la vérification de la région.
Condition est une évaluation unique. Elle fait référence à un field_id (l’UUID d’un autre champ sur le document), à un operator et à une value facultative pour la comparaison.
Référence des opérateurs
Firma.dev prend en charge 10 opérateurs de comparaison pour les champs conditionnels :
is_filled vérifie si un champ possède une valeur quelconque. Utile pour afficher des champs de suivi lorsqu’un signataire commence à renseigner une section. is_empty en 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 des valeurs. Affichez les champs liés au conjoint lorsque l’état matrimonial est égal à « Married », ou masquez une section lorsque le pays n’est pas égal à « US ».
contains et not_contains vérifient la présence de sous-chaînes. Vous pourriez afficher des champs liés à la conformité lorsqu’un champ de description contient « regulated », 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 tourneriez pour construire une logique basée sur des seuils, par exemple exiger l’approbation d’un responsable lorsqu’un montant dépasse 10 000 ou appliquer des conditions simplifiées lorsqu’une valeur de contrat tombe en dessous d’un certain nombre.
À quoi ressemblent les conditions en pratique
L’historique des modifications de l’API inclut un exemple du schéma conditionnel le plus simple : rendre un champ obligatoire uniquement lorsqu’un autre champ a été renseigné. La propriété required_conditions prend un ConditionSet avec la logique and, un groupe unique et une seule condition utilisant l’opérateur is_filled :
Le field_id référence l’UUID du champ que vous évaluez. Dans ce cas, chaque fois que ce champ référencé contient une valeur, le champ actuel devient obligatoire. Lorsqu’il est vide, le champ redevient facultatif.
Vous pouvez décliner 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 de texte « Spouse Name » qui n’apparaît que lorsque la case à cocher « Married » 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 à plusieurs conditions, vous ajoutez davantage de groupes ou davantage de conditions à l’intérieur des groupes. Si vous devez rendre obligatoire un champ de certification de conformité 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 logique opposée. Supposons que vous vouliez afficher une section « Special Terms » lorsque (amount > 50 000 OU customer type equals « Enterprise ») ET region n’est pas vide. Vous définiriez la propriété logic du ConditionSet sur and avec deux groupes. Le premier groupe contient deux conditions (amount et customer type), qui sont automatiquement combinées avec or parce que le parent utilise and. Le second groupe contient la condition unique de la région. 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 le document. Ce n’est pas facultatif, et ce n’est pas quelque chose qui peut être contourné par une altération côté client.
Si un champ est obligatoire de manière conditionnelle et que la condition est évaluée à true 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 à false, le champ est masqué et entièrement ignoré pendant la validation. Aucun cas limite, aucune condition de concurrence entre votre interface et le backend.
Pour les flux de travail de conformité, c’est important. Les conditions que vous définissez dans l’API sont celles qui sont appliquées, point final. Votre interface côté client peut afficher en temps réel les états de visibilité et d’obligation pour offrir une bonne expérience au 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èle intégré, l’éditeur de demande de signature intégré, et l’API REST complète pour les modèles comme pour les demandes de signature.
Les conditions configurées via l’API s’affichent et sont évaluées correctement dans toutes les interfaces, et les conditions configurées via les éditeurs sont entièrement accessibles via l’API. Il n’y a aucun écart de fonctionnalités entre les outils visuels et l’interface programmatique.
Pour commencer
Les champs conditionnels ont été publiés dans le cadre de Firma.dev API v1.10.0. Ils sont entièrement additifs, sans rupture de compatibilité. Les champs sans conditions continuent de fonctionner exactement comme auparavant, 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 l’historique des modifications de l’API pour la référence complète du schéma, et la documentation de l’API pour la spécification complète des champs.
Firma.dev facture 0,029 € par enveloppe sans minimum mensuel, sans frais par siège et sans engagement initial. Si vous construisez des workflows de signature qui doivent s’adapter aux entrées du signataire, les champs conditionnels vous permettent de déplacer cette logique là où elle doit se trouver : dans l’API, appliquée à chaque soumission.
Commencez gratuitement avec Firma.dev, sans carte de crédit requise.
Articles connexes
Notre plateforme est conçue pour permettre aux entreprises de toutes tailles de travailler plus intelligemment et d'atteindre leurs objectifs avec confiance.
