Firma.dev API v1.6, v1.7, y v1.8: División de PDFs, Firmas a Mano Alzada, y Plantillas de Correo Electrónico Personalizadas

Se han lanzado tres versiones de la API desde v1.5, y las tres son mejoras no disruptivas. Aquí está lo nuevo y cómo usarlo.

v1.6.0: Descargas de PDF Divididas y Limpieza de Tipos de Campo

Lanzado el 12 de febrero de 2026

La característica más solicitada en v1.6 es la división de descargas de PDF. Anteriormente, cuando se completaba una solicitud de firma, se obtenía un único PDF combinado que incluía tanto el documento firmado como el certificado de auditoría. Ahora puedes descargarlos por separado.

Dos nuevos campos están disponibles en las solicitudes de firma completadas:

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

{
  "document_only_download_url": "https://storage.example.com/document.pdf",
  "certificate_only_download_url": "https://storage.example.com/certificate.pdf"
}

Ambas URLs están prefirmadas y expiran después de 1 hora. Si necesitas un enlace nuevo, simplemente recupera la solicitud de firma nuevamente. Esto es particularmente útil si necesitas almacenar el documento firmado en un sistema y el rastro de auditoría en otro, o si tus usuarios finales solo necesitan el PDF firmado limpio sin las páginas del certificado adjuntas.

v1.6 también limpió los nombres de tipo de campo. La API ahora acepta tanto initials como initial, así como textarea y text_area, y los normaliza automáticamente. Si tu integración ya usaba los nombres originales, no habrá problemas. Si prefieres las formas normalizadas, también funcionan.

Registro de cambios completo de v1.6

v1.7.0: Firmas a Mano Alzada

Lanzado el 27 de febrero de 2026

Algunos flujos de trabajo requieren que los firmantes dibujen físicamente su firma en lugar de seleccionar una opción tipográfica o generada por fuente. v1.7 introduce la configuración hand_drawn_only para imponer exactamente eso.

Añádelo a la configuración de tu solicitud de firma:

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

{
  "settings": {
    "hand_drawn_only": true,
    "use_signing_order": false,
    "allow_download": true
  }
}

Cuando está habilitado, la interfaz de firma elimina las opciones de firma tipográficas y basadas en fuentes por completo. Los firmantes deben dibujar su firma a mano. Esto es útil para industrias con mucho cumplimiento como la salud y los servicios financieros, donde los reguladores o auditores esperan específicamente firmas manuscritas.

La configuración por defecto es false, por lo que las solicitudes de firma existentes no se ven afectadas.

Este lanzamiento también añadió campos de configuración heredados retrocompatibles al esquema SigningRequest. Estos son versiones basadas en enteros (0/1) de las configuraciones booleanas, diseñadas para integraciones más antiguas que esperan ese formato. Si estás construyendo algo nuevo, quédate con el objeto settings. Los campos heredados están ahí para los equipos que migran desde sistemas antiguos.

Registro de cambios completo de v1.7

v1.8.0: API de Plantillas de Correo Electrónico y Soporte de Idiomas

Lanzado el 3 de marzo de 2026

v1.8 es el más grande de los tres. La característica principal es la API de Plantillas de Correo Electrónico, que te da control total sobre los correos de notificación que Firma.dev envía durante el proceso de firma.

Puedes personalizar plantillas para cinco tipos de correos: signing_invite, next_signer, signing_expired, signing_cancelled, y signing_declined. Las plantillas soportan cuerpos HTML con marcadores de posición como {{signer_name}}, {{document_name}}, y {{signing_link}}.

Aquí tienes un ejemplo rápido:

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

PUT /workspace/{workspace_id}/email-templates/signing_invite
{
  "subject": "Please sign: {{document_name}}",
  "body": "<p>Hi {{signer_name}},</p><p>Please review and sign using this link: {{signing_link}}</p>"
}

Las plantillas siguen una jerarquía: las plantillas a nivel de espacio de trabajo sobrescriben las plantillas a nivel de empresa, que sobrescriben los valores predeterminados incorporados. Esto significa que puedes establecer una plantilla a nivel de empresa y luego personalizarla por Espacio de Cliente para escenarios de marca blanca donde cada uno de tus clientes necesita sus propios correos electrónicos personalizados.

Junto con las plantillas personalizadas, v1.8 añade un campo language tanto a Company como a WorkspaceSettings. Establécelo en uno de los siete idiomas soportados (es, es, it, pt, fr, de, el) y las plantillas de correo electrónico incorporadas de Firma.dev usarán ese idioma automáticamente. Combinado con las anulaciones a nivel de espacio de trabajo, puedes atender a mercados internacionales sin necesitar gestionar una infraestructura de correo electrónico separada.

Mejoras del Esquema

v1.8 también lanzó varias mejoras de esquema que vale la pena conocer:

El esquema Template ahora incluye en línea recipients, fields, settings, page_count, y expiration_hours cuando obtienes una plantilla individual. Esto significa menos llamadas a la API para obtener una imagen completa de la configuración de una plantilla.

Las respuestas de solicitud de firma se han dividido en formas específicas de endpoint (SigningRequestListItem, SigningRequestCreateResponse, SigningRequestDetail) con datos en línea y campos de marcas de tiempo estandarizados. Esto hace que las respuestas sean más predecibles y fáciles de tipar en tu base de código.

Los webhooks ganaron tres campos nuevos: description, consecutive_failures, y auto_disabled_at. Los campos de seguimiento de fallos son particularmente útiles para monitoreo. Si un webhook comienza a fallar, ahora puedes ver cuántas fallas consecutivas han ocurrido y si Firma.dev lo desactivó automáticamente.

Nota que v1.8 también corrigió varios nombres de campo en la especificación OpenAPI para que coincidan con las respuestas reales de la API. Si tu integración ya maneja los campos de respuesta reales (lo cual casi seguro hace), no se necesitan cambios.

Registro de cambios completo de v1.8

Actualizando

Los tres lanzamientos son completamente compatibles hacia atrás. No hay cambios disruptivos, no se requieren pasos de migración. Puedes actualizar tu versión de la API de v1.5 directamente a v1.8 y todo seguirá funcionando como antes, con las nuevas características disponibles de inmediato.

Para el registro completo con todos los cambios de esquema y notas de migración, revisa el Registro de Cambios de la API en los documentos. Si recién estás comenzando con Firma.dev, puedes obtener tu clave API gratis y comenzar a construir hoy.

Notas de lanzamientos anteriores: v1.5 | v1.3 y v1.4