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 consecutivas, solo en la última semana. Nada rompedor, pero nuevas características... todo en febrero de 2026. 👊

La Versión 1.3 llegó con dominios de correo electrónico personalizados y seguimiento de costos de crédito. La Versión 1.4 siguió con tres nuevos tipos de campo y operaciones PATCH granulares para campos individuales.

Ambos lanzamientos comparten el mismo tema: más control sin más complejidad. Y ninguno introduce cambios radicales, por lo que puedes adoptar estas características a tu propio ritmo.

Si estás buscando una solución de firma 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 campo individuales. Y un nuevo parámetro template_user_id hace que la asignación de destinatarios sea explícita.

Tres Nuevos Tipos de Campo

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

El tipo radio todavía funciona para compatibilidad retroactiva, pero radio_buttons es el nombre canónico 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 establece automáticamente en read_only: true ya que los firmantes hacen clic en el enlace en lugar de editarlo.

Utiliza 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 incrustadas. Si tu flujo de firma requiere que los firmantes reconozcan los términos de 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 de referencia y continúan firmando. No hay necesidad de 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 formato 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 Signing Request PATCH admiten operaciones de campo único.

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 Plantilla con template_user_id

Al crear solicitudes de firma a partir de plantillas, ahora puedes usar template_user_id para asignar explícitamente destinatarios a usuarios de 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 se basaba en la propiedad order. Eso todavía funciona como retroceso, 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 en el Esquema v1.4

Enum de tipo de campo 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 la coincidencia 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 sin marca, el seguimiento de costos de crédito para la visibilidad del uso y el manejo del estado de declinación 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@yourbrand.com.

Ocho nuevos puntos finales:

Nuevos esquemas:

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

• DomainDnsRecord: Detalles del registro DNS para la verificación de 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.

Caso de uso: Emails de firma sin marca. Si estás construyendo 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@yourplatform.com genera confianza. Un correo de noreply@firma.dev genera dudas.

Los dominios de correo electrónico personalizados emparejan bien con Espacios de Trabajo de Clientes para despliegues completamente sin marca. 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 mirada más profunda a las opciones de marca blanca, ve nuestras guías sobre API de firma de documentos con marca blanca y emails de firma electrónica con marca blanca.

Seguimiento de Costos de Crédito

Dos nuevos campos proporcionan visibilidad en el uso de crédito:

• 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 del espacio de trabajo, show_credit_cost_in_editor, te permite activar 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 tableros de facturación, establecer alertas de uso o mostrar a los clientes su consumo sin consultar puntos finales analíticos separados.

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

Estado de Rechazo de Solicitud de Firma

Las solicitudes de firma ahora admiten un estado declined:

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

• Se agregó el campo date_declined al esquema SigningRequest

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

Mejoras en el Esquema de v1.3

Campos de Plantilla:

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

• Se mejoró la descripción de multi_group_id para explicar la agrupación de campos mutuamente exclusiva para casillas de verificación y botones de radio

• Se aclaró que page_number está indexado 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 los campos de plantilla

Notas de Migración

Ni v1.3 ni v1.4 introducen cambios radicales.

Migrando de v1.2 a v1.3:

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

• Se añadió el estado declined al enum de estado de solicitud de firma

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

Migrando de v1.3 a v1.4:

• El tipo de campo radio se renombró a radio_buttons (ambos aceptados para compatibilidad retroactiva)

• Nuevas capacidades PATCH para actualizaciones granulares de campos

• template_user_id disponible para la coincidencia explícita de destinatarios

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

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

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

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

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

Comienza con Firma.dev gratis—no se requiere tarjeta de crédito.