Saltar al contenido principal
Este documento ofrece un registro de cambios detallado de todas las versiones de la API de Firma, documentando nuevas funcionalidades, cambios importantes y mejoras entre cada versión.
URL estables para la referencia de la API. La referencia de la API ahora está disponible en URL sin versión, como /es/api-reference/templates/list-templates, y siempre muestra la versión más reciente. Las cinco versiones anteriores siguen disponibles en el menú de versiones. Los enlaces a versiones más antiguas redirigen a la página actual, y las especificaciones OpenAPI se pueden seguir descargando desde las entradas de más abajo.

Resumen de Versiones


v1.43.0

Fecha de lanzamiento: 15 de noviembre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.43.0 Paginación y totales de la lista, limpieza del texto del webhook de rebote, nombres de espacio de trabajo en los webhooks, reglas de nombres de destinatarios y de preparación, y enlaces reparados de la documentación. Cambios de comportamiento:
  • En el webhook de rebote, los valores message y sub_type ya no contienen puntos de código de control, de formato, separadores de línea ni sustitutos. Un valor que queda vacío después de la limpieza es null. message está limitado a 500 puntos de código y sub_type a 64.
  • GET /signing-requests devuelve páginas y totales exactos para toda lista de estados que incluya exactamente uno de in_progress o expired (por ejemplo status=expired o status=in_progress,declined), siempre que no haya que comprobar más de 50.000 solicitudes de firma. Los totales y las páginas son exactos para las filas leídas. Una solicitud cuya posición cambia porque otra solicitud cambió de estado durante la misma llamada puede faltar en esa respuesta; la siguiente llamada la devuelve. Un filtro que obligaría a comprobar más de 50.000 solicitudes de firma se rechaza con 400 VALIDATION_ERROR y el texto “More than 50,000 signing requests would have to be checked for this filter. Narrow the request with created_after, created_before, name, signer_name or signer_email.” En estas llamadas de lista, un recuento fallido ahora responde con 500 en lugar de 200. En estas listas, los recipients[] están en orden de firma y los fields[] llegan en un orden fijo, que es el mismo en cada llamada.
  • Los eventos de webhook signing_request.created, signing_request.updated, signing_request.cancelled, signing_request.deleted y template.used ahora llevan el workspace.name real.
  • Los guardados desde el panel y desde los editores integrados conservan los campos de identidad de destinatarios, CC y usuarios de plantilla, y los nombres de documento que el guardado no modificó.
  • En el panel y en los editores integrados, los nombres y cargos de destinatario escritos conservan los apóstrofos tipográficos, los caracteres U+2010 a U+2015 y el punto medio, y los valores escritos están limitados a 125 puntos de código para first_name y last_name, 150 para title y 255 para company. Un guardado desde un editor rechaza un destinatario cuyo nombre y apellido juntos superan los 255 caracteres.
  • Las respuestas de preparación de /users de solicitudes de firma y de plantillas usan format_rules.prefilledData e ignoran los prerrellenados editables. La preparación sigue siendo orientativa y puede cambiar en solicitudes existentes en cualquier sentido. Por ejemplo, una etiqueta Title sin prefilledData deja de exigir title; un prefilledData: "title" no editable pasa a exigirlo; un prerrellenado de cargo editable deja de exigirlo.
  • Un PUT que añade un nuevo firmante o aprobador exige first_name y una dirección de correo electrónico, como ya hace PATCH. En PATCH y PUT, un nombre que queda vacío después de quitar los espacios cuenta como ausente para un nuevo destinatario o CC. Las demás partes de la solicitud se siguen aplicando; reenvía solo el destinatario corregido.
  • Los enlaces internos reparados de la documentación de Firma.dev ahora funcionan en inglés, español y francés.

Notas de migración

  • Si GET /signing-requests responde con 400 VALIDATION_ERROR porque habría que comprobar más de 50.000 solicitudes de firma, acota la solicitud con created_after, created_before, name, signer_name o signer_email.
  • En estas llamadas de lista, un recuento fallido responde con 500 en lugar de 200.
  • Una solicitud que falta en una respuesta de lista porque su posición cambió aparece en la siguiente llamada.
  • Las respuestas de preparación de /users pueden cambiar en solicitudes existentes en cualquier sentido; la preparación sigue siendo orientativa.
  • Un PUT que añade un nuevo firmante o aprobador necesita first_name y una dirección de correo electrónico. Un nombre que queda vacío después de quitar los espacios cuenta como ausente. Las demás partes de la solicitud se siguen aplicando; reenvía solo el destinatario corregido.
  • Un guardado desde el panel o desde un editor integrado rechaza un nombre completo de destinatario de más de 255 caracteres.

v1.42.0

Fecha de lanzamiento: 12 de noviembre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Esta versión no añade ninguna versión de referencia propia. Sus cambios de referencia se publican con v1.43.0. Rechazos del ciclo de vida, filtro de la lista de solicitudes rechazadas y correcciones de webhooks. Los siguientes rechazos de la API y el filtro de la lista se aplican en la ruta multidocumento, que da servicio a todas las empresas desde el 13 de octubre de 2026; los cambios de webhooks se aplican a todas las solicitudes. Cambios de comportamiento:
  • POST /signing-requests/{id}/cancel en una solicitud rechazada responde con 409 DECLINED y no escribe nada. Trátalo como ALREADY_CANCELLED. Una solicitud que se rechazó y después se canceló sigue respondiendo con ALREADY_CANCELLED. Una solicitud expirada todavía se puede cancelar. Un 409 CONFLICT significa que la solicitud cambió de estado mientras se ejecutaba la cancelación: vuelve a intentarlo una vez y la siguiente respuesta indicará el estado real.
  • POST /signing-requests/{id}/resend en una solicitud rechazada responde con 409 DECLINED; en una solicitud expirada, con 409 EXPIRED. No se envía ningún correo electrónico si la solicitud ya está rechazada o expirada cuando llega la llamada; si pasa a estar rechazada o expirada mientras se envían los recordatorios, los destinatarios ya notificados conservan su correo electrónico y la respuesta sigue siendo el 409. EXPIRED es definitivo: crea una solicitud nueva.
  • Los rechazos de POST /signing-requests/{id}/send ahora incluyen un code: 400 DECLINED o 400 ALREADY_CANCELLED. El estado y el mensaje no cambian.
  • GET /signing-requests?status=declined devuelve las solicitudes rechazadas (antes, la lista sin filtrar). Una solicitud rechazada que se canceló posteriormente aparece como cancelled. Combinar in_progress o expired con otro estado ahora devuelve todos los estados solicitados (antes, solo las filas in_progress o expired).
  • Se retiran ocho nombres de eventos que Firma.dev nunca envía: signing_request.field.filled, signing_request.document.updated, signing_request.recipient.added, signing_request.recipient.updated, template.created, template.deleted, template.field.added, workspace.deleted. POST /webhooks y PUT /webhooks/{id} los eliminan de la lista enviada e informan de cada uno en un array warnings; una lista que queda vacía después de eliminarlos responde con 400 VALIDATION_ERROR. Los webhooks almacenados no cambian; un PUT sin events los deja como están.
  • signing_request.recipient.signed: all_complete es true solo cuando todos los firmantes y aprobadores de la solicitud han terminado (antes era true en todos los eventos cuando el orden de firma estaba activado). Usa signing_request.completed para detectar la finalización; todavía puede quedar pendiente un sello de organización.
Novedades:
  • Nuevo evento al que puedes suscribirte, signing_request.recipient.email_bounced (sobre estándar; payload en la guía de webhooks). Un destinatario puede producir un rebote suave seguido de uno duro y más rebotes después de un recordatorio. Cada webhook está limitado a 100 eventos por minuto entre todos los tipos de evento, así que suscríbete a email_bounced desde un webhook dedicado cuando hagas envíos masivos.
  • signing_request.viewed incluye el objeto signing_request completo (workspace_id, created_at, sent_at, expires_at, document_page_count, test), los campos first_name, last_name, order y designation del destinatario, y el objeto workspace.
  • signing_request.completed incluye los destinatarios (firmantes y aprobadores con signed_at) en lugar de un array vacío.
Nota: si se desactiva la ruta multidocumento, las solicitudes que no son multidocumento recuperan el comportamiento anterior para los rechazos de cancelación y reenvío y para los códigos de rechazo de send; en ese caso, el reenvío de una solicitud rechazada o expirada responde con 500, y ?status=declined vuelve a devolver la lista sin filtrar para todas las empresas hasta que se reactiva la ruta. Los cambios de webhooks se mantienen en todas las rutas: el catálogo de 27 eventos, la clave warnings, el sobre email_bounced, el payload de viewed, all_complete y completed.recipients.

Notas de migración

  • Si una cancelación responde con 409 CONFLICT, vuelve a intentarlo una vez; la siguiente respuesta indicará el estado real.
  • EXPIRED es definitivo: crea una solicitud nueva.
  • Trata 409 DECLINED al cancelar como ALREADY_CANCELLED.
  • POST /webhooks y PUT /webhooks/{id} pueden devolver un array warnings que identifica los eventos retirados que eliminaron.
  • all_complete es true solo cuando todos los firmantes y aprobadores han terminado; usa signing_request.completed para detectar la finalización.

v1.40.4

Fecha de lanzamiento: 23 de octubre de 2026 Tipo de lanzamiento: Versión de parche Especificación OpenAPI: Descargar la especificación v1.40.4

Correcciones de la referencia

La especificación OpenAPI ahora describe lo que la API ya hace en estos casos. La API en sí no ha cambiado.
  • Rotación del secreto de webhook. POST /webhooks/rotate-secret y POST /workspaces/{id}/webhooks/rotate-secret permiten una rotación por hora (la especificación indicaba una por minuto); una segunda llamada dentro de esa hora devuelve 429 con el código COOLDOWN_ACTIVE. Solo se conserva un secreto anterior: si se vuelve a rotar durante el período de solapamiento de 7 días, se reemplaza. El encabezado X-RateLimit-Limit de POST /webhooks/rotate-secret ahora indica 60 solicitudes por minuto.
  • Envío de una solicitud. POST /signing-requests/{id}/send para una solicitud que ya se había enviado devuelve 409 con el código ALREADY_SENT (la especificación indicaba 400), y devuelve 409 con el código SEND_IN_PROGRESS mientras hay otro envío en curso. Una solicitud cancelada o rechazada devuelve 400. El ejemplo de éxito ahora coincide con la respuesta: success, message, sentTo, sentAt. Su encabezado X-RateLimit-Limit ahora indica 120 solicitudes por minuto.
  • Crear y enviar. Cuando el paso de envío de POST /signing-requests/create-and-send falla antes de que haya comenzado cualquier parte del envío, la solicitud de firma se elimina y se devuelve un error; no queda ningún borrador. Si el envío ya había comenzado, la solicitud se conserva y la respuesta 409 incluye su signing_request_id.
  • Listado de solicitudes de firma. En GET /signing-requests, signer_email realiza una coincidencia parcial sin distinguir entre mayúsculas y minúsculas (la especificación indicaba una coincidencia exacta). Las solicitudes eliminadas de forma parcial se incluyen de manera predeterminada con el estado deleted; el parámetro exclude_deleted=true, ahora documentado, las excluye.
  • Descargas parciales. GET /signing-requests/{id}/download devuelve una instantánea de progreso parcial para cualquier solicitud enviada que no esté finalizada. No hay ninguna configuración allow_partial_download. Una solicitud finalizada cuyo certificado de finalización todavía se está generando devuelve 409.
  • document_only_hash. La descripción ahora indica qué archivo se usa para el hash: el PDF sellado de cada documento, no el archivo subido ni el PDF final con el certificado.

Notas de migración

  • Sin cambios en las solicitudes, las respuestas ni las entregas de webhooks.
  • Si tu lógica de reintentos para POST /signing-requests/{id}/send esperaba un 400 para una solicitud ya enviada, gestiona 409 ALREADY_SENT en su lugar.

v1.40.3

Fecha de lanzamiento: 20 de octubre de 2026 Tipo de lanzamiento: Versión de parche

Evidencia del código de un solo uso en el registro de auditoría

El registro de auditoría ahora guarda que un firmante introdujo el código de un solo uso, con una referencia al registro del código verificado, y verify-signing-otp responde con más precisión cuando no se puede verificar un código.
  • Eventos de auditoría. GET /signing-requests/{id}/audit devuelve eventos otp_verified con details.channel = "email" y details.otp_code_id, descritos como Entered the one-time code sent by email. Los eventos document_finished incluyen details.otp_code_id cuando la sesión que finalizó el documento estaba vinculada a un código verificado. Esto se aplica a solicitudes con menos de 1000 filas de seguimiento; las solicitudes más grandes mantienen el truncamiento actual.
  • Respuestas de verify-signing-otp.
    • Un fallo de la base de datos devuelve 500 INTERNAL en lugar de OTP_NOT_FOUND.
    • Un firmante desconocido devuelve 404 SIGNING_USER_NOT_FOUND.
    • Un firmante de una solicitud eliminada devuelve 404 SIGNING_REQUEST_NOT_FOUND. Antes, un código vigente de una solicitud eliminada todavía se verificaba.
    • Un signingUserId con formato incorrecto devuelve 400 INVALID_INPUT.
    • Una solicitud que ya no se puede verificar (cancelada, rechazada, caducada, ya firmada, aún no enviada, fuera del turno del firmante o con el sello en pausa) devuelve 200 con code: "SIGNING_STATE_CHANGED" y state.
    • Un código correcto con un fallo transitorio ya no consume un intento.
  • Sin cambios en el esquema de OpenAPI. event sigue siendo texto libre. Esta versión no añade ninguna versión de referencia ni enlaza ningún documento OpenAPI.
  • Descripciones de auditoría de administrador. GET /signing-requests/{id}/audit y el registro de auditoría del panel describen una cancelación desde el panel como Signing Request Cancellation requested y una eliminación desde el panel como Signing Request Deletion requested. Un reintento de certificado añade Certificate regeneration requested. Firma.dev escribe cada línea antes del cambio, de modo que la línea permanece cuando la acción falla después o pierde una condición de carrera; “requested” no confirma que la acción se haya completado. Las filas escritas antes de esta versión conservan la redacción anterior (Signing Request Cancelled / Signing Request Deleted).

v1.40.2

Fecha de lanzamiento: 19 de octubre de 2026 Tipo de lanzamiento: Versión de parche Especificación OpenAPI: Descargar la especificación v1.40.2

Lista de eventos de webhook

La lista events de POST /webhooks y PUT /webhooks/{id} en la especificación OpenAPI ahora nombra los 26 eventos que envía Firma.dev, los mismos que describe la guía de webhooks. Desde la v1.37.0, la lista nombraba eventos que la API rechaza y omitía eventos que envía. La API en sí no ha cambiado.
  • Añadidos, ya enviados: signing_request.updated, signing_request.certificate.generated, signing_request.reminder.sent, signing_request.recipient.signed, signing_request.recipient.declined y signing_request.recipient.identity_changed.
  • Eliminados, nunca aceptados por la API (una solicitud que nombra uno devuelve 400 VALIDATION_ERROR): signing_request.declined, signing_request.voided, signing_request.field.completed, signing_request.resent y signing_request.credits.purchased. Para un firmante que rechaza, suscríbase a signing_request.recipient.declined; para una solicitud cancelada, a signing_request.cancelled.
  • Eliminados, aceptados por la API pero nunca enviados: template.created, template.deleted, template.field.added y workspace.deleted. Un webhook que los nombra sigue siendo válido, pero no llega ningún evento de estos tipos.

Notas de migración

  • Sin cambios en las solicitudes, las respuestas ni las entregas de webhooks.
  • Si generó un cliente o una validación a partir de la especificación, vuelva a generarlos: la lista anterior rechazaba eventos a los que puede suscribirse y ofrecía eventos que la API rechaza.

v1.40.1

Fecha de lanzamiento: 18 de octubre de 2026 Tipo de lanzamiento: Versión de parche Especificación OpenAPI: Descargar la especificación v1.40.1

PDF dañados

