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

Enviamos dos versiones de API seguidas, justo en la última semana. Nada que rompa, pero nuevas características… todo en febrero de 2026. 👊

La versión 1.3 llegó con dominios de correo electrónico personalizados y seguimiento del costo de crédito. La versión 1.4 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 significativos, por lo que puedes adoptar estas características a tu propio ritmo.

Si estás buscando una solución de firma de API que te brinde flexibilidad sin forzar migraciones, esto es lo que parece.

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

Tres Nuevos Tipos de Campo

El tipo de campo enum ahora incluye textarea, url, y radio_buttons:

El tipo radio todavía funciona para compatibilidad hacia atrás, pero radio_buttons es el nombre canónico de aquí en adelante.

Los tipos de campo url

El nuevo tipo de campo url te permite incrustar enlaces clicables directamente en tus documentos de firma. El campo se configura 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" }
  }
}

Uso: Términos y políticas integradas. Si tu flujo de firma requiere que los firmantes reconozcan los términos del servicio, políticas de privacidad o contratos externos, el tipo de campo url mantiene todo en un documento. Los firmantes hacen clic en el enlace, revisan el contenido referenciado y continúan firmando. No es necesario adjuntar múltiples 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 vinculada 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 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 de forma libre que no quepa en un campo text de una sola línea.

Operaciones PATCH para Campos Individuales

Anteriormente, actualizar un solo campo en una plantilla significaba enviar toda la carga útil de la plantilla o usar el punto final PUT completo. Ahora, tanto los puntos finales de Template como de Solicitud de Firma PATCH admiten operaciones de un solo campo.

Template PATCH (PATCH /templates/{id}) puede actualizar:

• Propiedades de la plantilla

• Un solo usuario

• Un solo campo (nuevo en v1.4)

Signing Request PATCH (PATCH /signing-requests/{id}) puede actualizar:

• Propiedades de la solicitud de firma

• Un solo destinatario

• Un solo 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 requerido de un campo o agregar un nuevo campo sin reconstruir toda la carga de la plantilla.

Coincidencia de Usuarios de Plantillas con template_user_id

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

{
  "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 se basaba en la propiedad order. Eso todavía funciona como respaldo, pero template_user_id elimina la ambigüedad. Si tu plantilla tiene múltiples firmantes y quieres garantizar que Jane obtenga el rol de "Comprador" (no el rol de "Vendedor"), la coincidencia explícita asegura que la persona correcta reciba los campos correctos.

Cambios de Esquema de v1.4

Tipo de campo enum 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"]

Esquema de destinatarios ahora incluye template_user_id para la coincidencia explícita de usuarios de plantillas 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 enviar correos electrónicos de marca blanca, el seguimiento del costo de crédito para la visibilidad del uso y el manejo de 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 solicitud de firma provengan de noreply@firma.dev, pueden provenir de signing@tuMarca.com.

Ocho nuevos puntos finales:

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 dominios de correo electrónico: agrega 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.

Uso: Correos electrónicos 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 electrónicos provengan de tu marca. Un correo electrónico de solicitud de firma de contracts@tuplataforma.com genera confianza. Un correo electrónico de noreply@firma.dev genera preguntas.

Los dominios de correo electrónico personalizados combinan bien con Espacios de Trabajo de Cliente para implementaciones de marca blanca completas. 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 un vistazo más profundo a las opciones de marca blanca, consulta nuestras guías sobre API de firma de documentos de marca blanca y correos electrónicos de firma electrónica de marca blanca.

Seguimiento del Costo del Crédito

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

Una nueva configuración de espacio de trabajo, show_credit_cost_in_editor, te permite alternar si los costos de crédito se muestran en los editores de plantillas y firmas integrados.

Esto importa para plataformas SaaS que transfieren costos a los clientes o necesitan rastrear el uso por espacio de trabajo. Con el costo de crédito visible a nivel de plantilla y solicitud de firma, puedes construir paneles de facturación, establecer alertas de uso o mostrar a los clientes su consumo sin consultar puntos finales de análisis separados.

A $0.029 por sobre, los costos siguen siendo predecibles. Pero la visibilidad de a dónde van esos créditos te ayuda a optimizar.

Estado Rechazado de Solicitud de Firma

Las solicitudes de firma ahora admiten un estado declined:

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

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

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

Mejoras del Esquema de v1.3

Campos de plantilla:

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

• Descripción mejorada de multi_group_id para explicar la agrupación de campos mutuamente excluyentes para casillas de verificación y botones de radio

• Se aclaró que page_number es 1-indexado y no debe exceder el conteo de páginas del documento

Campos de solicitud de firma:

• Las mismas mejoras de multi_group_id que los campos de plantilla

Notas de Migración

Ninguna de las versiones v1.3 ni v1.4 introduce cambios significativos.

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

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

• Se agregó el estado declined al enum de estado de solicitud de firma

• Seguimiento del costo del crédito disponible en plantillas y solicitudes de firma

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

• El tipo de campo radio se renombró a radio_buttons (ambos aceptados para compatibilidad hacia atrás)

• Nuevas capacidades PATCH para actualizaciones de campos granulares

• template_user_id disponible para coincidencia explícita de destinatarios

Puedes adoptar estas características de manera incremental. Las integraciones existentes continúan funcionando sin modificaciones.

Construye tu Integración de API de Firma Electrónica

Firma.dev está construido para desarrolladores que necesitan agregar la firma de documentos a sus productos sin el gasto adicional de contratos empresariales o integraciones complejas. Precios por uso a $0.029 por sobre. Sin mínimos. Sin contratos.

Estas versiones reflejan lo que escuchamos de los clientes: más flexibilidad de campo, mejor etiquetado blanco y control granular sobre plantillas y solicitudes de firma.

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

Empieza con Firma.dev gratis, sin necesidad de tarjeta de crédito.