Actualizaciones de producto
Novedades en Firma.dev: firma todo el paquete de la operación en una sola solicitud, con cada archivo sellado por separado
Escrito por

Un acuerdo B2B suele cerrarse con una pila de archivos: un contrato marco de servicios, una declaración de trabajo, un acuerdo de confidencialidad y una hoja de pedido, todos destinados al mismo cliente para la misma firma. A partir de la versión v1.39.0 de la API, todo ese paquete puede enviarse como una única solicitud de firma de Firma.dev, y cada archivo incluido se devuelve como su propio documento sellado.
La firma multidocumento ya está disponible para todas las cuentas de Firma.dev
Esto es nuevo y ya está activado para todos. La versión añade:
Una plantilla o solicitud de firma puede contener hasta 20 documentos, con un límite de 100 MB por conjunto de documentos.
POST /templates,POST /signing-requestsyPOST /signing-requests/create-and-sendaceptandocument_ids, una lista de subidas en el orden de los documentos.Nuevas rutas
/documentspara añadir, sustituir, renombrar, reordenar, eliminar y descargar documentos de uno en uno.Las etiquetas de anclaje pueden dirigirse a un único documento mediante
document_index.Cada documento de una solicitud de firma completada se descarga como su propio archivo sellado individualmente, con su propio hash SHA-256.
El registro de cambios fecha el lanzamiento el 12 de octubre de 2026, y las funciones multidocumento han estado disponibles para todas las empresas desde el 13 de octubre de 2026. No hay nada que activar ni ningún indicador que solicitar.
El precio tampoco cambia. Una solicitud de firma equivale a un crédito, 0,049 € (~5 ¢ USD), tanto si contiene un documento como veinte. Las preguntas frecuentes de la documentación lo dicen explícitamente: un crédito equivale a una solicitud de firma, independientemente de cuántos firmantes o documentos contenga. Sigue siendo de pago por uso, sin consumos mínimos mensuales ni tarifas por usuario.
Lo que antes requería un paquete de cuatro documentos
Hasta este lanzamiento, una solicitud de firma contenía un único documento. Enviar un paquete implicaba desarrollar una infraestructura para sortear esa limitación, y normalmente tenía este aspecto:
Paso | Lo que tenía que hacer su código |
|---|---|
1. Combinar | Combinar el contrato marco, la declaración de trabajo, el acuerdo de confidencialidad y la hoja de pedido en un solo PDF |
2. Desplazamiento | Añadir el número de páginas de cada archivo anterior al número de página de cada campo |
3. Enviar | Crear la solicitud de firma a partir del PDF combinado |
4. Dividir | Separar el PDF sellado único por rangos de páginas |
5. Asignar | Adjuntar cada fragmento al registro correspondiente en su aplicación |
Los pasos 2 y 4 es donde fallaba. Un cliente cambia un acuerdo de confidencialidad por uno de dos páginas donde antes había uno de tres páginas, y cada campo posterior acaba en la página equivocada. Los rangos de división se desfasan de la misma forma... y para una plataforma SaaS cuyos propios clientes suben estos conjuntos, el paquete de cada suscriptor es ligeramente diferente, por lo que el error aparece suscriptor por suscriptor.
Con la versión v1.39.0 desaparecen los pasos de combinar, calcular desplazamientos y dividir. Cada archivo entra como su propia subida, avanza a través de un único flujo de firma y se devuelve sellado de manera independiente.
Envío del paquete con document_ids
Suba cada archivo con POST /documents
Cada documento del conjunto comienza como una subida. POST /documents recibe un nombre de archivo, tamaño y tipo de contenido, y devuelve un document_id temporal junto con una upload_url prefirmada. Usted realiza un PUT con los bytes sin procesar del archivo a esa URL. Es una subida por archivo... por lo que un paquete de cuatro documentos implica cuatro subidas antes de que la solicitud de firma siquiera exista.
Esta vía es también la que debe utilizarse para archivos de gran tamaño. Desde la versión v1.40.0, cualquier cuerpo de solicitud superior a 6 MiB devuelve 413 REQUEST_TOO_LARGE, por lo que los archivos PDF grandes deben subirse mediante POST /documents de todos modos. Una subida individual puede alcanzar hasta 50 MB (el conjunto completo tiene un límite de 100 MB).
Crear y enviar en el orden de los documentos
Pase de 1 a 20 identificadores de subida en document_ids, en el orden en que deben aparecer los documentos. POST /signing-requests/create-and-send los acepta. También lo hacen POST /signing-requests, para un borrador que envíe más tarde, y POST /templates.
Cada llamada de creación toma exactamente una fuente de documento: document, document_id, document_ids o template_id. Si envía más de una, la API devolverá 400 CONFLICTING_DOCUMENT_SOURCE. Un identificador repetido devuelve 400 DUPLICATE_DOCUMENT_ID, más de 20 devuelve 400 MAX_DOCUMENTS_EXCEEDED y un conjunto que supere los 100 MB devuelve 413 DOCUMENT_SET_TOO_LARGE.
Dirigir etiquetas de anclaje al documento correcto
Las etiquetas de anclaje ahora admiten document_index, la posición en base 1 del documento de destino en document_ids. Con un solo documento es opcional y su valor por defecto es 1. Con más de uno es obligatorio, y omitirlo devuelve 400 ANCHOR_DOCUMENT_REQUIRED. Al indicarlo, el {{SIGN_HERE}} en el acuerdo de confidencialidad se mantiene separado del {{SIGN_HERE}} en la declaración de trabajo, incluso cuando todos los archivos del paquete utilicen el mismo marcador.
Si las etiquetas de anclaje son algo nuevo para usted, la guía paso a paso sobre etiquetas de anclaje trata los desplazamientos, las apariciones y el dimensionamiento.
Cada documento se devuelve sellado de manera independiente
GET /signing-requests/{id} devuelve un array documents. Cada elemento tiene document_id, position, label, original_filename y page_count, y en las solicitudes de firma también incluye document_only_hash, el SHA-256 del documento sellado individualmente una vez que el certificado queda vinculado (nulo antes de eso).
Para obtener un archivo, llame a GET /signing-requests/{id}/documents/{document_id}/download. Devuelve una URL firmada válida durante 1 hora:
type=original(el valor predeterminado) devuelve el documento tal y como se subió.type=documentdevuelve el documento sellado individualmente una vez que el certificado queda vinculado. Antes de eso devuelve404 DOCUMENT_SIGNED_NOT_AVAILABLE, por lo que debe interpretar ese código como "aún no disponible" y volver a intentarlo un poco más tarde.
Para una aplicación SaaS, esto elimina el último fragmento de código de integración provisional. El bucle siguiente escribe el contrato marco firmado en el registro del contrato, el acuerdo de confidencialidad firmado en el registro correspondiente, y así sucesivamente, guardando el hash de cada archivo junto a él. Y dado que position respeta el orden enviado en document_ids, se asigna directamente al paquete que usted configuró.
Si también desea las descargas a nivel de solicitud (el PDF solo con el documento y el certificado por separado), se tratan en la publicación sobre descargas de PDF divididos. Cada solicitud de firma conserva también su pista de auditoría.
Plantillas que contienen un conjunto de documentos
Una plantilla también puede albergar el paquete completo, lo que se adapta a plataformas que envían el mismo conjunto a cada cliente nuevo. Créela con document_ids en POST /templates, y luego gestione cada archivo en /templates/{id}/documents:
POST /templates/{id}/documentsañade un documento en lapositionindicada, o al final si se omite la posición.PATCH /templates/{id}/documents/{document_id}sustituye el documento por una nueva subida (document_id) o le cambia el nombre (label). Envíe exactamente una de las dos opciones por llamada.PUT /templates/{id}/documents/orderreordena el conjunto. La lista debe nombrar cada documento exactamente una vez, o devolverá400 INVALID_DOCUMENT_ORDER.DELETE /templates/{id}/documents/{document_id}elimina uno. El último documento restante no se puede eliminar.
Una sustitución mantiene los campos en su lugar siempre que el nuevo archivo tenga el mismo número de páginas y cada página mantenga las mismas dimensiones con un margen de 1 pt. De lo contrario, obtendrá 400 PAGE_COUNT_MISMATCH o 400 DIMENSION_MISMATCH. Así, cuando el departamento legal actualice el acuerdo de confidencialidad, solo tendrá que sustituir ese archivo... y los campos del contrato marco, la declaración de trabajo y la hoja de pedido permanecerán donde estaban. La página de la función para sustituir documentos de plantillas trata el reemplazo con más detalle.
También hay un control de concurrencia, y resulta especialmente importante en entornos multiinquilino (dos servicios, o dos administradores, editando la misma plantilla). documents_layout_version se incrementa cada vez que se añaden, eliminan o reordenan documentos. Las operaciones de escritura de campos a través de PUT y PATCH en /templates/{id} y /signing-requests/{id} envían el valor de su última lectura. Es obligatorio en cuanto hay más de un documento o la versión de diseño es superior a 1 (409 DOCUMENTS_LAYOUT_VERSION_REQUIRED si falta), y un valor desactualizado devuelve 409 DOCUMENT_SET_VERSION_CONFLICT. Si el administrador de un inquilino reordena el paquete en su interfaz de usuario mientras un proceso en segundo plano mueve un campo, la segunda escritura falla con un 409 y los cambios de nadie se sobrescriben de forma inadvertida.
Las solicitudes de firma utilizan las mismas rutas /signing-requests/{id}/documents mientras sigan en estado de borrador. Una vez que una solicitud se envía, finaliza, cancela o rechaza, cualquier escritura en los documentos devuelve 409 DOCUMENT_SET_LOCKED.
Qué cambia en una integración existente
La versión es acumulativa. Las solicitudes que nunca utilizan document_ids, document_index o las rutas /documents funcionan exactamente igual que antes. Vale la pena revisar tres aspectos:
Clientes generados. Si genera un cliente a partir de la especificación OpenAPI,
documentahora es opcional enPOST /templates, y el esquema del participante del sello en las respuestas de solicitudes de firma pasa a llamarseSealParticipantApi(antes eraSealParticipant).Validación estricta de errores. Si su código rechaza códigos de error desconocidos, añada los nuevos. El esquema
MultiDocumentErrorCodeen la referencia de la API los enumera todos.Copias de plantillas.
POST /templates/{id}/copyconvierte una plantilla multidocumento en una plantilla con un único documento combinado. Se conservan el contenido de los campos y los números de página absolutos. Se descartan las etiquetas y posiciones por documento, algo a tener en cuenta si copia plantillas en los espacios de trabajo de clientes.
En el aspecto legal no cambia nada. Firma.dev cumple con la ley ESIGN, UETA, eIDAS (SES y AES) y el eIDAS del Reino Unido, y las firmas son legalmente vinculantes en más de 55 países para cada documento del conjunto.
Resumen
La firma multidocumento ya está disponible en la API de Firma.dev para todas las cuentas. Suba cada archivo con POST /documents, pase hasta 20 identificadores en document_ids, oriente las etiquetas de anclaje con document_index y descargue cada documento sellado individualmente con su propio document_only_hash. Las plantillas pueden albergar los mismos conjuntos y actualizar un archivo a la vez, con documents_layout_version protegiendo contra ediciones concurrentes. Todo el paquete cuesta un crédito, 0,049 € (~5 ¢ USD). Todos los detalles están en el registro de cambios de la API.
Empiece a usar Firma.dev gratis, sin necesidad de tarjeta de crédito.
Artículos relacionados
Nuestra plataforma está diseñada para capacitar a las empresas de todos los tamaños para trabajar de manera más inteligente y alcanzar sus objetivos con confianza.