Desde el 18 de octubre de 2026, Firma.dev rechaza un PDF en el que una página no tiene contenido válido, por ejemplo una página cuyo contenido apunta a los datos de otra página en lugar de a sus propias instrucciones de dibujo. Esa página se muestra en blanco, y Firma.dev no puede generar el certificado de finalización de una solicitud que la contenga. La solicitud devuelve 400 MALFORMED_PDF:
  • malformed_pages indica los números (basados en 1) de las páginas dañadas. El mensaje nombra la primera.
  • En POST /signing-requests, POST /signing-requests/create-and-send y POST /templates, document_position (basado en 1, en el orden de documentos de la solicitud) identifica el documento, y se añade document_id cuando el documento procede de document_id o document_ids.
  • No se escribe nada: ninguna plantilla, ninguna solicitud de firma, ningún cargo de créditos, ningún correo electrónico.
  • En POST /signing-requests, POST /signing-requests/create-and-send y POST /templates, una carga indicada con document_id o document_ids queda consumida cuando se devuelve este error: vuelve a cargar el archivo reparado con POST /documents para obtener un id nuevo. En las rutas de adición y reemplazo de /documents, la carga se conserva.
  • Volver a exportar el archivo desde la aplicación que lo creó, o guardarlo de nuevo desde un editor de PDF, suele repararlo.
Las rutas que lo devuelven son las que aceptan un documento: POST /templates, PATCH /templates/{id}, PUT /templates/{id}, POST /templates/{id}/replace-document, POST /templates/{id}/documents, PATCH /templates/{id}/documents/{document_id}, POST /signing-requests, POST /signing-requests/create-and-send, PATCH /signing-requests/{id}, POST /signing-requests/{id}/documents y PATCH /signing-requests/{id}/documents/{document_id}.

PDF ilegibles

Desde el 17 de octubre de 2026, un documento que no se puede leer como PDF, incluido un PDF cifrado, devuelve 400 VALIDATION_ERROR con el mensaje The uploaded document is not a readable PDF en las mismas rutas. Antes devolvía 500. Las rutas de adición y reemplazo de /documents ya respondían así, y ahora también lo hacen para un archivo que empieza como un PDF pero cuyo árbol de páginas no se puede leer.

Notas de migración

  • Las solicitudes con PDF válidos se comportan como antes.
  • Donde cargues documentos, gestiona 400 MALFORMED_PDF: muestra el mensaje y pide un archivo reparado. Enviar el mismo archivo de nuevo devuelve el mismo error.
  • Si analizas las respuestas de error de forma estricta, acepta malformed_pages, document_position y document_id.
  • Un PDF ilegible ahora devuelve 400, no 500. No lo reintentes.

v1.40.0

Fecha de lanzamiento: 17 de octubre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.40.0

Botones de la página de firma

Dos nuevas configuraciones controlan los botones que firmantes y aprobadores ven en la página de firma, alojada o incrustada:
  • allow_decline muestra el botón Rechazar firma. Cuando es false, el botón se oculta para todos los firmantes y aprobadores, y Firma.dev tampoco acepta ningún rechazo. Nadie puede rechazar la solicitud de firma en Firma.dev, así que solo puede detenerse cancelándola.
  • show_save_for_later muestra el botón Guardar y terminar luego. Cuando es false, solo se oculta el botón.
Firma.dev usa el valor de la solicitud de firma. Si es null, se aplica el valor del espacio de trabajo y, si también es null, el de la empresa. El valor predeterminado de la empresa es true, así que las páginas de firma no cambian hasta que configures un valor.
  • Una solicitud de firma creada desde una plantilla (template_id en POST /signing-requests y POST /signing-requests/create-and-send, o POST /templates/{id}/duplicate) copia los valores de la plantilla al crearse. En las dos rutas de creación, un valor en settings de la solicitud reemplaza al de la plantilla; null ahí significa el valor del espacio de trabajo. POST /templates/{id}/duplicate siempre copia los valores de la plantilla. Cambiar la plantilla después no cambia las solicitudes de firma ya creadas a partir de ella.
  • POST /templates/{id}/copy copia ambos valores a la nueva plantilla.
  • Un cambio del valor del espacio de trabajo o de la empresa se aplica a todas las solicitudes de firma cuyo propio valor es null, incluidas las solicitudes ya enviadas y las creadas antes de esta versión.
  • Las respuestas devuelven los valores como true, false o null: en settings de las plantillas (GET /templates, GET /templates/{id}, POST /templates, PUT /templates/{id}) y de las solicitudes de firma (GET /signing-requests, GET /signing-requests/{id} y las respuestas de creación), y en el nivel superior de GET /company/settings y GET /workspace/{workspace_id}/settings. Los valores de la empresa son siempre true o false.
  • Cualquier otro valor, como una cadena o un número, devuelve 400 VALIDATION_ERROR con el nombre de la clave (por ejemplo settings.allow_decline must be a boolean or null) y no escribe nada. PUT /company/settings tampoco acepta null.

Límite de tamaño de la solicitud

Desde el 13 de octubre de 2026, un cuerpo de solicitud de más de 6.291.456 bytes (6 MiB) devuelve 413 REQUEST_TOO_LARGE con el cuerpo de error estándar error y code. Antes, la puerta de enlace respondía 502. La referencia de la API lo documenta en POST /templates, POST /signing-requests, POST /signing-requests/create-and-send y POST /documents. Para enviar un documento más grande, solicita una URL de carga con POST /documents, sube el archivo a esa URL y pasa document_id o document_ids en lugar de base64 en línea.

Notas de migración

  • El cambio es aditivo. Las solicitudes que nunca envían allow_decline ni show_save_for_later se comportan como antes, y ambos botones siguen visibles hasta que se configura un valor.
  • Si analizas las respuestas de forma estricta, acepta las dos nuevas claves en las respuestas de plantillas, solicitudes de firma, configuración del espacio de trabajo y configuración de la empresa.
  • Si envías documentos grandes en base64 en línea, gestiona 413 REQUEST_TOO_LARGE o sube los archivos con POST /documents.

v1.39.1

Fecha de lanzamiento: 12 de octubre de 2026 Tipo de lanzamiento: Versión de parche Especificación OpenAPI: Descargar la especificación v1.39.1

Actualización, 13 de octubre de 2026

  • En POST /signing-requests y POST /signing-requests/create-and-send con template_id, cuando la plantilla no tiene destinatarios propios y seal_participants está ausente o es null, los sellos heredados conservan ahora el orden de la plantilla al principio (1..k), seguidos por los destinatarios de la solicitud (a partir de k+1). Los arrays de reemplazo explícitos, las plantillas con destinatarios y las solicitudes sin sellos conservan su comportamiento de orden anterior.
  • Los reemplazos mediante PATCH /seals/{id} requieren ahora statement con accepted: true, version: 1, language, text exactamente igual al statement_text almacenado de GET /seals/{id} y signatory_name (signatory_title opcional). Esto se aplica a cambios en image, typed, display_name, signatory_title o statement. Sin statement, la solicitud devuelve 400 SEAL_STATEMENT_REQUIRED y no escribe nada. El comportamiento de creación de POST /seals no cambia.
  • Cada reemplazo registra su propio momento de aceptación, autor de la llamada y firmante enviado. El texto de la declaración, el hash, el idioma, la versión de la declaración y authority_name siguen siendo los de la versión 1 del sello. Las solicitudes ya enviadas conservan su versión fijada; las enviadas después del reemplazo usan la nueva versión, cuyo firmante y fecha de aceptación aparecen en sus certificados.
  • Los objetos de sello de POST /seals, GET /seals, GET /seals/{id}, PATCH /seals/{id} y los webhooks organization_seal.created, organization_seal.updated y organization_seal.deleted incluyen ahora statement_text y statement_hash. Los identificadores de usuario y clave API del declarante, la dirección IP y el user agent se excluyen de estos objetos de sello.

Sellos de organización desde plantillas

POST /signing-requests y POST /signing-requests/create-and-send con un template_id ahora copian los participantes de sello de la plantilla y sus campos de sello. La clave seal_participants decide qué ocurre:
  • Ausente o null: la solicitud hereda los sellos de la plantilla.
  • Un array: el array reemplaza los sellos de la plantilla. Los campos de sello de la plantilla no se copian.
  • []: la solicitud se crea sin sellos.
  • Cualquier otro tipo devuelve 400 VALIDATION_ERROR. Esto se comprueba en todas las rutas de creación, con o sin template_id.
Los campos del cuerpo solo reemplazan campos de la plantilla; por eso, en una plantilla que tiene campos, los sellos de un array de reemplazo no pueden obtener un campo de estampa en esa llamada y enviar la solicitud devuelve 400 SEAL_NO_IMAGE_FIELD. Para usar tus propios sellos con sus campos, crea a partir de un documento (o, solo en POST /signing-requests, usa una plantilla sin campos y asigna campos del cuerpo con seal_participant_temp_id). En caso contrario, hereda los sellos de la plantilla. Un sello heredado usa la versión actual del sello. Si el sello no tiene versión actual, o esa versión está revocada o eliminada, la creación devuelve 409 SEAL_UNAVAILABLE y no se escribe nada. Si se conserva al menos un sello heredado y los sellos de organización no están habilitados, la creación devuelve 503 SEALS_DISABLED. Un sello heredado limitado a otro espacio de trabajo distinto del de la solicitud, o que la empresa de la clave API no puede ver, se omite, junto con sus campos. Aparece en la respuesta con dropped: true, después de las demás entradas. Cada entrada persistida lleva dropped: false.
seal es null cuando la empresa de la clave API no puede ver el sello. Un sello de toda la empresa nunca se omite.

Orden con una plantilla

Cuando una creación con template_id resuelve al menos un sello, los destinatarios y los sellos se renumeran 1..n. Los sellos heredados conservan sus posiciones relativas a los destinatarios de la plantilla; los sellos suministrados en un array de reemplazo se colocan según su order. Un sello va primero cuando empata con un destinatario. Una creación así devuelve 201 donde antes devolvía 400 INVALID_SIGNING_ORDER o 400 SEAL_ORDER_COLLISION. La respuesta informa de los órdenes renumerados.
  • Desde el 13 de octubre de 2026, si la plantilla no tiene destinatarios y seal_participants está ausente o es null, los sellos heredados conservan el orden de la plantilla al principio (1..k); los destinatarios de la solicitud van después (a partir de k+1).
  • En POST /signing-requests, un recipient_id numérico en un campo sigue contando los destinatarios como se numerarían sin el sello.
  • Las creaciones basadas en un documento (document, document_id, document_ids) con participantes de sello explícitos no cambian: se aplican las comprobaciones de orden compartido sin procesar.

Campos de estampa y envío

Un sello necesita al menos un campo de estampa. La creación no lo comprueba, pero enviar una solicitud de firma cuyo sello no tiene ningún campo de estampa devuelve 400 SEAL_NO_IMAGE_FIELD. Da a cada sello al menos un campo de estampa.

Duplicar una plantilla

Excepto para las empresas habilitadas para las funciones multidocumento, POST /templates/{id}/duplicate copia los participantes de sello de la plantilla y sus campos a la nueva solicitud de firma, y los devuelve en seal_participants ([] cuando no hay ninguno). Cada sello conservado usa la versión actual de su linaje. Si el linaje no tiene versión actual, o esa versión está revocada o eliminada, la ruta devuelve 409 SEAL_UNAVAILABLE. Un sello limitado a otro espacio de trabajo distinto del de destino, o que la empresa de la clave API no puede ver, se omite y se lista con dropped: true. Si se conserva al menos un sello y los sellos de organización no están habilitados, la ruta devuelve 503 SEALS_DISABLED. Estos errores se devuelven antes de escribir nada. Para las empresas habilitadas para las funciones multidocumento, esta ruta adjunta tal cual la versión almacenada del sello de la plantilla. Un sello que fue reemplazado, revocado o eliminado desde entonces falla al enviar. La respuesta no incluye la clave seal_participants.

seal_attribute

Un campo de texto propio de un sello admite seal_attribute: display_name o signatory_title. Define qué propiedad del sello imprime el campo. POST /signing-requests y POST /signing-requests/create-and-send lo aceptan, desde un documento o desde una plantilla. Cualquier otro valor devuelve 400 VALIDATION_ERROR; null se acepta.
  • POST /signing-requests/create-and-send desde un documento ahora conserva seal_attribute. Antes se descartaba.
  • Un campo de sello copiado de una plantilla conserva el formato del campo de la plantilla. seal_attribute en la solicitud reemplaza únicamente qué propiedad imprime.

Plantillas

  • GET /templates/{id} y PUT /templates/{id} devuelven seal_participants, ordenados por order, [] cuando la plantilla no tiene ninguno. Cada entrada tiene la forma de los participantes de sello en el resto de rutas.
  • POST /templates no acepta seal_participants, recipients ni fields. Los ignora y devuelve un array warnings con una cadena por cada clave presente, por ejemplo seal_participants is not accepted on POST /templates and was ignored; add it with PATCH or PUT /templates/{id}. Sin esas claves la respuesta no cambia.

Otros cambios

  • Corregido: seal_participants en GET /signing-requests/{id}, GET /signing-requests, POST /signing-requests y POST /signing-requests/create-and-send ahora devuelve cada participante de sello de organización con su sello (id, linaje, versión, nombre y nombre para mostrar) para todas las empresas. Antes esta lista estaba vacía, aunque el sello en sí se guardaba y se aplicaba correctamente en el documento. Esta corrección solo cambia lo que devuelve la API; los documentos almacenados, las firmas y los webhooks no se modifican por ella.
  • Los certificados de finalización ahora dibujan los campos de estampa, fecha y texto del sello aplicado, y listan a cada participante de sello en la tabla de firmantes, en orden de firma. El certificado no se genera mientras quede un sello pendiente (sin aplicar o en pausa). Un sello aplicado automáticamente al finalizar, sin un destinatario que lo active, ya no bloquea el certificado; su línea de auditoría dice “una vez que finalizaron todos los participantes anteriores” (en el idioma del certificado).

Documentación y referencia de la API

La referencia de la API de esta versión documenta lo siguiente. Describe respuestas que la API ya daba.
  • Cada entrada de seal_participants en POST /signing-requests y POST /signing-requests/create-and-send requiere temp_id y order. seal_id es opcional: sin él se usa el sello predeterminado del espacio de trabajo o, si el espacio de trabajo no tiene ninguno, el sello predeterminado de la empresa, y la llamada devuelve 400 SEAL_UNAVAILABLE cuando no existe ninguno de los dos. La referencia tenía seal_id como obligatorio y temp_id como opcional.
  • El cuerpo seal_participant de PATCH /signing-requests/{id} y PATCH /templates/{id} se documenta tal como lo lee la API: id, seal_id, order y, en las solicitudes de firma, swap_to_seal_id. La clave participant_id que mostraban las referencias anteriores nunca se leía; usa id. Añadir un participante de sello responde 201 y actualizarlo o cambiarlo responde 200, ambos con { "seal_participant": ... }. Estas rutas devuelven 503 SEALS_DISABLED cuando los sellos de organización no están habilitados y se añade un participante de sello o se cambia su sello. En PATCH /signing-requests/{id}, un campo que pertenece a un participante de sello solo acepta cambios de posición y de página; las demás claves, incluida recipient_id, se ignoran.
  • Un cambio de sello en PATCH /signing-requests/{id} documenta sus respuestas: 403 PROTECTED_KEY_REQUIRED cuando la clave API no es del espacio de trabajo protegido; 404 NOT_FOUND cuando el nuevo sello no existe, pertenece a otra empresa o está limitado a otro espacio de trabajo; 409 SEAL_UNAVAILABLE cuando el nuevo sello está revocado, eliminado o no es la versión actual; 409 SEAL_MUTATION_NOT_ALLOWED cuando la solicitud no se envió o el participante no está en pausa; 400 SEAL_FIELD_REQUIRED cuando el participante no tiene un campo de estampa.
  • El cuerpo 200 de DELETE /signing-requests/{id}/seal-participants/{participant_id} es { "deleted": true }.
  • El array fields de la respuesta de POST /signing-requests/create-and-send lista todos los campos activos, incluidos los campos de los participantes de sello. Cada elemento es el registro del campo tal como se guarda, no la forma Field de las solicitudes (por ejemplo, el tipo está en field_type).
  • POST /templates/{id}/copy documenta sus seal_participants (comportamiento sin cambios).
  • PUT /templates/{id} documenta su array de solicitud seal_participants (TemplateSealParticipantInput), que reemplaza el conjunto de sellos de la plantilla.
  • El 400 de POST /signing-requests/create-and-send lista SEAL_NO_IMAGE_FIELD (un sello sin campo de estampa se rechaza al enviar).
  • Los ajustes cuyo null tiene un significado (require_otp_verification, require_terms_acceptance, allow_presigning_download, terms_url, el recipient_id o assigned_to_user_id de un campo, identity_editable_fields y los ajustes del espacio de trabajo show_signature_frame y show_partial_watermark) ahora indican qué hace null.

