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 enviado tres lanzamientos de API desde v1.5, y los tres son mejoras directas que no rompen la compatibilidad. 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 función más solicitada en v1.6 son las descargas de PDF divididas. Anteriormente, cuando se completaba una solicitud de firma, obtenías un único PDF combinado que incluía tanto el documento firmado como el certificado de la 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 URL están firmadas previamente y expiran después de 1 hora. Si necesitas un enlace nuevo, simplemente vuelve a obtener la solicitud de firma. Esto es particularmente útil si necesitas almacenar el documento firmado en un sistema y la auditoría en otro, o si tus usuarios finales solo necesitan el PDF firmado limpio sin las páginas de certificación adjuntas.

v1.6 también limpió la nomenclatura de 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

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 escrita o generada por fuente. v1.7 introduce la configuración hand_drawn_only para imponer precisamente eso.

Agrégalo a los ajustes 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 por completo las opciones de firma escrita y basada en fuentes. Los firmantes deben dibujar su firma a mano. Esto es útil para industrias con mucha regulación como la atención médica y los servicios financieros donde los reguladores o auditores esperan específicamente firmas manuscritas.

La configuración predeterminada 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 compatiblemente retroactivos al esquema SigningRequest. Estas 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 nuevo, quédate con el objeto settings. Los campos heredados están ahí para equipos que migran desde sistemas más antiguos.

Registro completo de cambios de v1.7

v1.8.0: API de Plantillas de Email 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 Email, 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 sobrescriben las plantillas a nivel de empresa, que sobrescriben los valores predeterminados integrados. Esto significa que puedes establecer una plantilla a nivel de empresa y luego personalizarla por Espacio de Trabajo del Cliente para escenarios de marca blanca donde cada uno de tus clientes necesita sus propios correos electrónicos de marca.

Junto con las plantillas personalizadas, v1.8 agrega un campo language tanto a Company como a WorkspaceSettings. Configúralo a uno de los siete idiomas compatibles (en, es, it, pt, fr, de, el) y las plantillas de correo electrónico integradas de Firma.dev usarán ese idioma automáticamente. Combinado con las anulaciones a nivel de espacio de trabajo, puedes servir a mercados internacionales sin gestionar una infraestructura de correos electrónicos separada.

Mejoras de Esquema

v1.8 también envió varias mejoras de esquema que vale 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 obtener una imagen completa de la configuración de una plantilla.

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

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

Ten en cuenta que v1.8 también corrigió varios nombres de campos en el esquema 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 seguramente hace), no se necesitan cambios.

Registro completo de cambios de v1.8

Actualización

Los tres lanzamientos son totalmente compatibles hacia atrás. No hay cambios disruptivos ni 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 el registro completo de cambios con cada cambio de esquema y nota de migración, consulta el Registro de Cambios de API en la documentación. Si recién comienzas con Firma.dev, puedes obtener tu clave de API de forma gratuita y comenzar a construir hoy mismo.

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