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 debe aparecer cuando alguien selecciona "Casado." Sección de divulgación adicional debe ser requerida cuando una transacción excede cierta cantidad en dólares. Un bloque de dirección de envío solo importa cuando el firmante marca "Enviar a una dirección diferente."

Sin campos condicionales, estás construyendo toda esa lógica en tu propia capa de interfaz de usuario. Estás gestionando los conmutadores de visibilidad, las reglas de validación y los casos límite del lado del cliente, y esperando que nada sea omitido. Funciona hasta que no funciona.

La API de Firma.dev ahora admite campos condicionales nativamente. Definas las reglas en tu esquema de campo, y la API maneja la visibilidad, el estado requerido y el cumplimiento del lado del servidor en el envío. No se necesita lógica de interfaz de usuario personalizada.

Dos tipos de condiciones

Cada objeto de campo en la API de Firma.dev ahora acepta dos nuevas propiedades que pueden ser nulas: required_conditions y visibility_conditions.

required_conditions anula la bandera estática required en un campo. Cuando configuras required_conditions, el campo se vuelve obligatorio solo cuando las condiciones se evalúan como verdaderas basándose en otros valores de campo al momento del envío. Si las condiciones se evalúan como falsas, el campo es opcional, independientemente de lo que diga la bandera required.

visibility_conditions controla si el firmante ve el campo o no. Cuando se establece, el campo permanece oculto a menos que las condiciones se evalúen como verdaderas. Los campos ocultos se omiten completamente durante la validación, por lo que no recibirás errores en campos que el firmante nunca vio.

Ambas propiedades pueden ser nulas. Cuando se dejan como null (el valor por defecto), el campo se comporta exactamente como lo hacía antes: la bandera estática required determina si es necesario y el campo siempre es visible. Las integraciones existentes no necesitan ningún cambio.

El esquema de condición

Las condiciones usan una estructura anidada de tres niveles: ConditionSet, ConditionGroup, y Condition. Esta es la parte que vale la pena entender cuidadosamente, porque es lo que te da lógica booleana composable sin árboles profundamente anidados.

ConditionSet es el contenedor de nivel superior. Tiene dos propiedades: un operador logic (ya sea and o or) y un array de groups (objetos ConditionGroup). El operador de lógica determina cómo se combinan los grupos. Si logic es and, todos los grupos deben evaluarse como verdaderos. Si logic es or, cualquier grupo único evaluado como verdadero es suficiente.

ConditionGroup contiene un array de conditions (objetos Condition individuales). Aquí está el detalle clave: las condiciones dentro de un grupo se combinan usando la lógica opuesta del ConditionSet padre. Si el ConditionSet usa and, las condiciones dentro de cada grupo se combinan con or. Si el 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. Te permite construir declaraciones como "(monto > 50000 O tipo de cliente igual a Enterprise) Y la región no está vacía" con solo dos grupos dentro de un ConditionSet and. El primer grupo contendría dos condiciones (monto y tipo de cliente, combinadas con or porque el padre es and), y el segundo grupo contendría una condición para la verificació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 la comparación.

Referencia de operadores

Firma.dev admite 10 operadores de comparación a través de campos condicionales:

is_filled verifica si un campo tiene algún valor. Ú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 de reserva cuando un campo principal se deja en blanco.

equals y not_equals realizan una coincidencia exacta de valores. Muestra campos de cónyuge cuando el estado civil es igual a "Casado", u oculta una sección cuando el país no es igual a "US".

contains y not_contains verifican los subcadenas. Podrías mostrar campos relacionados con el cumplimiento cuando un campo de descripción contiene "regulado", o saltar una sección cuando las notas no mencionan 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 que usarías cuando construyes lógica basada en umbrales, como requerir la aprobación del gerente cuando un monto excede 10,000 o aplicar términos simplificados cuando el valor de un contrato cae por debajo de un cierto número.

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 otro campo ha sido rellenado. La propiedad required_conditions toma un ConditionSet con lógica and, un solo grupo y una sola condición usando el operador 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"
          }
        ]
      }
    ]
  }
}

El field_id hace referencia al UUID del campo que estás evaluando. En este caso, siempre que ese campo referenciado tenga algún valor, el campo actual se vuelve obligatorio. Cuando está vacío, el campo vuelve a ser opcional.

Puedes construir sobre este patrón en varias direcciones. Para visibilidad condicional, usarías 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 una casilla de verificación "Casado" usaría visibility_conditions con una sola condición is_filled que apunta al UUID del campo de la casilla de verificación.

Para lógica de múltiples condiciones, agregas más grupos o más condiciones dentro de los grupos. Si necesitas que un campo de certificación de cumplimiento sea obligatorio solo cuando el monto de la transacción sea mayor que 10,000 Y el país sea igual a "US", crearías un ConditionSet con lógica and que contiene dos grupos, cada uno con una condición. El primer grupo verifica el monto con greater_than, el segundo verifica el país con equals.

El patrón más expresivo utiliza la regla de lógica opuesta. Imagina que quieres mostrar una sección de "Términos Especiales" cuando (monto > 50,000 O tipo de cliente igual a "Enterprise") Y la región no está vacía. Configurarías el logic del ConditionSet a and con dos grupos. El primer grupo contiene dos condiciones (monto y tipo de cliente), que se combinan automáticamente con or porque el padre usa and. El segundo grupo tiene la condición única de la región. El resultado es una estructura limpia y legible que de otro modo requeriría árboles booleanos anidados.

Cumplimiento del lado del servidor

Todas las condiciones se evalúan en el servidor cuando el firmante envía. Esto no es opcional y no es algo que se pueda omitir con manipulación del lado del cliente.

Si un campo es condicionalmente obligatorio y la condición se evalúa como verdadera al momento del envío, 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 completamente durante la validación. No hay casos límite, ni condiciones de carrera entre tu interfaz de usuario y el backend.

Para flujos de trabajo de cumplimiento, esto es importante. Las condiciones que defines en la API son las condiciones que se aplican, punto. Tu UI del lado del cliente puede renderizar los estados de visibilidad y requerimiento en tiempo real para una buena experiencia del firmante, pero la fuente de verdad reside en el lado del servidor.

Dónde funcionan las condiciones

Los campos condicionales están disponibles en todas las superficies 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 incrustado, el editor de solicitudes de firma incrustado y la API REST completa para ambas plantillas y solicitudes de firma.

Las condiciones establecidas a través de la API aparecen y se evalúan correctamente en todas las superficies de la interfaz de usuario, y las condiciones configuradas a través de los editores son completamente accesibles a través de la API. No hay brecha de características entre las herramientas visuales y la interfaz programática.

Comenzando

Los campos condicionales se lanzaron como parte de la API v1.10.0 de Firma.dev. Son completamente aditivos sin cambios disruptivos. Los campos sin condiciones continúan funcionando exactamente como antes, y las integraciones existentes no requieren modificaciones.

Puedes comenzar a usar required_conditions y visibility_conditions en cualquier objeto de campo hoy. Consulta el registro de cambios de la API para la referencia completa del esquema, y los documentos de la API para la especificación completa del campo.

Firma.dev cobra €0.029 por sobre sin mínimos mensuales, sin tarifas por asiento y sin compromisos previos. Si estás construyendo flujos de trabajo de firma que necesitan adaptarse en función de la entrada del firmante, los campos condicionales te permiten mover esa lógica donde pertenece: en la API, aplicada en cada envío.

Comienza con Firma.dev gratis, sin necesidad de tarjeta de crédito.