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

Publicamos dos versiones de la API consecutivas, justo en la última semana. Nada que rompa compatibilidad, pero nuevas funciones … todo en febrero de 2026. 👊

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

Ambas versiones comparten el mismo tema: más control sin más complejidad. Y ninguna introduce cambios que rompan compatibilidad, así que puedes adoptar estas funciones a tu propio ritmo.

Si estás buscando una solución de firma de API que te dé flexibilidad sin obligarte a migrar, esto es lo que eso significa.

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

v1.4.0: Nuevos tipos de campo 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 documentos y cómo los actualizas. Tres nuevos tipos de campo te ofrecen más opciones para recopilar datos. Las operaciones PATCH ahora admiten actualizaciones de campos individuales. Y un nuevo parámetro template_user_id hace explícita la coincidencia de destinatarios.

Tres nuevos tipos de campo

La enumeración de tipos de campo ahora incluye textarea, url y radio_buttons:

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

El tipo de campo url

El nuevo tipo de campo url te permite incrustar enlaces clicables directamente en tus documentos de firma. El campo se establece automáticamente como 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 reconozcan los términos del servicio, las 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 referenciado y continúan firmando. No hace falta adjuntar varios PDFs ni redirigir a los firmantes a páginas externas antes de que puedan completar el flujo.

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

El tipo de campo textarea

El tipo de campo textarea admite 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 text de una sola línea.

Operaciones PATCH para campos individuales

Antes, actualizar un único campo en una plantilla significaba enviar la carga útil completa de la plantilla o usar el endpoint PUT integral. Ahora tanto los endpoints PATCH de Plantilla como los de Solicitud de firma admiten operaciones sobre un solo campo.

PATCH de plantilla (PATCH /templates/{id}) puede actualizar:

• Propiedades de la plantilla

• Un único usuario

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

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 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 único campo, cambiar el estado de obligatorio de un campo o añadir un nuevo campo sin reconstruir toda la carga útil de la plantilla.

Coincidencia de usuarios de plantilla con template_user_id

Al crear solicitudes de firma a partir de plantillas, ahora puedes usar template_user_id para hacer coincidir 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 v1.4, la coincidencia 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 varios firmantes y quieres garantizar que Jane reciba el rol de "Buyer" (no el rol de "Seller"), la coincidencia explícita asegura que la persona correcta reciba los campos correctos.

Cambios de esquema de v1.4

La enumeración de tipos de campo se actualizó 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 la coincidencia explícita con usuarios de plantilla al crear solicitudes de firma.

v1.3.0: Dominios de correo personalizados y visibilidad del uso

La versión 1.3 introdujo la API de dominios de correo para el envío de correos de marca blanca, el seguimiento del coste en créditos para ofrecer visibilidad del uso y la gestión del estado rechazado para las solicitudes de firma.

API de dominios de correo

Una categoría completa de API para configurar dominios de correo personalizados. En lugar de que los correos de solicitud de firma salgan de noreply@firma.dev, pueden salir de signing@yourbrand.com.

Ocho nuevos endpoints:

Nuevos esquemas:

• Domain: Configuración de dominio de correo 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 dominios de correo: añade tu dominio, verifica la propiedad con un registro TXT, configura SPF/DKIM/DMARC, finaliza con el proveedor de correo y establece tu dominio principal de envío.

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

Los dominios de correo personalizados encajan bien con Espacios de trabajo de clientes para despliegues completos 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 del firmante.

Para una visión más profunda de las opciones de marca blanca, consulta nuestras guías sobre API de firma de documentos de marca blanca y correos de firma electrónica de marca blanca.

Seguimiento del coste en 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 a partir de esta plantilla

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

Un nuevo ajuste del espacio de trabajo, show_credit_cost_in_editor, te permite activar o desactivar si los costes en créditos se muestran en los editores incrustados de plantillas y de firmas.

Esto importa para las plataformas SaaS que repercuten los costes a los clientes o que necesitan hacer un seguimiento del uso por espacio de trabajo. Con el coste en créditos visible a nivel de plantilla y de solicitud de firma, puedes crear paneles de facturación, configurar alertas de uso o mostrar a los clientes su consumo sin consultar endpoints de analítica separados.

A 0,029 € por sobre, los costes siguen siendo previsibles. Pero la visibilidad sobre adónde van esos créditos te ayuda a optimizar.

Estado de rechazo de la solicitud de firma

Las solicitudes de firma ahora admiten un estado declined:

• Se añadió declined a los valores del enum SigningRequest.status

• Se añadió el campo date_declined al esquema SigningRequest

Cuando un firmante rechaza firmar, lo verás reflejado en el estado y en la marca temporal. Esto complementa los campos declined_on y decline_reason en SigningRequestUser que se publicaron en v1.2.

Mejoras del esquema de v1.3

Campos de plantilla:

• Se añadió el campo date_default para establecer valores de fecha predeterminados (formato ISO 8601)

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

• Se aclaró que page_number comienza en 1 y no debe superar el número de páginas del documento

Campos de solicitud de firma:

• Las mismas mejoras de multi_group_id que en los campos de plantilla

Notas de migración

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

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

• La configuración de dominios de correo está disponible, pero es opcional

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

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

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

• El tipo de campo radio se ha renombrado a radio_buttons (se aceptan ambos por compatibilidad con versiones anteriores)

• Nuevas capacidades PATCH para actualizaciones granulares de campos

• template_user_id disponible para la coincidencia explícita de destinatarios

Puedes adoptar estas funciones de forma incremental. Las integraciones existentes siguen funcionando sin modificaciones.

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

irma.dev está pensado para desarrolladores que necesitan añadir la firma de documentos a sus productos sin la complejidad de los contratos empresariales o de integraciones complejas. Precios de pago por uso de 0,029 € por sobre. Sin mínimos. Sin contratos.

Estas versiones reflejan lo que oímos de los clientes: más flexibilidad de campos, mejor marca blanca y un control granular sobre las plantillas y las solicitudes de firma.

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

Empieza gratis con Firma.dev: no se requiere tarjeta de crédito.