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 más rica en funcionalidades hasta la fecha, con cinco funciones aditivas y cero cambios incompatibles. Si estás en v1.9.0, tu integración existente funciona sin modificación. Todo lo que hay aquí es nueva capacidad, no trabajo de migración.

Esto es lo que trae esta versión.

Qué incluye v1.10.0

Las cinco funcionalidades son aditivas. Los nuevos campos tienen por defecto null o false. No se elimina ningún esquema, no hay cambios de comportamiento.

Lógica condicional de campos

Esta es la funcionalidad estrella. Los campos ahora pueden tener required_conditions y visibility_conditions dinámicos que se evalúan según los valores de otros campos en el momento de la firma. En lugar de construir la lógica de formularios condicionales en tu propia interfaz, defines las reglas una sola 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 o or) controla cómo se relacionan los grupos entre sí, mientras que las condiciones dentro de un grupo usan 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 laboral en el que un campo para el nombre del cónyuge solo debería 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 no está marcada, el campo del nombre del cónyuge permanece oculto y omite por completo la validación. Cuando está marcada, aparece y puede establecerse como obligatorio mediante una regla separada de required_conditions usando la misma estructura.

Algunos casos de uso que esto habilita directamente:

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

• Secciones de aprobación dependientes donde aparecen campos adicionales de validación según un importe en dólares o un 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 sensibles al cumplimiento normativo: las condiciones se aplican en el servidor al enviar. Un firmante no puede eludir las reglas de visibilidad o de obligatoriedad mediante manipulación del lado del cliente. Si un campo debe 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 endpoints de subida de documentos ahora aceptan archivos .docx además de PDF. Cuando subes un documento de Word, Firma.dev lo convierte automáticamente a PDF en el servidor. Sin preprocesado del lado del cliente, sin dependencias adicionales en tu pipeline.

Esto se aplica a la creación de plantillas, a la sustitución de documentos de plantilla, a la 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 existentes con PDF no se ven afectadas en absoluto. Si ya estás subiendo PDF, no cambia nada. 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 de cualquier solicitud de firma. Combina tanto las acciones de administración (creada, editada, enviada, cancelada) como las acciones del firmante (vista, firmada, rechazada, descargada) en una sola línea de tiempo.

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

Este endpoint cubre la petición de cumplimiento normativo más habitual: generar un paquete de evidencias que muestre exactamente quién hizo qué, cuándo y desde dónde. Tanto si lo necesitas para registros de auditoría internos, informes regulatorios o feeds de actividad orientados al cliente, los datos están todos en una sola llamada.

Para ver el esquema completo de respuesta y los detalles del endpoint, consulta la referencia de la API de 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 cadena de herencia clara:

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

2. Espacio de trabajo sobrescribe Empresa (null se hereda)

3. Solicitud de firma sobrescribe Espacio de trabajo (null se hereda)

Para desactivar 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 marca blanca. Si estás integrando Firma.dev en tu propio producto y quieres firmas limpias sin ningún marco de Firma.dev en el documento final, establece esto en false a nivel de espacio de trabajo y todas las solicitudes de firma de ese espacio de trabajo lo heredarán. Por el contrario, las industrias reguladas que requieren identificadores de firma visibles pueden mantenerlo activado explícitamente.

Forzar eliminación de condiciones al eliminar usuarios

Esta es una mejora en la ergonomía para desarrolladores. Cuando eliminas un destinatario cuyos campos están referenciados en las condiciones de otros campos (de la lógica condicional anterior), la API antes no tenía forma de gestionar la dependencia. Ahora, el parámetro force_remove_conditions controla el comportamiento:

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

• true: elimina automáticamente las referencias de condiciones y continúa con la eliminación

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

Resumen técnico

Nuevos esquemas: ConditionSet, ConditionGroup, Condition

Actualización desde v1.9.0

No hay cambios incompatibles. No se eliminan campos. No hay cambios de comportamiento. Los nuevos campos tienen por defecto null o false, así que las integraciones existentes no requieren ninguna modificación. Si vienes de una versión anterior, lo mismo se aplica a todas las versiones desde v1.0.0. Consulta el registro de cambios completo de la API para ver el historial completo de versiones.

Para ver los detalles de v1.9.0 (verificación OTP, sustitución de documentos de plantilla), consulta la sección del registro de cambios de v1.9.0.

Empezar

¿Eres nuevo en Firma.dev? Precios de pago por uso a $0.029 por sobre, sin contratos ni mínimos. Empieza con Firma.dev gratis, sin necesidad de tarjeta de crédito.

Obtener clave API

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