Notas de migración

  • Para los reemplazos de sellos a partir del 13 de octubre de 2026, lee GET /seals/{id} y envía statement en PATCH /seals/{id}: accepted: true, version: 1, language, el statement_text exacto almacenado como text y signatory_name (signatory_title opcional). Gestiona 400 SEAL_STATEMENT_REQUIRED y acepta statement_text y statement_hash en los objetos de sello.
  • Un POST /signing-requests o POST /signing-requests/create-and-send con template_id y sin la clave seal_participants ahora hereda los sellos de la plantilla. Envía "seal_participants": [] para crear sin ellos. null también hereda (incluido un cliente que envía null para un campo sin definir).
  • Un valor de seal_participants que no es un array ni null ahora devuelve 400 VALIDATION_ERROR en POST /signing-requests y POST /signing-requests/create-and-send; antes se ignoraba.
  • Si analizas las respuestas de forma estricta, acepta las nuevas claves: dropped en las respuestas de creación, warnings en POST /templates y seal_participants en GET /templates/{id}, PUT /templates/{id} y POST /templates/{id}/duplicate.

v1.39.0

Actualización, 13 de octubre de 2026: Las funciones multidocumento están disponibles para todas las empresas. No se necesita habilitación. Las restricciones de habilitación de las notas de lanzamiento originales que aparecen a continuación describen el despliegue inicial.
Fecha de lanzamiento: 12 de octubre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.39.0

Varios documentos por plantilla y solicitud de firma

Una plantilla o solicitud de firma ahora puede contener hasta 20 documentos, con un límite de 100 MB por conjunto de documentos. Puedes crearla a partir de varias subidas y después añadir, reemplazar, renombrar, reordenar, eliminar y descargar sus documentos uno a uno.
Las funciones multidocumento requieren habilitación para la empresa de tu espacio de trabajo. Esto incluye las rutas /documents, document_ids con más de un id, las anchor tags por documento (anchor_tags[].document_index) y las claves de respuesta documents, documents_version y documents_layout_version. Si tu empresa no está habilitada:
  • Las rutas /documents devuelven 404 NOT_FOUND, exactamente igual que un endpoint desconocido.
  • Las tres claves de respuesta no aparecen.
  • document_index en una anchor tag no se aplica: una creación con un solo documento lo acepta con una advertencia de propiedad desconocida y usa el único documento.
  • POST /templates, POST /signing-requests y POST /signing-requests/create-and-send con más de una entrada en document_ids (los ids repetidos cuentan) devuelven 409 MULTI_DOCUMENT_READ_ONLY antes de crear nada.
Mientras la edición multidocumento está suspendida, las escrituras en una plantilla o solicitud de firma multidocumento devuelven 409 MULTI_DOCUMENT_READ_ONLY. Las lecturas siguen funcionando.

Crear con varios documentos

POST /templates, POST /signing-requests y POST /signing-requests/create-and-send aceptan document_ids. Pasa de 1 a 20 ids de subida temporal de POST /documents, en el orden de los documentos.
  • Envía exactamente un origen de documento: document, document_id o document_ids (o template_id en las rutas de solicitudes de firma). Enviar más de uno devuelve 400 CONFLICTING_DOCUMENT_SOURCE.
  • Un id repetido devuelve 400 DUPLICATE_DOCUMENT_ID. Más de 20 ids devuelven 400 MAX_DOCUMENTS_EXCEEDED. Una subida desconocida o caducada devuelve 400 DOCUMENT_UPLOAD_NOT_FOUND. Un conjunto de más de 100 MB devuelve 413 DOCUMENT_SET_TOO_LARGE.
  • document ya no figura como obligatorio en POST /templates, porque document_id o document_ids pueden sustituirlo.

Anchor tags por documento

Para las empresas habilitadas, las anchor tags admiten un nuevo document_index: la posición (empezando en 1) dentro de document_ids del documento en el que se busca. Solo tiene sentido en solicitudes multidocumento.
  • Con un solo documento, document_index es opcional y su valor predeterminado es 1.
  • Con más de un documento, es obligatorio. Si falta, se devuelve 400 ANCHOR_DOCUMENT_REQUIRED; un valor fuera de rango devuelve 400 VALIDATION_ERROR.

Nuevos endpoints

Cada operación de añadir, reemplazar, renombrar, reordenar y eliminar devuelve el conjunto completo de documentos tras el cambio, con documents, documents_version y documents_layout_version.
  • Un reemplazo debe tener el mismo número de páginas, y cada página debe tener el mismo tamaño con una tolerancia de 1 pt. De lo contrario, devuelve 400 PAGE_COUNT_MISMATCH o 400 DIMENSION_MISMATCH. En una solicitud de firma, un documento colocado con anchor tags solo se reemplaza cuando las anchor tags del reemplazo se resuelven exactamente como están almacenadas. De lo contrario, devuelve 400 ANCHOR_MISMATCH.
  • Una solicitud de firma enviada, finalizada, cancelada o rechazada devuelve 409 DOCUMENT_SET_LOCKED en cualquier escritura de documentos.
  • Un id de documento que no pertenece a la plantilla o solicitud de firma devuelve 404 DOCUMENT_NOT_FOUND. Un id ausente o repetido al reordenar devuelve 400 INVALID_DOCUMENT_ORDER. Eliminar el último documento devuelve 400 MIN_DOCUMENTS_REQUIRED.
  • La descarga devuelve 404 DOCUMENT_ORIGINAL_NOT_AVAILABLE cuando el archivo subido ya no está almacenado, y 404 DOCUMENT_SIGNED_NOT_AVAILABLE antes de que se vincule el certificado.

Documentos en las respuestas

Para las empresas habilitadas, estas respuestas incluyen documents, documents_version y documents_layout_version: GET /templates, GET /templates/{id}, POST /templates, PUT /templates/{id}, GET /signing-requests y GET /signing-requests/{id}.
  • Cada entrada de documents tiene document_id, position, label, original_filename, page_count y document_url_kind. Fuera de las respuestas de listado, cada entrada incluye además un document_url firmado, válido durante 1 hora. Las solicitudes de firma incluyen también document_only_hash, el SHA-256 del documento sellado individualmente una vez vinculado el certificado.
  • Una plantilla o solicitud de firma cuyo conjunto de documentos nunca se ha modificado devuelve su único documento con document_id: null. En las respuestas de listado aparece con documents: [].
  • documents_version aumenta con cada cambio de documentos. documents_layout_version aumenta cuando se añaden, eliminan o reordenan documentos.

Escrituras de campos en plantillas y solicitudes de firma multidocumento

PUT y PATCH en /templates/{id} y /signing-requests/{id} aceptan documents_layout_version junto con las escrituras de campos. Envía el valor de tu última lectura.
  • Es obligatorio para escribir un campo cuando hay más de un documento o la versión de disposición es superior a 1. Si falta, se devuelve 409 DOCUMENTS_LAYOUT_VERSION_REQUIRED.
  • Un valor obsoleto devuelve 409 DOCUMENT_SET_VERSION_CONFLICT. Vuelve a cargar y reintenta.
  • Un valor que no es un entero no negativo devuelve 400 VALIDATION_ERROR con la clave documents_layout_version. Un campo colocado en una página posterior al número de páginas de su documento devuelve 400 VALIDATION_ERROR con la clave page.
  • Un document en línea en PATCH /signing-requests/{id} para una solicitud con más de un documento devuelve 409 MULTI_DOCUMENT_REPLACE_UNSUPPORTED. Usa las rutas /documents en su lugar.

Plantillas con varios documentos

  • POST /templates/{id}/copy copia una plantilla con más de un documento como una plantilla con un único documento combinado. Se conservan el contenido y los números de página absolutos de sus campos. No se copian las etiquetas ni las posiciones de cada documento.

Conflictos de create-and-send

POST /signing-requests/create-and-send puede devolver 409 con MULTI_DOCUMENT_READ_ONLY, SEND_IN_PROGRESS, SEND_EFFECTS_EXIST, ALREADY_SENT, DOCUMENT_SET_BUSY, DOCUMENT_SET_INCONSISTENT, DOCUMENT_SET_VERSION_CONFLICT o DOCUMENT_SET_DISPATCH_STALE. SEND_EFFECTS_EXIST y ALREADY_SENT también pueden incluir signing_request_id. Aparece cuando la solicitud de firma creada por esta llamada se conservó. Recupera esa solicitud en lugar de reintentar, porque un reintento crea una segunda solicitud. Sin signing_request_id, no se conservó ninguna solicitud.

Códigos de error

Códigos nuevos, todos devueltos como { error, code }: El esquema MultiDocumentErrorCode de la referencia de la API enumera los 42 códigos que pueden devolver las rutas multidocumento y las rutas que estas modifican. Un fallo del servidor devuelve 500 con INTERNAL_ERROR o INTERNAL, según la ruta (las rutas /documents usan INTERNAL); ninguno de los dos incluye detalles.

Orden de los participantes

Los firmantes, los aprobadores y los participantes de sello de organización comparten un único espacio de orden. Los destinatarios CC se guardan aparte y nunca ocupan una posición en él.
  • PATCH /templates/{id} y PATCH /signing-requests/{id} mueven un destinatario o un participante de sello mediante inserción con desplazamiento: se renumeran todos los participantes entre la posición antigua y la nueva. Una posición de destino mayor que n devuelve 400 INVALID_SIGNING_ORDER. Un order menor que 1 devuelve 400 INVALID_SIGNING_ORDER para un destinatario y 400 VALIDATION_ERROR para un participante de sello.
  • Un nuevo firmante o aprobador en esas rutas se inserta en order dentro de [1..n+1], o se añade al final cuando se omite order. order: 0 o una posición fuera de ese rango devuelve 400 INVALID_SIGNING_ORDER.
  • Un nuevo participante de sello requiere order como entero positivo. Un order ausente o igual a cero devuelve 400 VALIDATION_ERROR; una posición fuera de [1..n+1] devuelve 400 INVALID_SIGNING_ORDER.
  • En PATCH /templates/{id} y PATCH /signing-requests/{id}, el sello debe pertenecer a tu empresa: el sello de otra empresa devuelve 404 NOT_FOUND. Un sello revocado, eliminado o sustituido por una versión más reciente devuelve 400 SEAL_UNAVAILABLE. Un sello limitado a otro espacio de trabajo devuelve 400 SEAL_UNAVAILABLE en PATCH /signing-requests/{id}. En PATCH /templates/{id} devuelve 404 NOT_FOUND cuando añades un participante de sello o mueves uno (con order); si solo cambias el sello de un participante existente (id y seal_id, sin order), no se comprueba el espacio de trabajo del sello.
  • En una solicitud de firma enviada, PATCH /signing-requests/{id} devuelve 409 ALREADY_SENT, excepto el intercambio de un participante de sello en pausa por un llamador protegido. Eliminar un participante de sello con DELETE /signing-requests/{id}/seal-participants/{participant_id} devuelve 409 SEAL_MUTATION_NOT_ALLOWED.
  • Un cambio de orden que entra en conflicto con un participante de sello ya aplicado devuelve 409 SIGNING_ORDER_LOCKED_APPLIED.
  • POST /signing-requests y POST /signing-requests/create-and-send sin sellos numeran los destinatarios en el orden del array cuando use_signing_order es false o algún destinatario omite order. Con sellos, cada destinatario necesita un order, y destinatarios y sellos deben formar juntos 1..n: un orden ausente o un hueco devuelve 400 INVALID_SIGNING_ORDER, y dos participantes (destinatarios o sellos) con el mismo orden devuelven 400 SEAL_ORDER_COLLISION.
  • PUT /templates/{id} aplica cada entrada de users y deleted_users como una escritura de participante independiente. Si una entrada falla, se conservan las entradas aplicadas antes que ella.
  • POST /templates/{id}/copy conserva el orden de la plantilla de origen, descarta los participantes de sello cuyo sello no está en el ámbito del espacio de trabajo de destino (junto con sus campos) y compacta los participantes restantes a [1..n].

Nombre de la autoridad del sello de organización

Los sellos devueltos por POST /seals, GET /seals, GET /seals/{id} y PATCH /seals/{id} incluyen authority_name, el nombre para el que se atestiguó el sello: la empresa para el ámbito de empresa o el espacio de trabajo protegido; en otro caso, el espacio de trabajo. Es null para los sellos cuyo linaje se creó antes de fijar el nombre; esos sellos certifican con el nombre actual de la empresa.

Otros cambios

  • POST /signing-requests/{id}/resend devuelve 409 SEND_IN_PROGRESS mientras hay un envío de esa solicitud de firma en curso.
  • Corregido: para las empresas habilitadas para la firma multidocumento, crear una solicitud de firma (POST /signing-requests) y crearla y enviarla (POST /signing-requests/create-and-send) ahora devuelven cada participante de sello de organización con su sello (id, linaje, versión, nombre y nombre visible) en seal_participants. Antes esta lista estaba vacía, aunque el sello se guardaba y se aplicaba correctamente en el documento. Los documentos firmados, los certificados y los webhooks no se ven afectados.
  • Solo documentación: la respuesta de POST /signing-requests/create-and-send ahora documenta seal_participants, que ya devolvía. La respuesta de reenvío ahora documenta recipients_suppressed, el número de destinatarios a los que no se envió el recordatorio porque su dirección está suprimida.

Sin cambios

  • PUT /signing-requests/{id} con un id de campo que no pertenece a la solicitud de firma sigue devolviendo 400, también en las solicitudes multidocumento.
  • reminders en POST /signing-requests/create-and-send funciona como antes, también en las solicitudes creadas con document_ids.

Notas de migración

  • El cambio es aditivo. Las solicitudes que nunca usan document_ids, document_index ni las rutas /documents se comportan como antes, y las empresas no habilitadas no ven claves de respuesta nuevas.
  • Si generas un cliente a partir de la especificación OpenAPI: document es opcional en POST /templates, y el esquema del participante de sello en las respuestas de solicitudes de firma ahora se llama SealParticipantApi (antes SealParticipant).
  • Si analizas los códigos de error de forma estricta, acepta los códigos nuevos anteriores.
  • En una empresa habilitada, envía documents_layout_version con las escrituras de campos en plantillas y solicitudes de firma que tienen más de un documento.

v1.38.0

Fecha de lanzamiento: 17 de septiembre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.38.0

Compatibilidad con catalán

El conjunto de idiomas admitidos crece de 14 a 15 con la incorporación del catalán (ca), que se suma a en, es, it, pt, fr, de, el, ru, pl, cs, sv, nl, ro y nb. El nuevo código se acepta en todas las superficies del API que llevan idioma:
  • Configuración del espacio de trabajo: language en PUT /workspace/{workspace_id}/settings (y devuelto por el GET correspondiente)
  • Configuración de la empresa: language en los endpoints de configuración de empresa
  • Idioma de correo por solicitud de firma: el campo language en POST /signing-requests, POST /signing-requests/create-and-send y PATCH / PUT /signing-requests/{id}
  • Términos del firmante: el parámetro de ruta {language} en los endpoints de términos del firmante de empresa y espacio de trabajo (PUT / DELETE)
  • Plantillas de correo predeterminadas: GET /email-templates/defaults/{language}
  • Declaración del sello de organización: statement.language en la creación y actualización del sello, devuelto como statement_language en el sello
Establecer el catalán localiza la experiencia completa del firmante: correos dirigidos al firmante, la interfaz de la ceremonia de firma, la declaración de consentimiento registrada al aceptar los términos y el formato de fechas. El certificado de finalización sigue el idioma del espacio de trabajo, así que establezca el catalán en el espacio de trabajo para obtener un certificado en catalán. Los errores de validación para códigos no admitidos ahora enumeran los 15 idiomas.

