Firma.dev API v1.10.0: Campos Condicionales, Soporte DOCX, Registro de Auditoría, y Más

La API v1.10.0 de Firma.dev ya está disponible. Se trata de la versión con mayor densidad de funciones hasta la fecha, con cinco funciones adicionales y cero cambios incompatibles. Si utilizas la v1.9.0, tu integración actual funcionará sin modificaciones. Todo lo que te presentamos es nueva capacidad, no trabajo de migración.

Esto es lo que incluye el paquete.

Qué incluye la v1.10.0

Las cinco funciones se suman a las existentes. El valor predeterminado para los nuevos campos es null o false. No hay eliminación de esquemas ni cambios de comportamiento.

Lógica condicional de campos

Esta es la función estrella. Ahora los campos pueden tener reglas dinámicas required_conditions y visibility_conditions que se evalúan en función del valor de otros campos en el momento de la firma. En lugar de crear una lógica de formulario condicional en tu propia interfaz de usuario, defines las reglas una vez en la API y Firma.dev se encarga de evaluarlas tanto en el cliente como en el servidor.

La estructura es modular. Un ConditionSet contiene uno o varios objetos ConditionGroup, y cada grupo contiene objetos Condition individuales. El operador logic en el nivel del conjunto (and u or) controla cómo se relacionan los grupos entre sí, mientras que las condiciones dentro de un grupo utilizan el operador opuesto.

Hay diez operadores de comparación disponibles: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal y less_than_or_equal.

He aquí un ejemplo práctico. Supongamos que tienes un contrato de trabajo en el que el campo del nombre del cónyuge solo debe aparecer cuando el firmante marca la casilla "Casado":

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

{
  "visibility_conditions": {
    "logic": "and",
    "groups": [
      {
        "conditions": [
          {
            "field_id": "married-checkbox-field-id",
            "operator": "equals",
            "value": "true"
          }
        ]
      }
    ]
  }
}

Cuando la casilla está desmarcada, el campo del nombre del cónyuge permanece oculto y se omite por completo la validación. Cuando se marca, aparece y se puede definir como obligatorio mediante una regla required_conditions independiente que utiliza la misma estructura.

Algunos de los casos de uso que esto permite resolver directamente:

• Campos de declaración confidencial condicionales que aparecen únicamente cuando el firmante selecciona una opción específica

• Secciones de aprobación dependientes en las que aparecen campos de aprobación adicionales en función de un importe en dólares o de un nivel de riesgo

• Formularios progresivos que se adaptan a medida que el firmante introduce información, lo que mantiene limpia la vista inicial

El detalle clave para las integraciones sensibles al cumplimiento: las condiciones se aplican en el servidor en el momento del envío. El firmante no puede eludir las reglas de visibilidad u obligatoriedad mediante alteraciones en el lado del cliente. Si un campo deba ser obligatorio en función del valor de otro campo, Firma.dev lo valida en el servidor antes de aceptar el documento firmado.

Compatibilidad con documentos DOCX

Todos los puntos de conexión para la subida de documentos aceptan ahora archivos .docx además de PDF. Al subir un documento de Word, Firma.dev lo convierte automáticamente a PDF en el servidor. Sin procesamiento previo en el lado del cliente ni dependencias adicionales en tus procesos.

Esto se aplica a la creación de plantillas, la sustitución de documentos de plantilla, la creación de solicitudes de firma y todas las operaciones de actualización PUT/PATCH.

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

curl -X POST https://api.firma.dev/v1.10.0/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Agreement",
    "document": "BASE64_ENCODED_DOCX_CONTENT"
  }'

Las integraciones de PDF existentes no se ven afectadas en absoluto. Si ya subes documentos PDF, nada cambia. Esto simplemente elimina el paso de conversión para los equipos que redactan documentos en Word.

Punto de conexión de pista de auditoría

Un nuevo punto de conexión GET /signing-requests/{id}/audit devuelve el registro cronológico completo de eventos para cualquier solicitud de firma. Combina en una única línea de tiempo las acciones de administración (creado, editado, enviado, cancelado) y las acciones del firmante (visto, firmado, rechazado, descargado).

Cada evento incluye una marca de tiempo, origen (admin o signer), tipo de evento, identidad del actor, dirección IP (para eventos de firmantes) y metadatos específicos del evento.

Este punto de conexión cubre el requisito de cumplimiento más habitual: generar un paquete de pruebas que muestre exactamente quién hizo qué, cuándo y desde dónde. Tanto si lo necesitas para registros de auditoría interna, informes regulatorios o canales de actividad orientados al cliente, dispones de todos los datos en una sola llamada.

Para ver el esquema completo de la respuesta y los detalles del punto de conexión, consulta la referencia de la API de pista de auditoría.

Control del marco de firma

De forma predeterminada, los PDF finalizados incluyen un borde visual alrededor de cada firma con un Id. de firma. El nuevo parámetro show_signature_frame te permite controlar esto en tres niveles con una cadena de herencia clara:

1. Empresa establece el valor predeterminado (activado por defecto)

2. Espacio de trabajo anula el nivel de Empresa (null hereda)

3. Solicitud de firma anula el nivel de Espacio de trabajo (null hereda)

Para desactivar el marco en el nivel del espacio de trabajo:

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

PATCH /workspace-settings/{workspace_id}
{
  "settings": {
    "show_signature_frame": false
  }
}

El principal caso de uso aquí es la marca blanca. Si integras Firma.dev en tu propio producto y deseas obtener firmas limpias sin ningún marco de Firma.dev en el documento final, establece este valor en false en el nivel del espacio de trabajo y se heredará en cada solicitud de firma de ese espacio de trabajo. Por el contrario, los sectores regulados que requieran identificadores de firma visibles pueden mantenerlo activado de forma explícita.

Forzar la eliminación de condiciones al eliminar usuarios

Esta mejora facilita el trabajo de los desarrolladores. Al eliminar a un destinatario cuyos campos se referencian en condiciones de otros campos (de la lógica condicional descrita anteriormente), la API no tenía antes forma de gestionar la dependencia. Ahora, el parámetro force_remove_conditions controla este comportamiento:

• false (predeterminado): la solicitud se rechaza con un error que enumera los campos dependientes.

• true: elimina automáticamente las referencias a la condición y procede con la eliminación.

Esto es relevante al gestionar destinatarios mediante programación en flujos de trabajo dinámicos. Sin la opción force_remove_conditions, eliminar a un destinatario cuyos campos alimentan condiciones en otros campos te exigiría limpiar manualmente cada referencia de condición en primer lugar.

Resumen técnico

Nuevos esquemas: ConditionSet, ConditionGroup, Condition

Actualización desde la v1.9.0

Sin cambios incompatibles. Sin eliminación de campos. Sin cambios de comportamiento. El valor predeterminado de los nuevos campos es null o false, por lo que las integraciones existentes no requieren ninguna modificación. Si procedes de una versión anterior, lo mismo se aplica a cada lanzamiento desde la v1.0.0. Consulta el historial de cambios completo de la API para conocer el historial de versiones completo.

Para obtener más detalles sobre la v1.9.0 (verificación OTP, sustitución de documentos de plantilla), consulta la sección del historial de cambios de la v1.9.0.

Primeros pasos

¿Es la primera vez que utilizas Firma.dev? Modelo de pago por uso: precio de 0,049 $ por sobre, sin contratos ni mínimos. Empieza a utilizar Firma.dev gratis, sin tarjeta de crédito.

Obtener clave API

Para obtener la referencia de la API completa, consulta la documentación de Firma.dev.