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

Se han publicado tres versiones de la API desde v1.5, y las tres son actualizaciones directas compatibles con versiones anteriores. Aquí está lo nuevo y cómo usarlo.

v1.6.0: Descargas de PDF divididas y limpieza de tipos de campo

Publicado el 12 de febrero de 2026

La función más solicitada en v1.6 son las descargas de PDF divididas. Antes, cuando se completaba una solicitud de firma, recibías un único PDF combinado que incluía tanto el documento firmado como el certificado del registro de auditoría. Ahora puedes descargarlos por separado.

Hay dos nuevos campos 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 URL están firmadas previamente y caducan después de 1 hora. Si necesitas un enlace nuevo, solo vuelve a obtener la solicitud de firma. Esto es especialmente útil si necesitas almacenar el documento firmado en un sistema y el registro de auditoría en otro, o si tus usuarios finales solo necesitan el PDF firmado limpio sin las páginas del certificado añadidas.

v1.6 también limpió la nomenclatura de los tipos 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 se rompe nada. Si prefieres las formas normalizadas, también funcionan.

Registro completo de cambios de v1.6

v1.7.0: Firmas dibujadas a mano

Publicado 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 mecanografiada 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á habilitada, la interfaz de firma elimina por completo las opciones de firma mecanografiada y basada en fuentes. Los firmantes deben dibujar su firma a mano. Esto es útil para sectores con fuerte carga de cumplimiento como el sanitario y los servicios financieros, donde los reguladores o auditores esperan específicamente firmas manuscritas.

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

Esta versión también añadió campos heredados de configuración compatibles con versiones anteriores al esquema SigningRequest. Son versiones basadas en enteros (0/1) de la configuración booleana, diseñadas para integraciones más antiguas que esperan ese formato. Si estás creando algo nuevo, usa el objeto settings. Los campos heredados están ahí para los equipos que migran desde sistemas más antiguos.

Registro completo de cambios de v1.7

v1.8.0: API de plantillas de correo electrónico y compatibilidad con idiomas

Publicado el 3 de marzo de 2026

v1.8 es la más grande de las tres. La función 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 correo electrónico: signing_invite, next_signer, signing_expired, signing_cancelled y signing_declined. Las plantillas admiten 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 reemplazan a las plantillas a nivel de empresa, que reemplazan a los valores predeterminados integrados. Esto significa que puedes establecer una plantilla para toda la empresa y luego personalizarla por Customer Workspace para escenarios de marca blanca en los que cada uno de tus clientes necesita sus propios correos con marca.

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

Mejoras de esquema

v1.8 también incluyó varias mejoras de esquema que conviene conocer:

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

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

Los webhooks incorporaron tres nuevos campos: description, consecutive_failures y auto_disabled_at. Los campos de seguimiento de fallos son especialmente útiles para la supervisión. Si un webhook empieza a fallar, ahora puedes ver cuántos fallos consecutivos se han producido y si Firma.dev lo deshabilitó automáticamente.

Ten en cuenta 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 reales de respuesta (que casi con total seguridad lo hace), no se necesita ningún cambio.

Registro completo de cambios de v1.8

Actualización

Las tres versiones son totalmente compatibles con versiones anteriores. Sin cambios rompientes, sin pasos de migración requeridos. Puedes actualizar tu versión de API de v1.5 directamente a v1.8 y todo seguirá funcionando como antes, con las nuevas funciones disponibles de inmediato.

Para ver el registro completo de cambios con cada modificación de esquema y nota de migración, consulta el Registro de cambios de la API en la documentación. Si acabas de empezar con Firma.dev, puedes obtener tu clave de API gratis y empezar a construir hoy mismo.

Notas de la versión anteriores: v1.5 | v1.3 y v1.4