Notas de migración

  • El cambio del API es aditivo. Los 14 códigos de idioma existentes se aceptan y se devuelven exactamente igual que antes, y las solicitudes que nunca envían ca se validan como antes.
  • Salvo que la URL de firma incluya un código lang admitido, la página de firma selecciona el primer idioma de la lista de preferencias del navegador del firmante que admite Firma.dev. Un firmante cuyo navegador incluye ca o una variante regional ca- antes que cualquier otro idioma admitido ahora ve la página de firma en catalán. Antes de v1.38.0, el firmante veía el siguiente idioma admitido de la lista o el inglés. Los enlaces de firma enviados por correo electrónico no incluyen un parámetro lang, por lo que este comportamiento también se aplica a los firmantes existentes. Un código lang admitido que añadas a una URL de firma incrustada sigue estableciendo el idioma; se ignora cualquier otro valor.
  • La declaración de consentimiento se resuelve en este orden: términos del espacio de trabajo en el idioma del firmante, términos de la empresa en el idioma del firmante, términos del espacio de trabajo en el idioma configurado del espacio de trabajo, términos de la empresa en el idioma configurado de la empresa y, por último, los términos predeterminados de Firma.dev en el idioma del firmante. Si no existen términos en catalán ni en el idioma configurado aplicable, un firmante que prioriza el catalán ahora acepta la declaración predeterminada en catalán de Firma.dev en lugar de términos personalizados en otro idioma del navegador, como el español. Los términos en el idioma configurado del espacio de trabajo o de la empresa siguen aplicándose cuando están disponibles.
  • Añade términos del firmante en catalán a nivel de empresa o de espacio de trabajo para conservar los términos personalizados para estos firmantes. Usa PUT /company/signer-terms/ca, PUT /workspace/{workspace_id}/signer-terms/ca o la configuración de términos del panel de control.

v1.37.1

Fecha de lanzamiento: 15 de septiembre de 2026 Tipo de lanzamiento: Versión de parche Especificación OpenAPI: Descargar la especificación v1.37.0 (sin cambios en esta versión)

Destinatarios CC

Los endpoints de actualización ahora guardan los destinatarios con "designation": "CC" y los endpoints de lectura ahora los devuelven. Antes de esta versión no hacían ninguna de las dos cosas.

Añadir y actualizar destinatarios CC

  • PUT /templates/{id} (users[]) y PATCH /templates/{id} (user) guardan destinatarios CC. Antes devolvían 400 y 500.
  • PUT /signing-requests/{id} (recipients[]) y PATCH /signing-requests/{id} (recipient) guardan destinatarios CC. Antes, PUT devolvía 200 y contaba el CC en summary.recipients_created sin guardarlo, y PATCH devolvía 500.
  • En PUT /signing-requests/{id}, un destinatario que no se puede guardar ahora aparece en details.recipients de la respuesta 400 en lugar de contarse en summary.recipients_created.
  • Los destinatarios CC existentes se pueden actualizar por id y eliminar mediante deleted_users / deleted_recipients, igual que los firmantes y los aprobadores.
  • first_name y email son obligatorios para un nuevo destinatario CC.
  • designation se compara sin distinguir mayúsculas de minúsculas ("CC", "cc").

Destinatarios CC en las respuestas

Los destinatarios CC se devuelven con "designation": "CC", después de los firmantes y los aprobadores, en:
  • GET /signing-requests/{id}/users
  • GET /templates/{id}/users
  • GET /templates/{id} y GET /templates (recipients)
  • el array recipients de las respuestas de POST /signing-requests, POST /signing-requests/create-and-send y PUT /signing-requests/{id}
Las entradas CC tienen las mismas claves que las demás entradas de ese endpoint. Nunca reciben un enlace de firma, y las claves que solo se aplican a la firma tienen valores neutros (por ejemplo required_fields: [] y ready_to_send: true).

Creación a partir de una plantilla

  • POST /signing-requests y POST /signing-requests/create-and-send con template_id ahora copian los destinatarios CC de la plantilla a la nueva solicitud de firma. Un CC de la plantilla se omite cuando la solicitud ya tiene un CC con el mismo email (sin distinguir mayúsculas de minúsculas).
  • Un destinatario del cuerpo de la solicitud con "designation": "CC" siempre se añade como destinatario CC. Nunca se asocia a un usuario de la plantilla por template_user_id ni por order.

Validación

  • Cambiar un destinatario existente entre CC y Signer o Approver devuelve 400. PATCH /templates/{id} y PATCH /signing-requests/{id} devuelven el mensaje Cannot change designation between CC and Signer/Approver; delete the recipient and create it again, PUT /signing-requests/{id} lo incluye en details.recipients y PUT /templates/{id} devuelve el mensaje genérico Validation errors occurred. Elimina el destinatario y vuelve a crearlo con la nueva designación.
  • No se puede asignar un campo a un destinatario CC. En PUT /signing-requests/{id}, incluido un CC creado en la misma solicitud mediante _temp_id, el error del campo dice Cannot assign fields to CC recipient.; las demás rutas de campos rechazan el id de un CC como destinatario no válido.
  • Actualizar o eliminar un destinatario por id ahora solo encuentra destinatarios que no se han eliminado. Un destinatario ya eliminado se trata como no encontrado en lugar de modificarse.

Notas de migración

  • Sin nuevos endpoints, campos ni valores de enum, por lo que la especificación v1.37.0 sigue siendo válida.
  • Las listas de destinatarios ahora pueden incluir entradas CC. Si tu código trata cada entrada como un firmante, comprueba designation.
  • Las solicitudes de firma creadas a partir de una plantilla con destinatarios CC ahora incluyen esos destinatarios CC, que reciben el documento completado. Elimina los destinatarios CC de la plantilla si no quieres este comportamiento.
  • Si dependías de que PUT /signing-requests/{id} devolviera 200 cuando un destinatario no se guardaba, gestiona la respuesta 400.

v1.37.0

Fecha de lanzamiento: 14 de septiembre de 2026 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.37.0

Sellos de organización

Sellos electrónicos aplicados automáticamente en nombre de una empresa, como participantes en el orden de firma. La configuración, las reglas de ámbito y la salida en el certificado se describen en la guía de Sellos de Organización.

Nuevos endpoints

Participantes de sello

Las solicitudes de firma y las plantillas aceptan un array seal_participants[] junto a recipients[] / users[] en POST /signing-requests, POST /signing-requests/create-and-send, PATCH /signing-requests/{id}, POST /templates y PATCH /templates/{id}. Cada entrada incluye temp_id (identificador del cliente para asignar campos), seal_id y order. Destinatarios y sellos comparten un único espacio de orden contiguo; el orden 1 se aplica al enviar. Los campos que pertenecen a un sello indican seal_participant_temp_id en lugar de un destinatario. Los campos de sello los genera el servidor (read_only: 1, sin destinatario) y los valores proporcionados por el cliente en ellos se ignoran. Las respuestas de solicitudes de firma incluyen ahora seal_participants[].

Intercambio de sello

PATCH /signing-requests/{id} acepta seal_participant: { "id": "<participant-id>", "swap_to_seal_id": "<seal-uuid>" } para mover un participante pausado de una solicitud enviada a otro sello del ámbito. Requiere clave API protegida.

Eventos de webhook

Códigos de error

SEALS_DISABLED, SEAL_NOT_FOUND, SEAL_SCOPE_FORBIDDEN, SEAL_IMAGE_INVALID, SEAL_ALREADY_REVOKED, SEAL_ERASE_NOT_ELIGIBLE, SEAL_MUTATION_NOT_ALLOWED, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_UNAVAILABLE y SEAL_CREATION_DISABLED_EDGE (reservado para el host edge de respaldo; el host principal de la API realiza la creación de sellos).

Notas de migración

  • Puramente aditivo. recipients[], users[] y todos los endpoints existentes no cambian.
  • Sin cambios incompatibles.

v1.36.0

Fecha de lanzamiento: 2026-08-31 Tipo de lanzamiento: Versión menor Especificación OpenAPI: Descargar la especificación v1.36.0

Anchor tags

  • add_white_background en las definiciones de anchor tags: pinta un fondo blanco detrás del campo anclado.

Respuestas de error

  • Los objetos de error incluyen un code legible por máquina.
  • Los fallos de validación devuelven además errors[] con los errores por campo.

Create and send

  • Las respuestas de POST /signing-requests/create-and-send incluyen warnings[] con avisos no bloqueantes.

Notas de migración

  • Puramente aditivo. Sin cambios incompatibles.

v1.35.0

Fecha de lanzamiento: 13 de agosto de 2026 Tipo de versión: Versión Menor Especificación OpenAPI: Descargar spec v1.35.0

Copia de plantilla entre espacios de trabajo

Nuevo endpoint POST /templates/{id}/copy que copia una plantilla a otro espacio de trabajo dentro de la misma empresa. Todos los datos asociados se copian con remapeo correcto de IDs:
  • Configuraciones de la plantilla (vencimiento, orden de firma, correos, etc.)
  • Destinatarios (firmantes, aprobadores) con designaciones preservadas
  • Campos con referencias de required_conditions y visibility_conditions remapeadas
  • Destinatarios en copia (CC)
  • Definiciones de campos personalizados
  • Recordatorios con referencias a destinatarios remapeadas
  • Documento PDF (copia independiente)
Cuerpo de la solicitud:
  • workspace_id (requerido, uuid) - espacio de trabajo destino
  • name (opcional, string, max 255) - nombre para la copia (por defecto, nombre original con sufijo ” (copy)”)
Autorización: requiere una clave API de nivel empresa (protegida). Las claves de espacio de trabajo reciben 403 PROTECTED_KEY_REQUIRED.

v1.33.0

Tipo de versión: Versión Menor Publicado: 2026-08-03 Descargar especificación OpenAPI

Cinco nuevos idiomas

El conjunto de idiomas admitidos crece de 9 a 14: checo (cs), sueco (sv), neerlandés (nl), rumano (ro) y noruego bokmål (nb) se suman a en, es, it, pt, fr, de, el, ru, pl. Los nuevos códigos se aceptan en todas las superficies del API que llevan idioma:
  • Configuración del espacio de trabajo — language en PUT /workspace/{workspace_id}/settings (y devuelto por el GET correspondiente)
  • Configuración de la empresa — language en los endpoints de configuración de empresa
  • Idioma de correo por solicitud de firma — el campo language en POST /signing-requests, POST /signing-requests/create-and-send y PATCH / PUT /signing-requests/{id}
  • Términos del firmante — el parámetro de ruta {language} en los endpoints de términos del firmante de empresa y espacio de trabajo (GET / PUT / DELETE)
  • Plantillas de correo predeterminadas — GET /email-templates/defaults/{language}
Establecer uno de los nuevos idiomas localiza la experiencia completa del firmante: correos dirigidos al firmante, la interfaz de la ceremonia de firma, la declaración de consentimiento registrada al aceptar los términos, el formato de fechas y el certificado de finalización (incluida la representación correcta de los diacríticos checos y rumanos). Los errores de validación para códigos no admitidos ahora enumeran los 14 idiomas.

Guía de migración

No se requiere ninguna acción. El cambio es puramente aditivo: los 9 códigos de idioma existentes se comportan exactamente igual que antes, y los espacios de trabajo o solicitudes de firma que nunca establecieron un idioma no se ven afectados.

v1.32.0

Tipo de versión: Versión Menor Publicado: 2026-07-22 Descargar especificación OpenAPI

Tamaño de fuente explícito por campo

Los campos con texto (text, textarea, email, name, phone, company, title, number, date, signing_date, approval_date, dropdown, url) ahora aceptan un fontSize opcional dentro de format_rules — un entero entre 8 y 48, en píxeles. Consulta el nuevo esquema TextFormatRules; DateFormatRules incorpora la misma propiedad opcional, por lo que un campo de fecha puede llevar tanto dateFormat como fontSize. El valor es un tamaño inicial/máximo, no una garantía: la vista de firma y el PDF sellado comienzan a renderizar el valor del campo con el tamaño explícito y siguen reduciéndolo automáticamente para ajustarse al recuadro del campo cuando el contenido se desborda. Omite la propiedad para el dimensionado automático (el comportamiento anterior, sin cambios). Los valores fuera de rango se limitan a 8-48; los valores no numéricos se ignoran. Los campos signature, initials, checkbox, radio, file y stamp no aceptan tamaño de fuente. Defínelo donde se acepte format_rules — creación/actualización de campos de plantilla y payloads de campos de solicitudes de firma — por ejemplo:

Anchor tags: font_size

Los anchor tags incorporan una propiedad opcional font_size (entero, 8-48). Cuando un anchor se resuelve en un campo, el valor se almacena en el campo creado como format_rules.fontSize y se comporta exactamente como se describe arriba.

Guía de migración

No se requiere ninguna acción. Las propiedades son opcionales y aditivas — los campos sin fontSize se renderizan exactamente igual que antes, y las plantillas y solicitudes de firma existentes no se ven afectadas.

v1.31.0

Tipo de versión: Versión Menor Publicado: 2026-07-14 Descargar especificación OpenAPI

Idioma de correo opcional por solicitud de firma

Nuevo campo opcional language en los endpoints de creación y actualización de solicitudes de firma: POST /signing-requests, POST /signing-requests/create-and-send y PATCH / PUT /signing-requests/{id}. Establécelo en uno de en, es, it, pt, fr, de, el, ru, pl y todos los correos dirigidos al firmante de esa solicitud de firma — invitación, recordatorios, verificación OTP, finalización y CC, expiración, cancelación y rechazo — junto con su formato de fecha, usan ese idioma. El campo admite null y es aditivo: language controla los correos dirigidos al firmante de toda la solicitud.

Guía de migración

No se requiere ninguna acción. El campo es opcional: omítelo o envía null y el comportamiento no cambia; los correos recurren al idioma del espacio de trabajo, luego al de la empresa y luego a en. Las solicitudes de firma existentes no se ven afectadas.

v1.30.0

Tipo de versión: Versión Menor Publicado: 2026-07-08 Descargar especificación OpenAPI

Recuperar las marcas del firmante como imágenes

Cuatro nuevos endpoints de solo lectura devuelven las marcas capturadas de un firmante de forma individual, separadas del PDF firmado:
  • GET /signing-requests/{id}/signers/{signer_id}/signature — la firma adoptada por el firmante
  • GET /signing-requests/{id}/signers/{signer_id}/initials — las iniciales adoptadas por el firmante
  • GET /signing-requests/{id}/signers/{signer_id}/stamps/{field_id} — un sello para un campo de sello específico
  • GET /signing-requests/{id}/signers/{signer_id}/files/{field_id} — un archivo que el firmante subió a un campo de archivo
Los endpoints de firma, iniciales y sello devuelven la marca como una URI de datos PNG en base64 (data:image/png;base64,...), utilizable directamente en un <img src>. El endpoint de archivo devuelve una URL de descarga pre-firmada de corta duración (300 segundos). Un firmante adopta una firma y unas iniciales, aplicadas a todos sus campos de ese tipo, por lo que esos endpoints no reciben field_id; los sellos y archivos son por campo y requieren field_id (obtén los IDs de campo desde GET /signing-requests/{id}/fields). Por defecto se superpone un marco de ID de firmante en las imágenes devueltas; pasa include_frame=false para obtener la marca sin marco. Estos endpoints tienen un límite de 60 solicitudes por minuto. La validez legal de una firma reside en el PDF sellado y su certificado de finalización, no en una imagen recuperada.

Guía de Migración

Sin cambios importantes. Estos son endpoints nuevos y aditivos; las integraciones existentes no requieren cambios.

v1.29.0

Tipo de versión: Versión Menor Publicado: 2026-07-06 Descargar especificación OpenAPI

Subida de documentos en dos pasos

Un nuevo endpoint POST /documents permite subir documentos más grandes que el límite de tamaño de solicitud en línea. En lugar de enviar un documento codificado en base64 en el cuerpo de la solicitud, ahora puedes:
  1. Llamar a POST /documents con los metadatos del archivo para recibir una URL de subida pre-firmada
  2. Hacer PUT de los bytes del archivo directamente a la URL de subida (soporta hasta 50MB)
  3. Pasar el document_id devuelto en tu solicitud POST /signing-requests o POST /signing-requests/create-and-send
Esto es obligatorio para documentos mayores de aproximadamente 5MB. Los documentos más pequeños pueden seguir usando el campo document en línea.

Nuevo campo de solicitud: document_id

El endpoint POST /signing-requests/create-and-send ahora acepta document_id como alternativa a document y template_id. Los tres campos son mutuamente excluyentes: proporciona exactamente uno.

Aumento del límite de tamaño de documento

El tamaño máximo de documento se ha aumentado de 20MB a 50MB al usar el flujo de subida en dos pasos.

Guía de Migración

Sin cambios importantes. Las integraciones existentes que usan document o template_id en línea siguen funcionando sin cambios. Para subir documentos más grandes, adopta el flujo en dos pasos mediante POST /documents.

v1.28.0

Tipo de versión: Versión Menor Publicado: 2026-07-05 Descargar especificación OpenAPI

Ejemplos de código del SDK de TypeScript

Cada endpoint en la referencia de la API ahora incluye un ejemplo de código listo para copiar y pegar para el cliente oficial de TypeScript @firma-dev/sdk, que muestra la llamada tipada exacta para esa operación. Consulta la nueva guía del SDK de TypeScript para instalar el cliente y comenzar.

