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. Esta es la versión con mayor densidad de funcionalidades hasta la fecha, incorporando cinco características adicionales sin ningún cambio que rompa la compatibilidad. Si estás en la v1.9.0, tu integración actual funciona sin modificaciones. Todo lo que se incluye aquí son nuevas capacidades, no trabajo de migración.

Esto es lo que incluye.

Novedades de la v1.10.0

Las cinco características son aditivas. Los nuevos campos tienen como valor predeterminado null o false. Sin eliminaciones en el esquema, sin cambios de comportamiento.

Lógica condicional de campos

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

La estructura es componible. Un ConditionSet contiene uno o más objetos ConditionGroup, y cada grupo contiene objetos Condition individuales. El operador logic a nivel de 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.

Aquí tienes un ejemplo práctico. Imagina que tienes un contrato de trabajo donde el campo para el nombre del cónyuge solo debe aparecer cuando el firmante marca una 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 omite la validación por completo. Cuando está marcada, aparece y puede configurarse como obligatorio mediante una regla required_conditions independiente utilizando la misma estructura.

Algunos casos de uso que esto permite de forma directa:

• Campos de declaración condicionales que solo aparecen cuando un firmante selecciona una opción específica

• Secciones de aprobación dependientes donde se muestran campos de firma adicionales según un importe monetario o nivel de riesgo

• Formularios progresivos que se adaptan a medida que el firmante completa la información, manteniendo limpia la vista inicial

El detalle clave para integraciones con requisitos estrictos de cumplimiento: las condiciones se aplican en el servidor en el momento del envío. Un firmante no puede eludir las reglas de visibilidad o de obligatoriedad mediante manipulaciones en el cliente. Si un campo debe ser obligatorio según el valor de otro campo, Firma.dev lo valida en el servidor antes de aceptar el documento firmado.

Compatibilidad con documentos DOCX

Todos los endpoints de subida de documentos ahora aceptan archivos .docx junto con PDF. Al subir un documento de Word, Firma.dev lo convierte automáticamente a PDF en el servidor. Sin preprocesamiento en el cliente, sin dependencias adicionales en tu pipeline.

Esto aplica a la creación de plantillas, reemplazo de documentos de plantilla, creación de solicitudes de firma y a 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 estás subiendo archivos PDF, nada cambia. Esto simplemente elimina el paso de conversión para los equipos que redactan documentos en Word.

Endpoint de registro de auditoría

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

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

Este endpoint cubre la solicitud de cumplimiento más común: generar un paquete de evidencias que muestre con exactitud quién hizo qué, cuándo y desde dónde. Ya sea que lo necesites para registros de auditoría interna, informes regulatorios o feeds de actividad para los clientes, todos los datos están en una sola llamada.

Para consultar el esquema de respuesta completo y los detalles del endpoint, consulta la referencia de la API del registro de auditoría.

Control del marco de firma

De forma predeterminada, los PDF completados incluyen un borde visual alrededor de cada firma con un ID de firma. La nueva configuración show_signature_frame te permite controlar esto en tres niveles con una jerarquía de herencia limpia:

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

2. Espacio de trabajo anula a la Empresa (null hereda)

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

Para deshabilitar el marco a nivel de 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 estás integrando Firma.dev en tu propio producto y deseas firmas limpias sin ningún marco de Firma.dev en el documento final, establece esto en false a nivel de espacio de trabajo y cada solicitud de firma en ese espacio lo heredará. Por el contrario, los sectores regulados que requieren identificadores de firma visibles pueden mantenerlo explícitamente habilitado.

Forzar eliminación de condiciones al eliminar usuarios

Esta es una mejora en la ergonomía para desarrolladores. Cuando eliminas a un destinatario cuyos campos están referenciados en las condiciones de otros campos (de la lógica condicional descrita anteriormente), la API antes no tenía 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 continúa con la eliminación

Esto es importante cuando gestionas destinatarios de forma programática en flujos de trabajo dinámicos. Sin force_remove_conditions, eliminar a un destinatario cuyos campos alimentan condiciones en otros campos te exigiría limpiar manualmente cada referencia de condición primero.

Resumen técnico

Nuevos esquemas: ConditionSet, ConditionGroup, Condition

Actualizar desde la v1.9.0

Sin cambios disruptivos. Sin eliminaciones de campos. Sin cambios de comportamiento. Los nuevos campos tienen como valor predeterminado null o false, por lo que las integraciones existentes requieren cero modificaciones. Si vienes de una versión anterior, lo mismo se aplica a cada versión lanzada desde la v1.0.0. Consulta el registro de cambios completo de la API para ver el historial completo de versiones.

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

Primeros pasos

¿Nuevo en Firma.dev? Modelo de pago por uso: tarifas a 0,049 € por sobre, sin contratos ni consumos mínimos. Empieza a usar Firma.dev gratis, sin necesidad de tarjeta de crédito.

Obtener clave API

Para consultar la referencia completa de la API, visita la documentación de Firma.dev.