Firma.dev API v1.3 + v1.4: Nuevos Tipos de Campos, Dominios de Email Personalizados y Control Granular

Hemos lanzado dos versiones de la API de forma consecutiva, solo en la última semana. Nada que rompa la compatibilidad, sino nuevas características… todo esto en febrero de 2026. 👊

La versión 1.3 llegó con dominios de correo electrónico personalizados y seguimiento del coste de créditos. La versión 1.4 la siguió con tres nuevos tipos de campos y operaciones PATCH granulares para campos individuales.

Ambos lanzamientos comparten el mismo enfoque: más control sin añadir complejidad. Y ninguno de ellos introduce cambios que rompan la compatibilidad, de modo que puedes adoptar estas características a tu propio ritmo.

Si buscas una solución de firma de API que te ofrezca flexibilidad sin obligarte a realizar migraciones, así es como se ve.

Aquí está todo lo nuevo en las versiones v1.3 y v1.4.

v1.4.0: Nuevos tipos de campos y actualizaciones granulares

Fecha de lanzamiento: 31 de enero de 2026

La versión 1.4 amplía lo que puedes hacer con los campos de los documentos y cómo los actualizas. Tres nuevos tipos de campos te ofrecen más opciones para recopilar datos. Las operaciones PATCH ahora admiten actualizaciones individuales de campos. Y un nuevo parámetro template_user_id hace que la asignación de destinatarios sea explícita.

Tres nuevos tipos de campos

El enum de tipos de campos ahora incluye textarea, url y radio_buttons:

El tipo radio sigue funcionando por motivos de compatibilidad con versiones anteriores, pero radio_buttons es el nombre canónico a partir de ahora.

Los tipos de campo url

El nuevo tipo de campo url te permite incrustar enlaces en los que se puede hacer clic directamente en tus documentos de firma. El campo se establece automáticamente en read_only: true, ya que los firmantes hacen clic en el enlace en lugar de editarlo.

Usa read_only_value para establecer la URL de destino y format_rules.urlDisplayText para personalizar lo que ven los firmantes:

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

{
  "field": {
    "type": "url",
    "position": { "x": 100, "y": 200, "width": 150, "height": 30 },
    "page_number": 1,
    "read_only_value": "https://example.com/terms",
    "format_rules": { "urlDisplayText": "View Terms & Conditions" }
  }
}

Caso de uso: Términos y políticas incrustados. Si tu flujo de firma requiere que los firmantes acepten condiciones de servicio, políticas de privacidad o contratos externos, el tipo de campo url mantiene todo en un solo documento. Los firmantes hacen clic en el enlace, revisan el contenido de referencia y continúan firmando. No hay necesidad de adjuntar múltiples archivos PDF o redirigir a los firmantes a páginas externas antes de que puedan completar el flujo de trabajo.

Esto es especialmente útil para plataformas SaaS donde los términos cambian con frecuencia. Actualiza la URL enlazada una vez y cada nueva solicitud de firma apuntará a la versión actual.

El tipo de campo textarea

El tipo de campo textarea admite la entrada de texto de varias líneas. Úsalo cuando necesites que los firmantes proporcionen respuestas más largas: instrucciones especiales, notas de entrega o cualquier texto libre que no quepa en un campo de texto de una sola línea (text).

Operaciones PATCH para campos individuales

Anteriormente, actualizar un solo campo en una plantilla implicaba enviar toda la carga útil de la plantilla o usar el endpoint PUT completo. Ahora, tanto los endpoints PATCH de plantillas como los de solicitudes de firma admiten operaciones de un solo campo.

El método **PATCH de Plantilla** (PATCH /templates/{id}) puede actualizar:

• Propiedades de la plantilla

• Un único usuario

• Un único campo (nuevo en v1.4)

El método **PATCH de Solicitud de Firma** (PATCH /signing-requests/{id}) puede actualizar:

• Propiedades de la solicitud de firma

• Un único destinatario

• Un único campo (nuevo en v1.4)

Para crear un nuevo campo, incluye el objeto field sin un id:

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

{
  "field": {
    "type": "text",
    "x": 100,
    "y": 200,
    "width": 200,
    "height": 30,
    "page": 1,
    "required": true,
    "assigned_to_user_id": "user-uuid"
  }
}

Para actualizar un campo existente, incluye el field.id:

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

{
  "field": {
    "id": "field-uuid",
    "x": 120,
    "y": 220
  }
}

Este enfoque granular simplifica la gestión de campos cuando necesitas ajustar la posición de un solo campo, cambiar el estado obligatorio de un campo o añadir un nuevo campo sin tener que reconstruir toda la carga útil de la plantilla.

Asociación de usuarios de plantilla con template_user_id

Al crear solicitudes de firma a partir de plantillas, ahora puedes usar template_user_id para asociar explícitamente a los destinatarios con los usuarios de la plantilla:

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

{
  "template_id": "template-uuid",
  "recipients": [
    {
      "template_user_id": "template-user-uuid",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com"
    }
  ]
}

Antes de la versión 1.4, la asociación de destinatarios dependía de la propiedad order. Eso sigue funcionando como alternativa, pero template_user_id elimina la ambigüedad. Si tu plantilla tiene múltiples firmantes y quieres garantizar que Jane reciba el rol de "Comprador" (y no el de "Vendedor"), la asociación explícita asegura que la persona correcta reciba los campos adecuados.

Cambios en el esquema de la v1.4

El **enum de tipos de campo** se ha actualizado de:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio"]

A:

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

["text", "signature", "date", "checkbox", "initials", "dropdown", "radio_buttons", "textarea", "url"]