Cambios en la superficie de referencia

Los siguientes endpoints se eliminaron de la referencia de la API porque no forman parte de la superficie de API de socios documentada:

Guía de Migración

No se requieren cambios para las integraciones que usan los endpoints de la API de socios documentados aquí. Si hacías referencia a los endpoints de solicitud de firma incrustada, usa en su lugar las guías de Incrustables; el editor incrustado sigue dependiendo de esos endpoints. Si usabas los endpoints legados de /documents, migra a los endpoints de plantilla (POST /templates) y de solicitud de firma (POST /signing-requests).

v1.27.0

Tipo de versión: Versión de Parche Publicado: 2026-06-29 Descargar especificación OpenAPI

Campos de configuración ahora documentados en las respuestas

Esta versión documenta campos de configuración que la API ya devolvía. Todos los cambios son aditivos y compatibles con versiones anteriores: no cambió ningún comportamiento de la API, solo se actualizó la especificación OpenAPI para reflejar lo que los endpoints ya enviaban.

Configuración de solicitud de firma

El objeto de configuración devuelto por los endpoints de solicitud de firma (POST /signing-requests, POST /signing-requests/create-and-send, GET /signing-requests, GET /signing-requests/{id}, PUT /signing-requests/{id}, PATCH /signing-requests/{id}) ahora documenta cuatro campos adicionales:

Configuración de plantilla

El objeto de configuración devuelto por los endpoints de plantilla (POST /templates, PUT /templates/{id}, PATCH /templates/{id}, GET /templates, GET /templates/{id}, POST /templates/{id}/replace-document) ahora documenta el campo show_qr_code. La configuración de plantilla cubre las mismas opciones que la configuración de solicitud de firma, excepto los campos de identidad del firmante (identity_editable_fields, notify_identity_change_email), que aplican solo a las solicitudes de firma.

Respuestas de cancelación y reenvío

Nuevos esquemas

Dos nuevos esquemas dividen las formas de configuración que difieren entre endpoints, de modo que cada respuesta documenta exactamente los campos que devuelve:

Guía de Migración

Sin cambios importantes. Estas son adiciones únicamente de documentación que describen campos que la API ya devolvía. Las integraciones existentes no se ven afectadas. Si analizas objetos de configuración, ahora puedes contar con los campos documentados show_qr_code, allow_presigning_download, identity_editable_fields y notify_identity_change_email, y con emails_sent / recipients_failed en las respuestas de cancelación y reenvío.

v1.26.0

Tipo de versión: Versión Menor Publicado: 2026-06-23 Descargar especificación OpenAPI

Configuración del espacio de trabajo: cuatro nuevos campos

Cuatro campos ahora están disponibles en GET /workspace/{workspace_id}/settings y PUT /workspace/{workspace_id}/settings:

Estructura de anulaciones de etiquetas de botón

Claves de botón personalizables: common.finish, signing.approveAndFinish, signing.nextRequiredField, signing.saveAndFinishLater, signing.decline.confirm, signing.decline.title, signing.decline.cancel, signing.finishAnyway, signing.goBack. Los valores se sanean en el servidor (se elimina el HTML, máximo 200 caracteres). Los valores vacíos o que solo contienen espacios en blanco se ignoran.

v1.25.2

Tipo de versión: Versión de Parche Publicado: 2026-06-18 Descargar especificación OpenAPI

Validación más estricta para las anulaciones de campos de plantilla

Al crear una solicitud de firma a partir de una plantilla, cualquier campo proporcionado que no coincida con un campo en esa plantilla ahora se rechaza con 400 VALIDATION_ERROR en lugar de ignorarse en silencio. Anteriormente ese campo se descartaba y la solicitud igualmente tenía éxito, por lo que un identificador mal escrito significaba que el campo simplemente nunca aparecía en el documento sin ningún error. Un campo proporcionado coincide con un campo de plantilla mediante template_field_id, variable_name o variable_defined_name. El error nombra el/los campo(s) infractor(es):
Aplica a POST /signing-requests y POST /signing-requests/create-and-send. Migración: asegúrate de que cada campo que envíes en una creación basada en plantilla haga referencia a un campo de plantilla existente. Si dependías de que los campos adicionales/no coincidentes se ignoraran, elimínalos.

Tipos de campo sin distinción de mayúsculas y minúsculas

Los valores de type de campo ahora se normalizan sin distinguir mayúsculas y minúsculas. "Initials", "Signature", "TextArea", etc. se resuelven a su tipo canónico (initial, signature, text_area) en lugar de rechazarse como inválidos. Los valores en minúsculas no cambian.

v1.25.1

Tipo de versión: Versión de Parche Publicado: 2026-06-14 Descargar especificación OpenAPI

Respuestas de error precisas para create-and-send

POST /signing-requests/create-and-send anteriormente devolvía un 500 genérico cada vez que el paso de envío rechazaba una solicitud, ocultando el motivo real. Ahora devuelve el estado accionable por el cliente (400, 402 o 422) con un code legible por máquina y el detalle correspondiente:
  • 400 VALIDATION_ERROR — falló la validación de la solicitud o del envío (por ejemplo, a un firmante le falta información obligatoria); la respuesta incluye validation_errors, field_errors o details identificando qué corregir.
  • 402 INSUFFICIENT_CREDITS — créditos insuficientes para enviar; current_credits informa el saldo.
  • 422 RECIPIENT_EMAIL_SUPPRESSED (nuevo) — la dirección de correo de un destinatario está suprimida (previamente rebotada o marcada como spam) y no se le puede enviar.
Los fallos genuinos del lado del servidor siguen devolviendo 500. Cuando falla el paso de envío, la solicitud de firma creada parcialmente se revierte, por lo que no queda ningún borrador huérfano. Guía de migración: No se requiere ninguna acción para los clientes que ya tratan cualquier respuesta no-2xx como un fallo. Si antes tratabas de forma especial el 500 opaco de este endpoint, cambia a ramificar según el estado HTTP / code: 400 y 422 significan “corrige la solicitud y vuelve a intentar”, 402 significa “agrega créditos”.

v1.25.0

Tipo de versión: Versión Menor Publicado: 2026-06-14 Descargar especificación OpenAPI

Colores de marca del editor

La configuración de apariencia ahora incluye cinco colores de marca adicionales que dan tema a los editores incrustados (los editores de plantilla y de solicitud de firma que incrustas en tus propias páginas):
  • color_accent — color de acento para resaltados, pestañas activas, interruptores y controles principales en el marco del editor.
  • color_accent_fg — color de primer plano (texto/icono) mostrado sobre superficies de acento.
  • color_canvas — el color del entorno del lienzo del documento detrás de la página.
  • color_muted — color de superficie atenuada (separadores, estados de hover, pistas de interruptores).
  • color_muted_fg — color de texto atenuado.
Estos se suman a los seis campos de color existentes, por lo que los endpoints de configuración ahora contienen once campos color_*:
  • GET/PUT /company/settings y GET/PUT /workspace/{workspace_id}/settings aceptan y devuelven los cinco nuevos campos. Cada uno es una cadena hexadecimal #rrggbb anulable; null significa heredar (espacio de trabajo → empresa → predeterminado de Firma).
  • El objeto color_palette resuelto devuelto en los payloads del editor incrustado ahora contiene once claves (las seis existentes más accent, accent_fg, canvas, muted, muted_fg). Cuando no está establecido, muted toma como predeterminado el color card resuelto y muted_fg se deriva para garantizar la legibilidad, por lo que la paleta siempre está completamente poblada.
