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

Firma.dev API v1.10.0 está en vivo. Esta es la versión con más características hasta la fecha, enviando cinco características aditivas con cero cambios rompecompatibilidad. Si estás en v1.9.0, tu integración existente funciona sin modificaciones. Todo aquí es nueva capacidad, no trabajo de migración.

Esto es lo que hay en la caja.

Qué hay en v1.10.0

Las cinco características son aditivas. Los nuevos campos por defecto son null o false. No hay eliminaciones de esquemas, no hay cambios de comportamiento.

Lógica de campo condicional

Esta es la característica principal. Los campos ahora pueden tener required_conditions y visibility_conditions dinámicos que se evalúan basados en otros valores de campo al momento de la firma. En lugar de construir lógica de formulario condicional en tu propia UI, defines las reglas una vez en la API y Firma.dev maneja la evaluación tanto del lado del cliente como del servidor.

La estructura es componible. Un ConditionSet contiene uno o más objetos ConditionGroup, y cada grupo contiene objetos Condition individuales. El operador logic en el 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 disponibles diez operadores de comparación: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal y less_than_or_equal.

Aquí hay un ejemplo práctico. Supongamos que tienes un contrato de trabajo donde un campo de nombre de cónyuge solo debe aparecer cuando el firmante marca una casilla de verificación "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 de nombre del cónyuge permanece oculto y omite la validación por completo. Cuando está marcada, aparece y puede establecerse como obligatorio a través de una regla required_conditions separada utilizando la misma estructura.

Unos pocos casos de uso que esto desbloquea directamente:

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

• Secciones de aprobación dependientes donde aparecen campos de aprobación adicionales basados en un monto en dólares o nivel de riesgo

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

El detalle clave para integraciones sensibles al cumplimiento: las condiciones se aplican del lado del servidor al enviar. Un firmante no puede evadir la visibilidad o las reglas obligatorias mediante manipulación del lado del cliente. Si un campo debe ser obligatorio basado en el valor de otro campo, Firma.dev valida eso del lado del servidor antes de aceptar el documento firmado.

Soporte de documentos DOCX

Todos los puntos de acceso de subida de documentos ahora aceptan archivos .docx junto con PDF. Cuando subes un documento de Word, Firma.dev lo convierte automáticamente a PDF del lado del servidor. Sin preprocesamiento del lado del cliente, sin dependencias extra en tu flujo de trabajo.

Esto se aplica a la creación de plantillas, reemplazo de documentos de plantilla, creación de solicitud 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 estás subiendo PDFs, nada cambia. Esto solo elimina el paso de conversión para equipos que crean documentos en Word.

Punto de acceso de historial de auditoría

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

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

Este punto de acceso cubre la pregunta de cumplimiento más común: producir un paquete de evidencia que muestre exactamente quién hizo qué, cuándo y desde dónde. Ya sea que lo necesites para registros de auditoría internos, informes reglamentarios o feeds de actividad para clientes, los datos están todos en una llamada.

Para el esquema de respuesta completo y los detalles del punto de acceso, consulta la referencia de API de historial de auditoría.

Control del marco de firma

Por defecto, los PDFs completados incluyen un borde visual alrededor de cada firma con una ID de firma. La nueva configuración show_signature_frame te permite controlar esto en tres niveles con una cadena de herencia limpia:

1. Compañía establece el predeterminado (habilitado por defecto)

2. Espacio de trabajo anula a Compañía (null hereda)

3. Solicitud de firma anula a 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 caso de uso principal aquí es la marca blanca. Si estás integrando Firma.dev en tu propio producto y deseas firmas limpias sin ningún encuadre de Firma.dev en el documento final, establece esto en false al nivel de espacio de trabajo y cada solicitud de firma en ese espacio de trabajo lo hereda. Por el contrario, las industrias reguladas que requieren identificadores de firma visibles pueden mantenerlo habilitado explícitamente.

Eliminar condiciones forzadamente al eliminar usuario

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

• false (por defecto): La solicitud es rechazada con un error que lista los campos dependientes

• true: Elimina automáticamente las referencias de condiciones y procede con la eliminación

Esto importa cuando estás gestionando destinatarios programáticamente en flujos de trabajo dinámicos. Sin force_remove_conditions, eliminar un destinatario cuyos campos alimentan condiciones en otros campos requeriría que limpiaras manualmente cada referencia de condición primero.

Resumen técnico

Nuevos esquemas: ConditionSet, ConditionGroup, Condition

Actualizando desde v1.9.0

No hay cambios rompecompatibilidad. No hay eliminaciones de campos. No hay cambios de comportamiento. Los nuevos campos por defecto son null o false, por lo que las integraciones existentes no requieren modificaciones. Si vienes de una versión anterior, lo mismo se aplica a cada versión desde v1.0.0. Consulta el historial de cambios completo de la API para el historial de versiones completo.

Para detalles sobre v1.9.0 (verificación OTP, reemplazo de documento de plantilla), consulta la sección de historial de cambios de v1.9.0.

Comienza ahora

¿Nuevo en Firma.dev? Precios pay-as-you-go a $0.029 por sobre, sin contratos ni mínimos. Comienza con Firma.dev gratis, sin necesidad de tarjeta de crédito.

Obtener clave API

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