Guías
Campos Condicionales: Construye Flujos de Firma Inteligentes y Ramificados a Través de la API
La mayoría de los documentos de firma no son estáticos. Un campo para el nombre del cónyuge solo debería aparecer cuando alguien selecciona "Casado". Una sección de divulgación adicional debería ser obligatoria cuando una transacción supera un determinado importe en dólares. Un bloque de dirección de envío solo es relevante cuando el firmante marca "Enviar a una dirección diferente".
Sin campos condicionales, tiene que crear toda esa lógica en su propia capa de interfaz de usuario. Estará gestionando alternancias de visibilidad, reglas de validación y casos extremos en el lado del cliente, esperando que nada se salte. Funciona hasta que deja de hacerlo.
La API de Firma.dev ahora admite campos condicionales de forma nativa. Define las reglas en el esquema de sus campos y la API se encarga de la visibilidad, el estado obligatorio y la aplicación en el lado del servidor al enviar. No se necesita lógica de interfaz de usuario personalizada.
Dos tipos de condiciones
Cada objeto de campo en la API de Firma.dev acepta ahora dos nuevas propiedades que admiten valores nulos: required_conditions y visibility_conditions.
required_conditions anula la bandera estática required en un campo. Al establecer required_conditions, el campo pasa a ser obligatorio solo cuando las condiciones se evalúan como verdaderas según los valores de otros campos en el momento del envío. Si las condiciones se evalúan como falsas, el campo es opcional, independientemente de lo que indique la bandera required.
visibility_conditions controla si el firmante ve el campo en absoluto. Cuando se establece, el campo permanece oculto a menos que las condiciones se evalúen como verdaderas. Los campos ocultos se omiten por completo durante la validación, por lo que no recibirá errores en los campos que el firmante nunca vio.
Ambas propiedades admiten valores nulos. Cuando se dejan como null (el valor por defecto), el campo se comporta exactamente igual que antes: la bandera estática required determina si es obligatorio y el campo está siempre visible. Las integraciones existentes no necesitan ningún cambio.
El esquema de condiciones
Las condiciones utilizan una estructura anidada de tres niveles: ConditionSet, ConditionGroup y Condition. Esta es la parte que vale la pena entender con cuidado, porque es lo que le brinda lógica booleana componible sin árboles profundamente anidados.
ConditionSet es el contenedor de nivel superior. Tiene dos propiedades: un operador logic (ya sea and u or) y una matriz de groups (objetos ConditionGroup). El operador lógico determina cómo se combinan los grupos. Si logic es and, todos los grupos deben evaluarse como verdaderos. Si logic es or, basta con que un solo grupo se evalúe como verdadero.
ConditionGroup contiene una matriz de conditions (objetos Condition individuales). Detalle clave: las condiciones dentro de un grupo se combinan usando la lógica opuesta de la ConditionSet principal. Si la ConditionSet usa and, las condiciones dentro de cada grupo se combinan con or. Si la ConditionSet usa or, las condiciones dentro de cada grupo usan and.
Este patrón de lógica opuesta es lo que hace que el esquema sea expresivo sin requerir una anidación profunda. Le permite construir declaraciones como "(importe > 50000 o tipo de cliente equivale a Empresa) y región no está vacío" con solo dos grupos dentro de un ConditionSet and. El primer grupo contendría dos condiciones (importe y tipo de cliente, combinadas con or porque el principal es and), y el segundo grupo contendría una condición para la comprobación de la región.
Condition es una evaluación única. Hace referencia a un field_id (el UUID de otro campo en el documento), un operator y un value opcional para comparar.
Referencia de operadores
Firma.dev admite 10 operadores de comparación en los campos condicionales:
is_filled comprueba si un campo tiene algún valor. Resulta útil para mostrar campos de seguimiento cuando un firmante comienza a rellenar una sección. is_empty es el inverso y funciona bien para requerir un campo alternativo cuando un campo principal se deja en blanco.
equals y not_equals realizan coincidencias exactas de valores. Muestre campos de cónyuge cuando el estado civil sea igual a "Casado" o oculte una sección cuando el país no sea igual a "US".
contains y not_contains buscan subcadenas. Podría mostrar campos relacionados con el cumplimiento normativo cuando un campo de descripción contenga "regulado" o saltarse una sección cuando las notas no mencionen una palabra clave específica.
greater_than, less_than, greater_than_or_equal y less_than_or_equal manejan comparaciones numéricas. Estos son los operadores a los que recurriría al diseñar lógica basada en umbrales, como requerir la aprobación del gerente cuando un importe supera los 10 000 o aplicar condiciones simplificadas cuando el valor de un contrato cae por debajo de cierta cantidad.
Cómo se ven las condiciones en la práctica
El registro de cambios de la API incluye un ejemplo del patrón condicional más simple: hacer que un campo sea obligatorio solo cuando se ha rellenado otro campo. La propiedad required_conditions toma un ConditionSet con lógica and, un único grupo y una única condición que utiliza el operador is_filled:
El field_id hace referencia al UUID del campo que está evaluando. En este caso, siempre que el campo referenciado tenga algún valor, el campo actual pasa a ser obligatorio. Cuando está vacío, el campo vuelve a ser opcional.
Puede ampliar este patrón en varias direcciones. Para la visibilidad condicional, utilizaría la misma estructura de ConditionSet bajo visibility_conditions en lugar de required_conditions. Un campo de texto "Nombre del cónyuge" que solo aparece cuando se marca la casilla "Casado" usaría visibility_conditions con una única condición is_filled que apunta al UUID de la casilla de verificación.
Para lógica de múltiples condiciones, añade más grupos o más condiciones dentro de los grupos. Si necesita que un campo de certificación de cumplimiento sea obligatorio solo cuando el importe de la transacción sea superior a 10 000 Y el país sea igual a "US", crearía un ConditionSet con lógica and que contenga dos grupos, cada uno con una condición. El primer grupo comprueba el importe con greater_than y el segundo comprueba el país con equals.
El patrón más expresivo utiliza la regla de lógica opuesta. Supongamos que desea mostrar una sección de "Condiciones especiales" cuando (importe > 50 000 o tipo de cliente es igual a "Empresa") y la región no está vacía. Establecería el operador logic de su ConditionSet en and con dos grupos. El primer grupo contiene dos condiciones (importe y tipo de cliente), que se combinan automáticamente con or porque el principal usa and. El segundo grupo alberga la única condición para la región. El resultado es una estructura limpia y legible que, de lo contrario, requeriría árboles booleanos anidados.
Aplicación en el lado del servidor
Todas las condiciones se evalúan en el lado del servidor cuando el firmante realiza el envío. Esto no es opcional y no es algo que pueda eludirse mediante manipulaciones en el lado del cliente.
Si un campo es condicionalmente obligatorio y la condición se evalúa como verdadera en el momento de la entrega, la API devuelve un error de validación cuando ese campo está vacío. Si las visibility_conditions de un campo se evalúan como falsas, el campo se oculta y se omite por completo durante la validación. Sin casos extremos, sin condiciones de carrera entre su interfaz de usuario y el backend.
Para los flujos de trabajo de cumplimiento normativo, esto es fundamental. Las condiciones que define en la API son las condiciones que se aplican, y punto. Su interfaz de usuario en el lado del cliente puede representar la visibilidad y los estados obligatorios en tiempo real para ofrecer una buena experiencia al firmante, pero la fuente de verdad siempre reside en el lado del servidor.
Dónde funcionan las condiciones
Los campos condicionales están disponibles en todas las interfaces de Firma.dev: la interfaz de usuario del editor de plantillas, la interfaz de usuario del editor de solicitudes de firma, el editor de plantillas integrado, el editor de solicitudes de firma integrado y la API REST completa tanto para plantillas como para solicitudes de firma.
Las condiciones configuradas a través de la API aparecen y se evalúan correctamente en todas las interfaces de usuario, y las condiciones configuradas a través de los editores son totalmente accesibles mediante la API. No existe ninguna brecha de funciones entre las herramientas visuales y la interfaz programática.
Primeros pasos
Los campos condicionales se lanzaron como parte de la versión v1.10.0 de la API de Firma.dev. Son totalmente aditivos y no introducen cambios incompatibles. Los campos sin condiciones siguen funcionando exactamente igual que antes, y las integraciones existentes no requieren ninguna modificación.
Puede empezar a usar required_conditions y visibility_conditions en cualquier objeto de campo hoy mismo. Consulte el registro de cambios de la API para ver la referencia completa de esquemas y la documentación de la API para la especificación completa de campos.
Firma.dev cobra 0,049 € por sobre sin mínimos mensuales, sin tarifas por usuario y sin compromisos iniciales. Si está creando flujos de trabajo de firma que deben adaptarse en función de las respuestas del firmante, los campos condicionales le permiten llevar esa lógica a donde corresponde: a la API, aplicada en cada envío.
Comience a usar Firma.dev de forma gratuita, sin necesidad de tarjeta de crédito.
Artículos relacionados
Nuestra plataforma está diseñada para capacitar a las empresas de todos los tamaños para trabajar de manera más inteligente y alcanzar sus objetivos con confianza.