El **esquema de destinatarios** ahora incluye template_user_id para una asociación explícita de usuarios de plantilla al crear solicitudes de firma.

v1.3.0: Dominios de correo electrónico personalizados y visibilidad de uso

La versión 1.3 introdujo la API de Dominios de Correo Electrónico para el envío de correos electrónicos de marca blanca, el seguimiento de costes de créditos para la visibilidad del uso y la gestión del estado rechazado para las solicitudes de firma.

API de Dominios de Correo Electrónico

Una categoría completa de API para configurar dominios de correo electrónico personalizados. En lugar de que los correos electrónicos de las solicitudes de firma provengan de noreply@firma.dev, pueden provenir de signing@yourbrand.com.

Ocho nuevos endpoints:

Nuevos esquemas:

• Domain: Configuración del dominio de correo electrónico con estado de verificación

• DomainDnsRecord: Detalles del registro DNS para la verificación del dominio

El flujo de verificación funciona como la mayoría de las configuraciones de dominio de correo electrónico: añade tu dominio, verifica la propiedad con un registro TXT, configura SPF/DKIM/DMARC, finaliza con el proveedor de correo electrónico y establece tu dominio de envío principal.

Caso de uso: Correos electrónicos de firma de marca blanca. Si estás desarrollando una integración de API de firma electrónica para tu producto SaaS, tus clientes esperan que los correos electrónicos provengan de tu marca. Un correo de solicitud de firma desde contracts@yourplatform.com genera confianza. Un correo desde noreply@firma.dev despierta dudas.

Los dominios de correo electrónico personalizados combinan muy bien con los Espacios de Trabajo del Cliente (Customer Workspaces) para implementaciones completas de marca blanca. Cada uno de tus clientes obtiene un espacio de trabajo aislado con plantillas y solicitudes de firma que nunca hacen referencia a Firma.dev en la experiencia de firma.

Para conocer más detalladamente las opciones de marca blanca, consulta nuestras guías sobre la API de firma de documentos de marca blanca y los correos electrónicos de firma electrónica de marca blanca.

Seguimiento del coste de créditos

Dos nuevos campos proporcionan visibilidad sobre el uso de créditos:

• credit_cost en el esquema Template: Número de créditos consumidos al enviar una solicitud de firma desde esta plantilla

• credit_cost en el esquema SigningRequest: Créditos consumidos cuando se envió esta solicitud de firma

Un nuevo ajuste de espacio de trabajo, show_credit_cost_in_editor, te permite alternar si el coste de los créditos se muestra en los editores de firma y plantilla integrados.

Esto es importante para las plataformas SaaS que transfieren los costes a los clientes o necesitan realizar un seguimiento del uso por espacio de trabajo. Con el coste de créditos visible a nivel de plantilla y solicitud de firma, puedes crear paneles de facturación, establecer alertas de uso o mostrar a los clientes su consumo sin tener que consultar endpoints de análisis independientes.

A 0,049 € por sobre, los costes siguen siendo predecibles. Pero la visibilidad de hacia dónde se dirigen esos créditos te ayuda a optimizar.

Estado rechazado en solicitudes de firma

Las solicitudes de firma ahora admiten el estado declined (rechazado):

• Se ha añadido declined a los valores del enum SigningRequest.status

• Se ha añadido el campo date_declined al esquema SigningRequest

Cuando un firmante se niega a firmar, verás que esto se refleja en el estado y en la marca de tiempo. Esto complementa los campos declined_on y decline_reason en SigningRequestUser que se lanzaron en la v1.2.

Mejoras en el esquema de la v1.3

Campos de plantilla:

• Se ha añadido el campo date_default para establecer valores de fecha por defecto (formato ISO 8601)

• Se ha mejorado la descripción de multi_group_id para explicar la agrupación de campos mutuamente excluyentes en casillas de verificación y botones de opción

• Se ha aclarado que page_number tiene un índice basado en 1 y no debe superar el número de páginas del documento

Campos de solicitud de firma:

• Se aplican las mismas mejoras de multi_group_id que en los campos de plantilla

Notas de migración

Ni la v1.3 ni la v1.4 introducen cambios que rompan la compatibilidad.

Migración de v1.2 a v1.3:

• La configuración del dominio de correo electrónico está disponible de manera opcional

• Se añade el estado declined al enum de estados de solicitud de firma

• El seguimiento del coste de créditos está disponible en plantillas y solicitudes de firma

Migración de v1.3 a v1.4:

• El tipo de campo radio pasa a llamarse radio_buttons (ambos se aceptan por motivos de compatibilidad con versiones anteriores)

• Nuevas capacidades PATCH para la actualización granular de campos

• template_user_id disponible para una coincidencia explícita del destinatario

Puedes adoptar estas características de forma progresiva. Las integraciones existentes siguen funcionando sin modificaciones.

Desarrolla tu integración de API de firma electrónica

Firma.dev está pensado para desarrolladores que necesitan añadir la firma de documentos a sus productos sin la sobrecarga de contratos empresariales o integraciones complejas. Pago por uso a 0,049 € por sobre. Sin mínimos. Sin contratos.

Estos lanzamientos reflejan lo que escuchamos de nuestros clientes: más flexibilidad en los campos, mejor marca blanca y control granular sobre las plantillas y las solicitudes de firma.

Consulta el registro de cambios completo de la API para conocer el historial de versiones y las guías de migración. O empieza a desarrollar ahora mismo.

Empieza a utilizar Firma.dev de forma gratuita, sin necesidad de tarjeta de crédito.