Los valores del espacio de trabajo anulan los valores de la empresa; los valores no establecidos recurren a los valores predeterminados de Firma, por lo que las integraciones existentes se renderizan sin cambios. Guía de migración: No se requiere ninguna acción. Los cinco campos son aditivos y anulables. Para personalizar la marca de los editores incrustados, envía cualquiera de los nuevos campos color_* (hexadecimal #rrggbb válido, o null para borrar) al endpoint de configuración de empresa o de espacio de trabajo.

v1.24.0

Tipo de versión: Versión Menor Publicado: 2026-06-09 Descargar especificación OpenAPI

Claves API de prueba del espacio de trabajo

Los espacios de trabajo ahora exponen una clave API en modo de prueba junto a la clave live existente. Las solicitudes autenticadas con una clave de prueba no consumen créditos y producen solicitudes de firma marcadas como prueba y con marca de agua.
  • POST /workspaces ahora provisiona un par de claves live + test y devuelve tanto api_key (live) como el nuevo campo test_api_key.
  • GET /workspaces/{id} y GET /workspaces ahora devuelven tanto api_key como test_api_key.
  • POST /workspaces/{id}/api-key/regenerate y /api-key/expire aceptan un key_type opcional ("live" o "test", predeterminado "live"). Regenerar un tipo de clave ya no afecta al otro.
  • Los espacios de trabajo existentes creados a través de la API se completan retroactivamente con una clave de prueba.
Todos los cambios son aditivos y compatibles con versiones anteriores: los consumidores que leen api_key siguen funcionando sin cambios. Guía de migración: No se requiere ninguna acción. Para usar el modo de prueba, lee test_api_key desde cualquier respuesta de creación/obtención de espacio de trabajo y envíala como la clave de Authorization para las solicitudes que quieras ejecutar en modo de prueba.

v1.23.0

Tipo de versión: Versión Menor Publicado: 2026-06-04 Descargar especificación OpenAPI

Términos del Firmante

Nuevos endpoints de Términos del Firmante te permiten gestionar declaraciones de consentimiento personalizadas del firmante a nivel de empresa y de espacio de trabajo:
  • Los endpoints GET listan los términos del firmante de empresa y de espacio de trabajo
  • Los endpoints PUT crean o actualizan los términos del firmante por idioma a nivel de empresa y de espacio de trabajo
  • Los endpoints DELETE eliminan los términos del firmante de empresa y de espacio de trabajo

Configuración de Empresa

Los nuevos endpoints GET /company/settings y PUT /company/settings exponen la configuración de la empresa, incluyendo la puerta de aceptación de términos.

Cambios de Esquema

  • Esquema de configuración de empresa: se agregó require_terms_acceptance (boolean)
  • Esquema de configuración de espacio de trabajo: se agregó require_terms_acceptance (boolean, anulable). Usa null para heredar la configuración de la empresa.

Guía de Migración

Sin cambios importantes. Esta versión es aditiva y no se requiere ninguna acción para las integraciones existentes.

v1.22.1

Tipo de versión: Versión de Parche Publicado: 2026-06-02 Descargar especificación OpenAPI

Eliminación de dominio de correo

DELETE /company/domains/{id} y DELETE /workspace/{workspace_id}/domains/{id} ahora tienen éxito cuando el objetivo es el dominio principal del espacio de trabajo o su único dominio. Anteriormente esto devolvía 400 "Cannot delete primary domain". Después de la eliminación, el correo saliente recurre al remitente predeterminado de la empresa, o al predeterminado de la plataforma si no hay ninguno configurado. Para volver a usar un dominio de envío personalizado, agrega y verifica un nuevo dominio, y luego establécelo como principal.

Guía de Migración

Sin cambios importantes. Las respuestas 400 "Cannot delete primary domain" y “cannot delete the only domain” se eliminan de ambos endpoints DELETE de dominio; ahora devuelven 200 en esos casos. Las integraciones que trataban ese 400 de forma especial pueden eliminar ese manejo.

v1.22.0

Tipo de versión: Versión Menor Publicado: 2026-05-30 Descargar especificación OpenAPI

Endpoint de Eliminación de Solicitud de Firma

Nuevo endpoint DELETE /signing-requests/{id} para eliminar solicitudes de firma sin enviar (borrador). Este endpoint solo funciona en solicitudes de firma que aún no se han enviado. Para solicitudes de firma enviadas, usa en su lugar el endpoint de cancelación existente. Respuesta:
  • 200 con signing_request_id y deleted_on en caso de éxito
  • 409 ALREADY_SENT si la solicitud de firma ya se ha enviado
  • 404 si no se encuentra o ya se eliminó

Nuevo Evento de Webhook

  • signing_request.deleted se dispara cuando una solicitud de firma se elimina a través de la API

Guía de Migración

Sin cambios importantes. El nuevo método DELETE en /signing-requests/{id} es puramente aditivo. Las integraciones existentes no se ven afectadas.

v1.21.1

Tipo de versión: Versión de Parche Publicado: 2026-05-19 Descargar especificación OpenAPI

Gestión de Webhooks del Espacio de Trabajo

El endpoint PATCH /workspaces/{id} ahora admite dos nuevos campos para gestionar los webhooks a nivel de espacio de trabajo a través de la API:
  • webhook_enabled (boolean) - Habilita o deshabilita los webhooks a nivel de espacio de trabajo. Cuando se establece en true por primera vez, se genera automáticamente un secret de webhook.
  • ignore_company_webhooks (boolean) - Si es true, los webhooks a nivel de empresa no se dispararán para eventos en este espacio de trabajo.
Anteriormente, estas configuraciones solo podían configurarse a través de la interfaz del panel.

Cambios de Esquema

  • Cuerpo de la solicitud de PATCH /workspaces/: se agregaron webhook_enabled (boolean, opcional) e ignore_company_webhooks (boolean, opcional)
  • Respuesta de PATCH /workspaces/: ahora incluye webhook_enabled, webhook_secret, webhook_secret_rotated_at, webhook_secret_created_at e ignore_company_webhooks

Guía de Migración

Sin cambios importantes. Las configuraciones de webhook de espacio de trabajo existentes no se ven afectadas. Usa PATCH /workspaces/{id} con webhook_enabled: true para habilitar los webhooks de espacio de trabajo a través de la API en lugar del panel.

v1.21.0

Tipo de versión: Versión Menor Publicado: 2026-05-14 Descargar especificación OpenAPI

Nuevas Configuraciones

  • email_local_part (string, anulable) - Personaliza la parte local (antes del @) de los correos de firma salientes cuando se usa un dominio personalizado verificado. Disponible en dos niveles:
    • Configuración de Empresa (GET/PATCH /company) - Establece el valor predeterminado para todos los espacios de trabajo. Cadena con valor predeterminado "support".
    • Configuración de Espacio de Trabajo (GET/PUT /workspace/{id}/settings) - Anula el valor predeterminado de la empresa. Cadena anulable (null hereda de la empresa).
Los correos se envían desde {email_local_part}@{tu-dominio-personalizado}. Por ejemplo, establecer email_local_part en "noreply" envía correos desde noreply@tudominio.com en lugar de support@tudominio.com. Validación: alfanumérico en minúsculas, puntos, guiones y guiones bajos. Debe comenzar y terminar con un carácter alfanumérico. 1-64 caracteres. Patrón: ^[a-z0-9]([a-z0-9._-]*[a-z0-9])?$

Cambios de Esquema

  • Esquema de Company: se agregó email_local_part (string, predeterminado "support")
  • Esquema de configuración de espacio de trabajo: se agregó email_local_part (string, anulable)

Guía de Migración

Sin cambios importantes. Las configuraciones existentes siguen enviando correos desde support@{dominio} de forma predeterminada. Establece email_local_part a nivel de empresa o de espacio de trabajo para personalizar la dirección del remitente.

v1.20.0

Tipo de versión: Versión Menor Publicado: 2026-05-12

Nuevas Configuraciones

  • disable_guided_navigation (boolean, anulable) - Deshabilita el desplazamiento automático al siguiente campo obligatorio durante la firma. Disponible en cuatro niveles:
    • Configuración de Empresa (GET/PUT /company/settings) - Establece el valor predeterminado para todos los espacios de trabajo. Boolean (no anulable).
    • Configuración de Espacio de Trabajo (GET/PUT /workspace/{id}/settings) - Anula el valor predeterminado de la empresa. Boolean o null (null hereda de la empresa).
    • Plantilla (POST/PATCH /templates) - Se copia a las solicitudes de firma creadas a partir de esta plantilla. Boolean o null.
    • Solicitud de Firma (POST/PATCH /signing-requests) - Anulación de mayor prioridad. Boolean o null (null hereda del espacio de trabajo/empresa).
La configuración sigue el mismo patrón de cascada que require_otp_verification: el nivel de solicitud de firma tiene prioridad, luego el espacio de trabajo, luego la configuración de la empresa.

Cambios de Esquema

  • Esquema de configuración de empresa: se agregó disable_guided_navigation (boolean)
  • Esquema de configuración de espacio de trabajo: se agregó disable_guided_navigation (boolean, anulable)
  • Esquema de configuración de plantilla: se agregó disable_guided_navigation (boolean, anulable)
  • Esquema de configuración de solicitud de firma: se agregó disable_guided_navigation (boolean, anulable)

Guía de Migración

Sin cambios importantes. Las solicitudes de firma y plantillas existentes siguen funcionando como antes (desplazamiento automático habilitado de forma predeterminada). Para deshabilitar el desplazamiento automático, establece disable_guided_navigation: true en el nivel deseado. Descargar especificación OpenAPI

v1.19.0

Tipo de versión: Versión Menor Publicado: 2026-05-12

Nuevos Endpoints

  • POST /company/logo - Sube una imagen de logotipo de empresa (PNG o JPEG, máximo 2MB). El logotipo aparece en los certificados de firma y correos electrónicos.
  • DELETE /company/logo - Elimina el logotipo de la empresa. Los certificados recurren al predeterminado de Firma.
  • POST /workspaces/{id}/logo - Sube un logotipo específico del espacio de trabajo que anula el logotipo de la empresa para ese espacio de trabajo.
  • DELETE /workspaces/{id}/logo - Elimina el logotipo del espacio de trabajo. Recurre al logotipo de la empresa.

Cambios de Esquema

  • El esquema de Workspace ahora incluye icon_url (string, anulable) - una URL públicamente accesible a la imagen del logotipo del espacio de trabajo
  • icon_url de Company ahora es de solo lectura en las solicitudes PATCH/PUT. Usa el nuevo endpoint POST /company/logo para gestionar los logotipos.

Guía de Migración

  • Si establecías icon_url directamente mediante PATCH /company o PATCH /workspaces/{id}, cambia a los nuevos endpoints POST .../logo en su lugar. El campo icon_url ya no se acepta en los cuerpos de solicitud de actualización.
  • icon_url en las respuestas GET ahora devuelve una URL públicamente accesible en lugar de una referencia interna.
Descargar especificación OpenAPI

v1.18.0

Fecha de lanzamiento: 5 de mayo de 2026

Nuevas Funcionalidades

Campos Editables de Identidad

Las solicitudes de firma ahora admiten la edición de identidad por campo y por firmante. Cuando se configura, los firmantes ven un diálogo de confirmación antes de firmar donde pueden revisar y editar campos de identidad específicos (nombre, empresa, cargo, teléfono, dirección). Nueva propiedad de configuración: Claves de campo válidas: name, company, title, phone, address Anulación por destinatario mediante identity_editable_fields en el objeto del destinatario:
  • null - usar el predeterminado de la solicitud
  • [] - deshabilitado para este firmante
  • ["name", "company"] - campos personalizados para este firmante
Ejemplo:
En este ejemplo, John hereda el predeterminado de la solicitud (nombre + empresa editables), mientras que Jane tiene la edición de identidad explícitamente deshabilitada. Nuevo evento de webhook: signing_request.recipient.identity_changed ya está disponible como un evento de webhook estándar. Suscríbete a él en tu configuración de webhook para recibir notificaciones cuando un firmante modifica su identidad durante la firma.

Campos de Datos Precompletados Editables

Los campos de datos precompletados ahora pueden ser opcionalmente editables por los firmantes. Anteriormente, todos los campos con prefilled_data establecido se bloqueaban automáticamente como de solo lectura. Una nueva propiedad prefilled_editable te permite controlar este comportamiento. Cuando prefilled_editable es true, el valor del campo sigue completándose automáticamente desde los datos del destinatario, pero el firmante puede modificarlo durante el proceso de firma. Disponible en:
  • Campos de plantilla (PATCH /templates/{id}, PUT /templates/{id})
  • Campos de solicitud de firma (POST /signing-requests, POST /signing-requests/create-and-send)
  • Objetos de respuesta de campo (GET /signing-requests/{id})
Ejemplo: crear una solicitud de firma con un campo precompletado editable:

Validación del Origen del Valor de Campo

La API ahora valida que los campos usen solo una fuente de valor a la vez. Las solicitudes que combinan read_only_value, prefilled_data y un value explícito en el mismo campo devolverán un 400 VALIDATION_ERROR. Esta validación aplica a:
  • POST /signing-requests
  • POST /signing-requests/create-and-send
  • PATCH /templates/{id} (creación y actualización de campos)
  • PUT /templates/{id} (upsert de campos)

Precedencia de Valores

Cuando prefilled_editable es true y tanto un value explícito como prefilled_data están establecidos en un campo, el valor explícito tiene precedencia sobre los datos del destinatario auto-completados.

Guía de Migración

Sin cambios importantes. Las nuevas funcionalidades son opcionales:
  • La edición de identidad está deshabilitada de forma predeterminada (identity_editable_fields: null). Establécela en un array de claves de campo para habilitarla.
  • Los campos de datos precompletados existentes permanecen bloqueados (de solo lectura) de forma predeterminada. Establece prefilled_editable: true en format_rules para hacerlos editables.

v1.17.0

Fecha de lanzamiento: 30 de abril de 2026 Descargar especificación OpenAPI

Nuevas Funcionalidades

Personalización de Color para la Experiencia de Firma

Seis nuevos campos de color anulables te permiten personalizar la apariencia de la experiencia de firma tanto a nivel de empresa como de espacio de trabajo. Los colores siguen una cascada de 3 niveles: los predeterminados de Firma se usan a menos que se anulen a nivel de empresa, y los colores de la empresa se usan a menos que se anulen a nivel de espacio de trabajo. Nuevos campos en Company (GET /company, PUT /company, PATCH /company): Nuevos campos en Workspace Settings (GET /workspace/{workspace_id}/settings, PUT /workspace/{workspace_id}/settings): Los mismos seis campos están disponibles en la configuración del espacio de trabajo. Establece un valor para anular el predeterminado de la empresa, o establece null para heredar de la empresa.

Esquema ColorPalette

Un nuevo esquema ColorPalette representa la paleta de colores resuelta aplicada a la experiencia de firma. Todos los valores son cadenas de color hexadecimal (#rrggbb).

Guía de Migración

De v1.16.0 a v1.17.0: Este es un cambio aditivo sin efectos disruptivos. Las integraciones existentes siguen funcionando sin modificaciones.
  • Los seis campos de color son null de forma predeterminada, lo que preserva la apariencia predeterminada existente de Firma.
  • Para personalizar los colores, establece valores hexadecimales en la configuración de la empresa (predeterminados para toda la empresa) o en la configuración del espacio de trabajo (anulaciones por espacio de trabajo).
  • La cascada de colores es: predeterminados de Firma -> anulaciones de empresa -> anulaciones de espacio de trabajo. Cada nivel solo anula los campos que están explícitamente establecidos (no nulos).

v1.16.0

Fecha de lanzamiento: 27 de abril de 2026 Descargar especificación OpenAPI

Nuevas Funcionalidades

Descarga del Documento de la Solicitud de Firma

Un nuevo endpoint recupera una URL de descarga para el documento de una solicitud de firma. Para las solicitudes de firma completadas, la URL apunta al PDF final firmado. Para las solicitudes en progreso, canceladas, rechazadas o expiradas, la URL apunta a un PDF de instantánea parcial que captura el estado del documento en el momento de la última acción del firmante. Endpoint: GET /signing-requests/{id}/download Campos de respuesta: Comportamiento según el estado: Las instantáneas parciales se generan bajo demanda y se almacenan en caché. La primera solicitud puede devolver 503 con un encabezado Retry-After mientras se genera el PDF; vuelve a intentarlo después del intervalo indicado. Expiración de URL: El download_url es una URL pre-firmada. Vuelve a llamar al endpoint después de expires_at para obtener una URL nueva.

Configuración de Marca de Agua de Descarga Parcial

Una nueva configuración de espacio de trabajo show_partial_watermark controla si las descargas de PDF parciales incluyen una marca de agua diagonal “EN PROGRESO — AÚN NO EJECUTADO”. Deshabilitada de forma predeterminada. Se puede establecer a nivel de empresa (predeterminado para todos los espacios de trabajo) o anular por espacio de trabajo. Endpoint: PUT /workspace/{workspace_id}/settings

Guía de Migración

De v1.15.3 a v1.16.0: Este es un cambio aditivo sin efectos disruptivos. Las integraciones existentes siguen funcionando sin modificaciones.
  • El endpoint de descarga es puramente opcional. No cambia ningún comportamiento existente.
  • Llama a GET /signing-requests/{id}/download — maneja 503 con Retry-After hasta que el documento esté listo.

v1.15.3

Fecha de lanzamiento: 27 de abril de 2026 Descargar especificación OpenAPI

Alias de campos limpios para GET /signing-requests//fields

El endpoint de campos ahora devuelve campos limpios y con nombres consistentes junto a los nombres de columna de base de datos existentes: Adicionalmente, required, read_only y date_signing_default ahora devuelven booleanos (true/false) en lugar de enteros (0/1). Todos los campos obsoletos permanecen en la respuesta por compatibilidad con versiones anteriores y se eliminarán en una futura versión mayor.

Guía de migración

Actualiza tu análisis de campos para usar los nombres nuevos. Los nombres obsoletos siguen funcionando:

v01.15.02

Fecha de Lanzamiento: 23 de abril de 2026
Descargar especificación OpenAPI

Corrección de Errores

Tipos de Campo de Create-and-Send Ampliados

Al esquema fields del endpoint create-and-send le faltaban varios tipos de campo que ya eran compatibles con el backend y disponibles a través de anchor_tags. Se han agregado los siguientes tipos al enum fields.type:
  • dropdown (con la propiedad dropdown_options)
  • radio_buttons
  • text_area
  • url
  • file
Estos tipos ya eran aceptados por la API y eran completamente funcionales. Esta actualización alinea la especificación OpenAPI con el comportamiento real del backend. Endpoint afectado:
  • POST /signing-requests/create-and-send — enum fields[].type

v01.15.01

Fecha de Lanzamiento: 17 de abril de 2026
Descargar especificación OpenAPI

Corrección de Errores

Enum de Idioma Actualizado

Se agregaron los códigos de idioma faltantes ru (ruso) y pl (polaco) a todos los campos enum de idioma en la API. Estos idiomas ya eran compatibles con la plataforma pero faltaban en la especificación OpenAPI, lo que impedía a los usuarios de la API establecerlos a través de endpoints documentados. Endpoints afectados:
  • PUT /workspace/{workspace_id}/settings — campo language
  • PUT /company y PATCH /company — campo language
  • GET /email-templates/defaults — parámetro de consulta language

v01.15.00

Fecha de Lanzamiento: 16 de abril de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Webhooks con Alcance de Espacio de Trabajo

Los webhooks ahora pueden tener alcance a espacios de trabajo individuales en lugar de aplicarse a toda la empresa. Esto permite que diferentes espacios de trabajo tengan configuraciones de webhook y secretos de firma independientes.
  • Parámetro workspace_id en la creación de webhooks — Pasa un workspace_id opcional al crear un webhook para limitarlo a un espacio de trabajo específico. Omitirlo crea un webhook a nivel de empresa (comportamiento existente).
  • Filtro workspace_id en el listado de webhooks — Filtra la lista de webhooks por espacio de trabajo. Cuando se omite, solo se devuelven los webhooks a nivel de empresa.
  • Campo de espacio de trabajo ignore_company_webhooks — Los espacios de trabajo pueden excluirse de recibir eventos de webhook a nivel de empresa estableciendo este indicador en true.

Gestión de Secretos de Webhook de Espacio de Trabajo

Dos nuevos endpoints para gestionar los secretos de firma de webhook a nivel de espacio de trabajo:
  • POST /workspaces/{id}/webhooks/rotate-secret — Genera un nuevo secret de firma de webhook para el espacio de trabajo. El secreto anterior sigue siendo válido durante un período de gracia de 7 días.
  • GET /workspaces/{id}/webhooks/secret-status — Devuelve el estado del secret de webhook del espacio de trabajo, incluyendo fecha de creación, fecha de rotación e información del período de gracia.

Campos de Webhook en la Respuesta del Espacio de Trabajo

La respuesta GET del espacio de trabajo ahora incluye campos relacionados con webhooks:
  • webhook_enabled — Si los webhooks a nivel de espacio de trabajo están habilitados
  • webhook_secret — El secret de firma de webhook actual
  • webhook_secret_created_at — Cuándo se creó el secret actual
  • webhook_secret_rotated_at — Cuándo se rotó el secret por última vez
  • ignore_company_webhooks — Si el espacio de trabajo ignora los eventos de webhook a nivel de empresa

Cambios

  • Se agregó el parámetro opcional workspace_id a POST /webhooks y GET /webhooks
  • Se agregaron 5 nuevos campos al esquema Workspace: webhook_enabled, webhook_secret, webhook_secret_created_at, webhook_secret_rotated_at, ignore_company_webhooks
  • Se agregaron 2 nuevos endpoints: POST /workspaces/{id}/webhooks/rotate-secret, GET /workspaces/{id}/webhooks/secret-status
  • Se aplicó protección SSRF a la validación de URL de webhook

Guía de Migración

De v01.14.00 a v01.15.00: Este es un cambio aditivo sin efectos disruptivos. Las integraciones existentes siguen funcionando sin modificaciones.
  • Los webhooks a nivel de empresa siguen siendo el predeterminado. El parámetro workspace_id es opcional tanto en la creación como en el listado.
  • Los webhooks existentes no se ven afectados. Los nuevos campos de espacio de trabajo en la respuesta de espacio de trabajo son predeterminadamente webhook_enabled: false e ignore_company_webhooks: false.
  • Para adoptar los webhooks de espacio de trabajo, crea un webhook con un workspace_id y luego usa el endpoint de rotación de secret del espacio de trabajo para generar un secret de firma para ese espacio de trabajo.

v01.14.00

Fecha de Lanzamiento: 12 de abril de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Designaciones de Destinatario

El campo designation en los destinatarios de solicitud de firma y plantilla ahora acepta tres valores: "Signer", "Approver" y "CC".
  • Signer — Firma el documento (comportamiento existente, sigue siendo el predeterminado)
  • Approver — Aprueba el documento usando campos específicos de aprobación. Los aprobadores no firman pero deben completar todos los campos de aprobación asignados antes de que la solicitud pueda finalizar.
  • CC — Recibe una copia completada del documento firmado. Los destinatarios en CC no pueden firmar ni tener campos asignados.
Aún se requiere al menos un Signer por solicitud de firma.

Tipos de Campo de Aprobación

Tres nuevos tipos de campo para destinatarios Approver:
  • approval_signature — Un sello de aprobación colocado por el aprobador
  • approval_checkmark — Una casilla de aprobación
  • approval_date — Fecha auto-completada cuando el aprobador aprueba
Estos tipos de campo solo se pueden asignar a destinatarios con designación "Approver".

Destinatarios CC

Los destinatarios CC ahora son compatibles en todos los endpoints de creación y actualización tanto para plantillas como para solicitudes de firma. Los destinatarios CC aparecen en la lista de destinatarios pero no tienen campos ni participan en el flujo de firma o aprobación.

Cambios

  • Se amplió el enum designation de ["Signer"] a ["Signer", "Approver", "CC"] en 7 esquemas
  • Se agregaron approval_signature, approval_checkmark y approval_date a los enums de tipo de campo en 10 esquemas

Guía de Migración

De v01.13.00 a v01.14.00: Este es un cambio aditivo sin efectos disruptivos. Las integraciones existentes siguen funcionando sin modificaciones.
  • Los nuevos valores de designation son opcionales. Omitir el campo designation usa "Signer" de forma predeterminada, preservando el comportamiento existente.
  • Los nuevos tipos de campo son aditivos. Todos los valores de tipo de campo existentes siguen siendo válidos y sin cambios.
  • Si integras flujos de aprobación, asigna la designación "Approver" a los destinatarios relevantes y usa los tipos de campo approval_* para sus campos.

v01.13.00

Fecha de Lanzamiento: 12 de abril de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Tipo de Campo de Sello

Nuevo tipo de campo stamp para colocar imágenes de sello preconfiguradas o sellos de empresa en documentos. Los sellos son imágenes PNG de solo lectura establecidas por el creador de la plantilla o solicitud de firma, se renderizan en el momento de la firma sin interacción del firmante, y se incrustan en el PDF final.

Cambios

  • Se agregó stamp a los enums de tipo de campo en todos los esquemas relacionados con campos (plantillas, solicitudes de firma, create-and-send)
  • Se actualizaron las descripciones de tipo de campo para documentar el comportamiento del sello

Guía de Migración

De v01.12.01 a v01.13.00: Este es un cambio aditivo sin efectos disruptivos. Las integraciones existentes no se ven afectadas.
  • Si creas campos a través de la API, ahora puedes usar "stamp" como tipo de campo. Los campos de sello deben establecerse como read_only: true con la imagen del sello como una URL de datos PNG en read_only_value.
  • Los campos de sello también son compatibles con las etiquetas de anclaje. Al usar etiquetas de anclaje, la imagen del sello debe proporcionarse mediante read_only_value como una URL de datos PNG.

v01.12.01

Fecha de Lanzamiento: 2 de abril de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

variable_defined_name en las Respuestas de Campo

Todos los endpoints de la API que devuelven campos de plantilla o de solicitud de firma ahora incluyen una propiedad variable_defined_name. Este es el field_name legible por humanos de la definición de campo personalizado al que está vinculado el campo. Anteriormente, los campos vinculados a definiciones de campo personalizado solo exponían variable_name, que contiene el identificador interno (por ejemplo, custom_template_a1b2c3d4-...). El nuevo variable_defined_name devuelve el nombre que definiste originalmente (por ejemplo, artist_name), facilitando el mapeo de campos en tu integración sin tener que hacer referencia cruzada al endpoint de campos personalizados. Endpoints afectados:
  • GET /templates (lista y único)
  • GET /templates/{id}/fields
  • POST /templates/{id}/replace-document
  • GET /signing-requests (lista)
  • GET /signing-requests/{id}/fields
  • GET /documents (legado)
Ejemplo de respuesta:
Para campos no vinculados a una definición de campo personalizado, variable_defined_name es null.

variable_defined_name como Entrada para la Coincidencia de Campos

Al crear una solicitud de firma a partir de una plantilla mediante POST /signing-requests/create-and-send, ahora puedes usar variable_defined_name para dirigir campos para anulaciones en lugar del variable_name interno:
Se aceptan tanto variable_name como variable_defined_name. variable_name tiene prioridad cuando se proporcionan ambos.

Sin Cambios Importantes

Esta es una versión de parche sin efectos disruptivos. Todo el comportamiento existente de la API no cambia.

v01.12.00

Fecha de Lanzamiento: 26 de marzo de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Integración con Servidor MCP

Firma ahora es compatible con el Model Context Protocol (MCP), lo que permite que asistentes de IA como Claude interactúen con la API de Firma mediante lenguaje natural. El servidor MCP expone las operaciones principales de la API de Firma como herramientas que los asistentes de IA pueden descubrir y llamar directamente. URL del Servidor: https://mcp.firma.dev/mcp Autenticación:
  • Autenticación con clave API a través del encabezado Authorization
  • OAuth 2.1 con PKCE para clientes basados en navegador (Claude.ai, Claude Desktop)
Categorías de herramientas disponibles:
  • Espacios de trabajo — listar, crear, obtener, actualizar
  • Plantillas — CRUD completo, duplicar, ver campos/usuarios/recordatorios
  • Solicitudes de Firma — CRUD completo, enviar, cancelar, reenviar, registros de auditoría
  • Webhooks — CRUD completo, prueba de entrega
  • Empresa — ver y actualizar información de la empresa
Transporte: Streamable HTTP — compatible con Claude Code, Claude Desktop, Claude.ai y cualquier cliente MCP que admita el estándar. Consulta la guía de Integración MCP para instrucciones de configuración y ejemplos de uso.

Sin Cambios Importantes

Esta versión no agrega nuevos endpoints de API ni cambios de esquema. La especificación OpenAPI no ha cambiado respecto a v1.11.0.

v01.11.00

Fecha de Lanzamiento: 19 de marzo de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Tipo de Campo de Subida de Archivos

Un nuevo tipo de campo file permite a los firmantes subir archivos adjuntos. Compatible tanto en solicitudes de firma como en plantillas.
  • Los firmantes pueden subir imágenes (JPG, PNG) y/o archivos PDF según la configuración
  • Los archivos se validan por bytes mágicos, no solo por la extensión del archivo
  • Tamaño máximo de archivo: 10MB
Configuración mediante format_rules:

Etiquetas de Anclaje para la Colocación Automática de Campos

Un nuevo array anchor_tags en la creación de solicitudes de firma habilita la colocación automática de campos usando marcadores de texto incrustados en documentos PDF (por ejemplo, {{SIGN_HERE}}). El texto de anclaje se elimina del PDF después del procesamiento de forma predeterminada.
  • Hasta 100 etiquetas de anclaje por solicitud
  • Solo disponible para la creación basada en documentos (no basada en plantillas)
  • Los campos creados a partir de etiquetas de anclaje se agregan junto a cualquier campo especificado manualmente
Propiedades clave: Ejemplo:

Color de Fondo de Campo

Todos los tipos de campo ahora admiten una propiedad background_color — una cadena de color hexadecimal (por ejemplo, #FFFDE7, #fff) útil para resaltar campos que requieren atención. Disponible tanto en campos estándar como en definiciones de etiquetas de anclaje.

Cambios de Esquema

Nuevos Esquemas

Field / TemplateField / SigningRequestField

Enum de Tipo de Campo

  • Se agregó file a la lista de tipos de campo aceptados

format_rules

  • Ahora acepta FileFormatRules (con acceptedFileTypes) además de DateFormatRules y el texto a mostrar de URL

Creación de Solicitud de Firma

Cambios Importantes

Cambio del Valor Predeterminado de use_signing_order

El valor predeterminado de la configuración use_signing_order ha cambiado de false a true. Esto significa que las nuevas solicitudes de firma aplicarán el orden de firma de forma predeterminada. Cuando es true, los firmantes reciben el documento en secuencia según su campo order. Establece use_signing_order: false explícitamente para preservar el comportamiento anterior en el que todos los firmantes reciben el documento simultáneamente.

Guía de Migración

Si dependes del comportamiento anterior en el que todos los firmantes reciben los documentos simultáneamente, establece explícitamente use_signing_order: false al crear solicitudes de firma. Revisa cualquier código de integración que cree solicitudes de firma sin especificar este campo.

v01.10.00

Fecha de Lanzamiento: 10 de marzo de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Lógica de Campo Condicional

Los campos ahora admiten reglas condicionales tanto para el estado obligatorio como para la visibilidad. Dos nuevas propiedades anulables están disponibles en los objetos de campo:
  • required_conditions — Cuando se establece, anula el indicador estático required. El campo es obligatorio solo cuando las condiciones se evalúan como verdaderas según los valores de otros campos.
  • visibility_conditions — Cuando se establece, el campo se oculta a menos que las condiciones se evalúen como verdaderas. Los campos ocultos no se validan al enviar.
Las condiciones usan una estructura de grupo anidada con operadores lógicos: Operadores admitidos: is_filled, is_empty, equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_or_equal, less_than_or_equal Ejemplo: hacer que un campo sea obligatorio solo cuando se completa otro campo:

Soporte de Documentos DOCX

Todos los endpoints de subida de documentos ahora aceptan archivos DOCX además de PDF. Los archivos DOCX se convierten automáticamente a PDF al subirlos. Esto aplica a:
  • Creación de plantilla (POST /templates)
  • Reemplazo de documento de plantilla (POST /templates/{id}/replace-document)
  • Creación de solicitud de firma (POST /signing-requests)
  • Actualizaciones de plantilla/solicitud de firma (PUT y PATCH)

Endpoint de Registro de Auditoría

Un nuevo endpoint recupera el registro de auditoría completo de una solicitud de firma, combinando las acciones del administrador (creado, editado, enviado, cancelado) y las acciones del firmante (visto, firmado, rechazado, descargado). Los eventos se ordenan cronológicamente. Endpoint: GET /signing-requests/{id}/audit Campos de respuesta:

Control del Marco de Firma

Una nueva configuración show_signature_frame controla si se renderiza un marco visual con el ID de Firma alrededor de las firmas en los PDF completados. Disponible a nivel de empresa, espacio de trabajo y solicitud de firma. Valores:
  • true — Mostrar el marco de firma con el ID de Firma
  • false — Ocultar el marco de firma
  • null — Heredar del nivel padre

Forzar la Eliminación de Condiciones al Eliminar Usuarios

Al eliminar destinatarios cuyos campos son referenciados por condiciones en otros campos, un nuevo parámetro booleano force_remove_conditions controla el comportamiento:
  • false (predeterminado) — La solicitud se rechaza con un error que lista los campos dependientes
  • true — Elimina automáticamente las referencias de condición y procede con la eliminación
Esto aplica tanto a las operaciones de eliminación de usuario de plantilla como de solicitud de firma.

Cambios de Esquema

Field

Nuevos Esquemas

SigningRequestSettings / WorkspaceSettings / Company

Eliminación de Usuario de Plantilla y Solicitud de Firma

Nuevos Endpoints

Guía de Migración

Sin cambios importantes. Todas las nuevas funcionalidades son aditivas:
  • Las propiedades de campo condicional son predeterminadamente null (sin condiciones)
  • show_signature_frame es predeterminadamente null (heredar, que está habilitado de forma predeterminada)
  • force_remove_conditions es predeterminadamente false (preservando el comportamiento de rechazo existente)
  • El soporte DOCX es transparente: las subidas de PDF existentes siguen funcionando sin cambios
  • El endpoint de registro de auditoría es puramente aditivo

v01.09.00

Fecha de Lanzamiento: 5 de marzo de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Verificación OTP por Correo Electrónico

Una nueva configuración require_otp_verification te permite exigir que los firmantes verifiquen su dirección de correo electrónico con un código de un solo uso antes de acceder a los documentos de firma. Esto agrega una capa adicional de verificación de identidad. Dónde está disponible: Valores:
  • true — Requerir verificación OTP antes de acceder al documento
  • false — No requerir verificación OTP
  • null — Heredar del nivel padre (espacio de trabajo → empresa, solicitud de firma → espacio de trabajo)
Ejemplo: habilitar OTP a nivel de espacio de trabajo:
Ejemplo: anular para una solicitud de firma específica:

Reemplazar Documento de Plantilla

Un nuevo endpoint permite reemplazar el documento PDF de una plantilla mientras se preservan todas las colocaciones de campos. Esto es útil cuando necesitas actualizar un documento (por ejemplo, corregir un error tipográfico) sin recrear todas las configuraciones de campos. Endpoint: POST /templates/{id}/replace-document Requisitos:
  • El documento de reemplazo debe tener el mismo número de páginas que el original
  • Las dimensiones de página deben coincidir dentro de una tolerancia de 1pt
  • El documento debe proporcionarse como un PDF codificado en base64
Ejemplo:
Casos de error:

Cambios de Esquema

SigningRequestSettings

WorkspaceSettings

Nuevos Endpoints

Guía de Migración

Sin cambios importantes. El campo require_otp_verification es predeterminadamente null (heredar), por lo que el comportamiento existente no cambia. El endpoint de reemplazo de documento es puramente aditivo.

v01.08.00

Fecha de Lanzamiento: 3 de marzo de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

API de Plantillas de Correo

Un nuevo grupo de endpoints de Plantillas de Correo te permite personalizar los correos de notificación enviados durante el proceso de firma. Las plantillas se pueden configurar tanto a nivel de empresa como de espacio de trabajo, y las plantillas a nivel de espacio de trabajo anulan los predeterminados a nivel de empresa. Tipos de correo admitidos: Nuevos endpoints: Jerarquía de plantillas: Plantillas de espacio de trabajo → Plantillas de empresa → Predeterminados incorporados. Las plantillas admiten cuerpos HTML con marcadores como {{signing_link}}, {{signer_name}}, etc. Se devuelve una advertencia si el cuerpo no contiene {{signing_link}}. Ejemplo:

Soporte de Idiomas

Nuevo campo language agregado tanto al esquema Company como al WorkspaceSettings para admitir plantillas de correo multi-idioma.

Cambios de Esquema

Correcciones de Marca de Tiempo

Los nombres de los campos de marca de tiempo se han corregido en la especificación para coincidir con las respuestas reales de la API:
Estas son solo correcciones de especificación: las respuestas de la API no han cambiado. Si tu integración ya maneja los campos de respuesta reales de la API, no se necesitan cambios de código.

Esquema Company

Esquema Template (Ampliado)

El esquema Template ahora incluye destinatarios y campos en línea al obtener una única plantilla (GET /templates/{id}), reduciendo la necesidad de llamadas API separadas.

Formas de Respuesta de Solicitud de Firma

El esquema monolítico SigningRequest se ha dividido en formas de respuesta específicas por endpoint: Las respuestas de lista y creación ahora incluyen arrays recipients y fields en línea, y usan campos de marca de tiempo estandarizados (created_date, sent_date, finished_date, etc.).

SigningRequestSettings

use_signing_order (boolean, predeterminado false) ahora está incluido en el objeto settings. Anteriormente solo estaba disponible como un campo entero obsoleto de nivel superior.

Esquema Reminder

Esquema Webhook

SendSigningRequestResponse (Corregido)

La especificación ahora refleja con precisión la forma real de la respuesta:

WorkspaceSettings


v01.07.00

Fecha de Lanzamiento: 25 de febrero de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Firmas Solo Manuscritas

Una nueva configuración hand_drawn_only te permite exigir que los firmantes dibujen a mano su firma en lugar de usar opciones tipeadas o basadas en fuentes. Agregado al esquema SigningRequestSettings: Esta configuración está disponible en todos los lugares donde se configura la configuración de solicitud de firma:
  • Creación de solicitudes de firma (POST /signing-requests)
  • Creación y envío de solicitudes de firma (POST /signing-requests/create-and-send)
  • Actualizaciones completas (PUT /signing-requests/{id})
  • Actualizaciones parciales (PATCH /signing-requests/{id})
  • Creación y actualización de plantillas
Ejemplo:

Cambios de Esquema

Campos de Configuración Heredados Obsoletos

El esquema SigningRequest ahora incluye campos enteros obsoletos de nivel superior que reflejan el objeto settings booleano. Estos existen por compatibilidad con versiones anteriores y no deben usarse en nuevas integraciones:
Estos campos obsoletos usan enteros 0/1 en lugar de booleanos. Usa siempre el objeto settings para las nuevas integraciones.

Guía de Migración

Sin cambios importantes. La configuración hand_drawn_only es predeterminadamente false, preservando el comportamiento existente. Los campos enteros obsoletos de nivel superior son puramente aditivos.

v01.06.00

Fecha de Lanzamiento: 12 de febrero de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Descargas de PDF Divididas

Las solicitudes de firma completadas ahora admiten la descarga del documento firmado y el certificado de registro de auditoría como archivos separados, además de la descarga combinada existente. Nuevos campos en el esquema SigningRequest: Notas:
  • Solo disponible cuando la funcionalidad de PDF dividido se ha aplicado a la solicitud de firma
  • Las URL expiran después de 1 hora: vuelve a obtener la solicitud de firma para obtener una URL nueva
  • Los campos de error devuelven "file_not_accessible" si la ruta del archivo existe pero el archivo falta
Ejemplo de Respuesta (parcial):

Cambios de Esquema

Normalización de Tipo de Campo

Los enums de tipo de campo ahora aceptan tanto las formas originales como las normalizadas en todos los esquemas. La API normaliza las entradas automáticamente: Esquemas afectados:

Guía de Migración

Sin cambios importantes. Se aceptan tanto los nombres de tipo de campo antiguos como los nuevos. Los campos de descarga de PDF dividido son puramente aditivos.

v01.05.00

Fecha de Lanzamiento: 5 de febrero de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Advertencias de Validación de Correo Electrónico

Los endpoints de solicitud de firma ahora devuelven advertencias no bloqueantes cuando las direcciones de correo electrónico de los destinatarios tienen formatos potencialmente inválidos (por ejemplo, TLD inusuales, puntos faltantes). Estas advertencias ayudan a identificar posibles problemas de entrega sin hacer fallar la solicitud. Endpoints Afectados: Ejemplo de Respuesta:
Notas:
  • Las advertencias no son bloqueantes: la solicitud sigue teniendo éxito
  • Útil para marcar posibles errores tipográficos o dominios de correo inválidos
  • Verifica el campo warnings o warning en la respuesta para mostrar esto a los usuarios

Guía de Migración

Sin cambios importantes. Las advertencias de validación de correo electrónico son puramente aditivas y no afectan a las integraciones existentes.

v01.04.00

Fecha de Lanzamiento: 31 de enero de 2026
Descargar especificación OpenAPI

Nuevas Funcionalidades

Nuevos Tipos de Campo

Se han agregado tres nuevos tipos de campo: Detalles del Campo URL:
  • Se establece automáticamente en read_only: true
  • Usa read_only_value para establecer la URL de destino
  • Usa format_rules.urlDisplayText para personalizar el texto mostrado
Ejemplo:

Operaciones PATCH de Campo

Ambos endpoints PATCH de Plantilla y Solicitud de Firma ahora admiten operaciones de campo único: PATCH de Plantilla (PATCH /templates/{id}):
  • Ahora puede actualizar propiedades, un solo usuario, O un solo campo
  • Incluye el objeto field en el cuerpo de la solicitud
  • Incluye field.id para actualizar un campo existente, omítelo para crear uno nuevo
PATCH de Solicitud de Firma (PATCH /signing-requests/{id}):
  • Ahora puede actualizar propiedades, un solo destinatario, O un solo campo
  • Misma estructura de objeto de campo que las plantillas
Ejemplo: crear un nuevo campo:
Ejemplo: actualizar un campo existente:

Coincidencia de Usuario de Plantilla para Destinatarios

Al crear solicitudes de firma a partir de plantillas, ahora puedes usar template_user_id para coincidir explícitamente destinatarios con usuarios de plantilla:
  • template_user_id es el método preferido para la coincidencia
  • order sigue disponible como alternativa

Cambios de Esquema

Enum de Tipo de Campo

Actualizado de:
A:

Esquema Recipient

  • La creación de solicitud de firma ahora usa la referencia del esquema Recipient compartido
  • Se agregó la propiedad template_user_id para la coincidencia explícita de usuario de plantilla

v01.03.00

Descargar especificación OpenAPI

Nuevas Funcionalidades

API de Dominios de Correo

Una nueva categoría de API completa para configurar dominios de correo personalizados para el envío de correos de solicitud de firma: Nuevos Endpoints:
  • GET /company/domains - Listar todos los dominios de correo de la empresa
  • POST /company/domains - Agregar un nuevo dominio de correo
  • GET /company/domains/{id} - Obtener detalles del dominio
  • DELETE /company/domains/{id} - Eliminar un dominio
  • POST /company/domains/{id}/verify-ownership - Verificar la propiedad del dominio mediante un registro TXT
  • POST /company/domains/{id}/finalize - Completar la configuración del dominio con el proveedor de correo
  • POST /company/domains/{id}/verify-dns - Verificar los registros SPF, DKIM, DMARC
  • POST /company/domains/{id}/set-primary - Establecer el dominio de envío principal
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

Seguimiento del Coste en Créditos

  • Se agregó el campo credit_cost al esquema Template - Número de créditos consumidos al enviar
  • Se agregó el campo credit_cost al esquema SigningRequest - Créditos consumidos al enviar

Estado Rechazado de la Solicitud de Firma

  • Se agregó declined a los valores del enum SigningRequest.status
  • Se agregó el campo date_declined al esquema SigningRequest

Mejoras de Esquema

Campos de Plantilla

  • Se agregó el campo date_default para establecer valores de fecha predeterminados (formato ISO 8601)
  • Descripción mejorada de multi_group_id: explica la agrupación mutuamente excluyente de campos para casillas de verificación/botones de radio
  • Se agregó una aclaración de que page_number comienza en 1 y no debe exceder el número de páginas del documento

Campos de Solicitud de Firma

  • Descripción mejorada de multi_group_id con las mismas mejoras que los campos de plantilla

v01.02.00

Descargar especificación OpenAPI

Información de Usuario Mejorada

Mejoras del Esquema TemplateUser

Se agregaron campos completos de información del destinatario:
  • first_name - Nombre del destinatario
  • last_name - Apellido del destinatario
  • phone_number - Número de teléfono de contacto
  • street_address - Dirección
  • city - Ciudad
  • state_province - Estado o provincia
  • postal_code - Código postal
  • country - País
  • title - Cargo
  • company - Nombre de la empresa

Indicadores de Listo para Enviar

Nuevos campos para ayudar a determinar la preparación del destinatario:
  • required_fields - Lista de campos de datos de destinatario obligatorios según la configuración de la plantilla
  • missing_fields - Lista de campos obligatorios que actualmente están vacíos
  • required_read_only_fields - Campos de solo lectura que necesitan valores precompletados
  • ready_to_send - Booleano que indica si el destinatario tiene todos los datos obligatorios

Mejoras del Esquema SigningRequestUser

Las mismas mejoras que TemplateUser, más:
  • declined_on - Marca de tiempo de cuándo el destinatario rechazó firmar
  • decline_reason - Motivo proporcionado por el destinatario para rechazar
  • custom_fields - Valores de campo personalizado para el destinatario
  • Propiedad has_value en required_read_only_fields - Indica si el campo de solo lectura tiene un valor

Cambios en el Formato de Respuesta

El endpoint de usuarios de plantilla (GET /templates/{id}/users) ahora devuelve:

v01.01.00

Descargar especificación OpenAPI

Nuevos Endpoints

Gestión de Plantillas

Soporte CRUD completo para plantillas:
  • POST /templates - Crear una nueva plantilla con PDF codificado en base64
  • PATCH /templates/{id} - Actualización parcial (propiedades O un solo usuario)
  • PUT /templates/{id} - Actualización completa (propiedades, usuarios, campos, recordatorios)
  • DELETE /templates/{id} - Eliminación suave de una plantilla

Sub-Recursos de Plantilla

  • GET /templates/{id}/users - Obtener todos los destinatarios de la plantilla
  • GET /templates/{id}/fields - Obtener todos los campos de la plantilla
  • GET /templates/{id}/reminders - Obtener todos los recordatorios de la plantilla

Gestión de Claves API

Nuevos endpoints para el ciclo de vida de la clave API del espacio de trabajo:
  • POST /workspaces/{id}/api-key/regenerate - Generar una nueva clave API con un período de gracia de 24 horas
  • POST /workspaces/{id}/api-key/expire - Expirar inmediatamente las claves pendientes

Operaciones Mejoradas

Actualizaciones Completas

El endpoint PUT para plantillas admite:
  • template_properties - Actualizar metadatos y configuración
  • users - Upsert de usuarios (incluye id para actualizar, omítelo para crear)
  • deleted_users - Eliminar usuarios con estrategia de manejo de campos (delete o reassign)
  • fields - Upsert de campos
  • reminders - Upsert de recordatorios
Ejemplo de solicitud:

v01.00.02

Descargar especificación OpenAPI

Nuevas Funcionalidades

API de Campos Personalizados

Se agregó la gestión de definiciones de campo personalizado para espacios de trabajo, plantillas y solicitudes de firma. Nueva Etiqueta:
  • Custom Fields - Gestión de definiciones de campo personalizado
Nuevos Esquemas:
WorkspaceCustomField
TemplateCustomField
SigningRequestCustomField

Mejoras de Esquema

Esquema TemplateField

Mejorado con descripciones más claras y propiedades adicionales:
  • Propiedad type explícita con valores enum
  • Objeto position con x, y, width, height
  • read_only y read_only_value para campos precompletados

v01.00.01

Descargar especificación OpenAPI

Versión Inicial

La versión inicial de la API de Socios de Firma con las siguientes funcionalidades principales:

Etiquetas / Categorías de la API

  • Company - Información y configuración de la empresa
  • Workspaces - Operaciones de gestión de espacios de trabajo
  • Templates - Operaciones de gestión de plantillas
  • Signing Requests - Operaciones de solicitud de firma de documentos
  • Webhooks - Configuración y gestión de webhooks
  • JWT Management - Generación y revocación de tokens JWT
  • Legacy - Endpoints obsoletos por compatibilidad con versiones anteriores

Autenticación

  • Autenticación con clave API mediante el encabezado Authorization
  • Soporte opcional de prefijo Bearer

Límite de Solicitudes

Límites de solicitudes escalonados según el tipo de operación:
  • Operaciones de lectura (GET): 200 solicitudes/minuto
  • Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes/minuto
  • CRUD de Webhook: 60 solicitudes/minuto
  • Prueba de Webhook: 10 solicitudes/minuto
  • Operaciones de clave API: 1 solicitud/minuto
  • Rotación de secretos: 1 solicitud/minuto

Esquemas Principales

Company
  • id, company_name, account_owner, account_owner_email
  • website, icon_url, credits (solo lectura)
  • date_created, date_changed
Workspace
  • id, name, protected, api_key
  • date_created, date_changed
Template
  • id, name, description
  • document_url (pre-firmada, expira)
  • document_url_expires_at
  • date_created, date_changed
SigningRequest
  • id, name, description
  • document_url, document_url_expires_at
  • document_page_count, status, expiration_hours
  • settings, template_id
  • Campos de fecha: date_created, date_sent, date_finished, date_cancelled, expires_at
  • Objeto certificate con estado de generación
  • final_document_download_url, final_document_download_error
Recipient
  • Principal: id, first_name, last_name, email, designation, order
  • Dirección: street_address, city, state_province, postal_code, country
  • Profesional: phone_number, title, company
  • custom_fields para datos adicionales
  • Soporte de ID temporal para la creación basada en documentos
Field
  • id, type, position, page_number, required
  • recipient_id, variable_name
  • Específico del tipo: dropdown_options, date_default, date_signing_default
  • Solo lectura: read_only, read_only_value, prefilled_data
  • Formato: format_rules, validation_rules
Webhook
  • id, url, events, enabled
  • date_created, date_changed

Gestión JWT

  • Generar JWT para la incrustación de plantillas
  • Generar JWT para la incrustación de solicitudes de firma
  • Revocar tokens JWT

Guía de Migración

Migración de v01.00.01 a v01.00.02

  • Sin cambios importantes
  • API de Campos Personalizados disponible para su uso

Migración de v01.00.02 a v01.01.00

  • Sin cambios importantes
  • Nuevos endpoints de gestión de plantillas disponibles
  • Endpoints de regeneración de clave API disponibles

Migración de v01.01.00 a v01.02.00

  • Sin cambios importantes
  • Los usuarios de plantilla y de solicitud de firma ahora incluyen campos adicionales
  • Booleano ready_to_send disponible para verificar la preparación del destinatario

Migración de v01.02.00 a v01.03.00

  • Sin cambios importantes
  • Configuración de dominio de correo disponible para dominios de envío personalizados
  • Estado declined agregado al enum de estado de la solicitud de firma
  • Seguimiento del coste en créditos disponible en plantillas y solicitudes de firma

Migración de v01.03.00 a v01.04.00

  • Sin cambios importantes
  • El tipo de campo radio se renombró a radio_buttons (ambos siguen siendo aceptados)
  • Nuevos tipos de campo disponibles: textarea, url
  • Los endpoints PATCH ahora admiten operaciones de campo único
  • Usa template_user_id para la coincidencia explícita de usuario de plantilla en solicitudes de firma

Migración de v01.04.00 a v01.05.00

  • Sin cambios importantes
  • Las advertencias de validación de correo electrónico son puramente aditivas

Migración de v01.05.00 a v01.06.00

  • Sin cambios importantes
  • URL de descarga de PDF dividido disponibles en solicitudes de firma completadas
  • Las entradas de tipo de campo initials/initial y textarea/text_area se aceptan ambas con normalización automática

Migración de v01.06.00 a v01.07.00

  • Sin cambios importantes
  • Nueva configuración hand_drawn_only disponible en la configuración de solicitud de firma (predeterminado false)
  • Los campos enteros obsoletos de nivel superior ahora son visibles en el esquema SigningRequest: usa el objeto settings en su lugar

Migración de v01.07.00 a v01.08.00

  • Sin cambios importantes: las correcciones de nombres de campo del esquema reflejan las respuestas reales de la API
  • Nueva API de Plantillas de Correo para personalizar los correos de notificación de firma
  • Campo language agregado a Company y WorkspaceSettings
  • Esquema Template ampliado con recipients, fields, settings, page_count, expiration_hours en línea
  • use_signing_order agregado a SigningRequestSettings
  • El esquema Webhook incluye description, consecutive_failures, auto_disabled_at
  • Las respuestas de solicitud de firma se dividieron en formas específicas por endpoint con datos en línea

Migración de v01.08.00 a v01.09.00

  • Sin cambios importantes
  • Nueva configuración require_otp_verification disponible a nivel de empresa, espacio de trabajo y solicitud de firma
  • Nuevo endpoint POST /templates/{id}/replace-document para reemplazar los PDF de plantilla preservando los campos

Migración de v01.09.00 a v01.10.00

  • Sin cambios importantes
  • Lógica de campo condicional disponible mediante required_conditions y visibility_conditions en los campos
  • Ahora se aceptan archivos DOCX junto con PDF en todos los endpoints de subida de documentos
  • Nuevo endpoint GET /signing-requests/{id}/audit para recuperar registros de auditoría
  • Nueva configuración show_signature_frame a nivel de empresa, espacio de trabajo y solicitud de firma
  • Nuevo parámetro force_remove_conditions en las operaciones de eliminación de usuario

Migración de v01.10.00 a v01.11.00

  • Cambio importante: el valor predeterminado de use_signing_order cambió de false a true; establece explícitamente use_signing_order: false si dependes de la entrega simultánea
  • Nuevo tipo de campo file para las subidas de archivos del firmante
  • Etiquetas de anclaje para la colocación automática de campos a partir de marcadores de texto en PDF
  • Propiedad background_color disponible en todos los tipos de campo

Migración de v01.11.00 a v01.12.00

  • Sin cambios importantes
  • Integración con servidor MCP para el acceso de asistentes de IA a la API de Firma
  • Sin nuevos endpoints de API ni cambios de esquema: la especificación OpenAPI no ha cambiado desde v1.11.0

Migración de v01.12.00 a v01.12.01

  • Sin cambios importantes
  • Nuevo campo variable_defined_name en todas las respuestas de campo: devuelve el nombre legible por humanos de la definición de campo personalizado junto al variable_name interno
  • variable_defined_name aceptado como entrada para la coincidencia de campos en POST /signing-requests/create-and-send

Migración de v01.15.03 a v01.16.00

  • Sin cambios importantes
  • Nuevo endpoint GET /signing-requests/{id}/download para recuperar una URL de descarga del documento firmado
  • Descargas parciales disponibles cuando allow_partial_download está habilitado en la configuración de solicitud de firma

Migración de v01.16.00 a v01.17.00

  • Sin cambios importantes
  • Seis nuevos campos de color anulables (color_primary, color_primary_fg, color_background, color_foreground, color_card, color_border) en Company y Workspace Settings
  • Nuevo esquema ColorPalette para los colores resueltos de la experiencia de firma
  • Los colores siguen una cascada de 3 niveles: predeterminados de Firma -> Empresa -> Espacio de Trabajo

Migración de v1.19.0 a v1.20.0

  • Sin cambios importantes
  • Nueva configuración disable_guided_navigation disponible a nivel de empresa, espacio de trabajo, plantilla y solicitud de firma
  • Sigue el mismo patrón de cascada que require_otp_verification: solicitud de firma -> espacio de trabajo -> empresa (el primer valor no nulo gana)
  • Predeterminado false (desplazamiento automático habilitado), preservando el comportamiento existente

Migración de v1.20.0 a v1.21.0

  • Sin cambios importantes
  • Nueva configuración email_local_part en Company (GET/PATCH /company) y Workspace Settings (GET/PUT /workspace/{id}/settings)
  • El valor del espacio de trabajo tiene prioridad sobre el valor de la empresa; el predeterminado es "support"
  • Solo aplica cuando hay un dominio personalizado verificado configurado

Migración de v1.38.0 a v1.39.0

  • Sin cambios importantes
  • Las funciones multidocumento requieren habilitación para tu empresa; las empresas no habilitadas no ven ningún cambio
  • Nuevo document_ids en POST /templates, POST /signing-requests y POST /signing-requests/create-and-send, y nuevas rutas /documents en plantillas y solicitudes de firma
  • En las empresas habilitadas, anchor_tags[].document_index selecciona el documento en el que se busca una anchor tag en las solicitudes multidocumento
  • Envía documents_layout_version con las escrituras de campos en plantillas y solicitudes de firma que tienen más de un documento

Migración de v1.40.0 a v1.40.1

  • Ningún cambio para los PDF válidos
  • Un PDF con una página sin contenido válido devuelve 400 MALFORMED_PDF con malformed_pages; no se escribe nada
  • Un PDF ilegible, incluido uno cifrado, devuelve 400 VALIDATION_ERROR en lugar de 500

Migración de v1.40.1 a v1.40.2

  • Sin cambios en la API
  • La lista events de POST /webhooks y PUT /webhooks/{id} ahora nombra los 26 eventos que envía Firma.dev; vuelva a generar los clientes creados a partir de la especificación