Enlace de firma múltiple

Cuando una misma persona tiene varios documentos pendientes de firma, en lugar de enviarle una invitación por cada uno puedes agruparlos y generar un único enlace de firma múltiple. El firmante valida su identidad una sola vez y firma todo el conjunto en una misma sesión. Este tutorial explica cómo generar ese enlace utilizando la API de Signatura.

En la API, este conjunto se denomina grupo de documentos (document group).

Funcionalidad experimental

Este endpoint es experimental: su contrato puede cambiar sin previo aviso y sin un cambio de versión de la API. Tenlo en cuenta antes de utilizarlo en producción.

Requisitos previos

Para crear un grupo de documentos necesitas:

• Una API key válida
• Los IDs de los documentos (document_id) que deseas agrupar, previamente cargados
• El correo electrónico del firmante

Además, cada documento debe cumplir estas condiciones:

• Pertenecer al mismo espacio de trabajo que la API key utilizada
• Estar en estado Pendiente (PE)
• Tener exactamente un firmante pendiente con el correo indicado (la comparación no distingue mayúsculas de minúsculas)
• Exigir al firmante las mismas validaciones de identidad que el resto de los documentos del grupo, con los mismos valores fijos

La funcionalidad no está disponible en espacios de trabajo que requieren geolocalización.

¿Por qué las validaciones deben coincidir?

El grupo valida la identidad del firmante una sola vez y aplica ese resultado a todos los documentos. Si los documentos exigieran validaciones distintas, alguna firma terminaría afirmando una validación que el firmante nunca completó para ese documento en particular. Por eso no puedes combinar, por ejemplo, un documento que exige validación por ARCA (AF) con otro que solo exige correo electrónico (EM).

Endpoint

POST /api/v2/document-groups
Authorization: Bearer <apikey>
Content-Type: application/json

Parámetros de la solicitud

Campo	Tipo	Requerido	Descripción
documents	array de UUID	Sí	IDs de los documentos a agrupar. No puede estar vacío y admite hasta 100 documentos. Los IDs repetidos se ignoran.
signer.email	string	Sí	Correo electrónico del firmante. Debe corresponder a un único firmante pendiente en cada documento.
delivery	string	No	Quién entrega el enlace. send (valor por defecto) envía al firmante un correo con el enlace. self no envía ninguna notificación y te deja distribuir el access_url por tus propios medios.

Ejemplo de solicitud

curl -X POST "https://connect.signatura.co/api/v2/document-groups" \
  -H "Authorization: Bearer <apikey>" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      "1f0c9d2e-8b4a-4f6c-9d3e-2a7b5c8e1f4a",
      "6e2d4b8a-3c5f-4a1e-8b7d-9f0c2e6a4d1b",
      "b4a8c1e6-5d2f-4e9b-a3c7-8e1f6b0d4a2c"
    ],
    "signer": {
      "email": "firmante@example.org"
    },
    "delivery": "send"
  }'

Ejemplo de respuesta

{
  "id": "0195b2f4-7c3a-7f1e-9a8d-3c5b7e2f9a41",
  "access_url": "https://connect.signatura.co/sign/link/AbC123.../"
}

Campos de la respuesta

Campo	Tipo	Descripción
id	string	UUID del grupo de documentos
access_url	string	URL donde el firmante accede al conjunto de documentos. Cómo se habilita depende del valor de delivery (ver Formas de entrega)

Códigos de respuesta

Código	Descripción
201	Grupo creado correctamente
400	Algún documento no cumple los requisitos (ver detalle abajo)
429	Demasiadas solicitudes (rate limiting)

Los errores 400 incluyen un mensaje que identifica el problema:

Mensaje	Causa
Uno o más documentos no están disponibles.	Algún ID no existe o el documento pertenece a otro espacio de trabajo
Uno o más documentos no están pendientes de firma.	Algún documento no está en estado PE, o la firma de ese firmante ya no está pendiente
Uno o más documentos no tienen un firmante pendiente con ese correo electrónico.	El correo no coincide con ningún firmante pendiente del documento
Uno o más documentos tienen más de un firmante con ese correo electrónico.	El documento tiene firmantes duplicados con el mismo correo, por lo que no se puede determinar cuál debe firmar
Los documentos requieren validaciones de identidad diferentes para este firmante.	Las validaciones exigidas no son idénticas en todos los documentos del grupo
Los grupos de documentos no están disponibles en espacios de trabajo que requieren geolocalización.	El espacio de trabajo tiene la política de geolocalización en modo requerido

Los mensajes se devuelven en el idioma que indiques en la cabecera Accept-Language. El resto de las restricciones (lista vacía o más de 100 documentos) se informan como errores de validación del campo documents.

La creación es atómica: si un solo documento no cumple los requisitos, no se crea el grupo ni se envía ninguna notificación.

Formas de entrega

El campo delivery define quién le hace llegar el enlace al firmante. En ambos casos el firmante debe probar que controla la casilla de correo antes de que se complete cualquier firma; lo que cambia es en qué momento lo hace.

send: entrega por Signatura

Es el valor por defecto. Signatura envía inmediatamente un correo al firmante con un enlace mágico: el access_url acompañado de un parámetro m con un segundo token que solo viaja en ese correo. Abrirlo prueba el control de la casilla, habilita la sesión de firma y redirige al access_url sin el parámetro, de modo que el token no queda en la barra de direcciones ni en el historial.

Ese token nunca se devuelve en la respuesta de la API. Quien abra el access_url sin haber pasado antes por el correo verá el mensaje "Por seguridad, este enlace solo puede abrirse desde el correo electrónico que le enviamos con sus documentos para firmar", sin ninguna opción para solicitar el acceso. Como la identidad ya quedó probada, el firmante no vuelve a validar su correo dentro del proceso de firma.

self: entrega propia

No se envía ninguna notificación: recibes el access_url y lo distribuyes por tus propios medios (tu aplicación, tu portal de clientes, tu propio correo). El enlace se abre directamente y muestra los documentos, igual que un enlace de firma de un documento individual.

En este caso la validación del correo ocurre más adelante, dentro del asistente de firma: en el paso de identidad, el firmante recibe un código de validación de un solo uso en su casilla y debe ingresarlo. Sin ese código no se completa ninguna firma.

Quién puede ver los documentos

Con delivery: "self", quien tenga el access_url puede ver los documentos del grupo, del mismo modo que en un enlace de firma individual. Trátalo como un dato sensible y entrégalo únicamente al firmante. La firma, en cambio, siempre exige el código enviado a su correo.

Qué sucede al crear un grupo de documentos

Al abrir el enlace, el firmante:

1. Ve la lista de todos los documentos pendientes del grupo y puede revisarlos uno por uno
2. Completa las validaciones de identidad que exija el conjunto —por ejemplo biometría, ARCA o SMS—, una sola vez para todos los documentos. Con delivery: "self", este paso incluye la validación del correo electrónico mediante un código; con delivery: "send", el correo ya quedó probado por el enlace mágico y no se vuelve a pedir
3. Firma todos los documentos con una única acción
4. Es redirigido a la URL de redirección del espacio de trabajo, si hay una configurada

Cada documento conserva su ciclo de vida propio: mantiene su estado, sus notificaciones webhook y su certificado de auditoría individual. El grupo es solamente la forma de presentarlos y firmarlos en conjunto.

La redirección usa otros parámetros

Al firmar un grupo, la URL de redirección recibe los parámetros g (ID del grupo) y status, en lugar de los parámetros d y s que recibe al firmar un documento individual:

https://www.example.com/success?g=0195b2f4-7c3a-7f1e-9a8d-3c5b7e2f9a41&status=success

Solo se aplica la URL de redirección configurada a nivel del espacio de trabajo. El campo complete_url que hayas enviado al crear cada documento se ignora, porque sería ambiguo entre los documentos del grupo. Si no hay ninguna URL configurada, el firmante permanece en una página de confirmación de Signatura.

La firma del conjunto se resuelve documento por documento: si alguno dejó de estar disponible entre la creación del enlace y la firma —porque venció, fue cancelado o ya había sido firmado—, ese documento se omite y el resto se firma igualmente. Reintentar la operación es seguro, ya que los documentos ya firmados no se vuelven a firmar.

Vigencia del enlace

El enlace permanece activo mientras quede al menos un documento del grupo en condiciones de ser firmado. Cuando ya no queda ninguno, el firmante ve el estado correspondiente al conjunto:

Estado	Cuándo se muestra
Completado	Todos los documentos del grupo fueron firmados
Cancelado	Algún documento del grupo fue cancelado
Vencido	Algún documento o firma del grupo venció
Rechazado	El firmante rechazó firmar algún documento del grupo

Buenas prácticas

• Verifica el estado antes de agrupar: la creación falla ante el primer documento que no cumpla los requisitos, así que conviene consultar los documentos y filtrar los que sigan pendientes para ese firmante.
• Agrupa documentos con la misma configuración de firmante: si generas los documentos desde una plantilla o un mismo flujo, las validaciones ya coincidirán.
• Crea un grupo por firmante: el enlace es personal y cubre únicamente las firmas asociadas a un correo electrónico. Si el mismo conjunto de documentos tiene varios firmantes, crea un grupo para cada uno.
• Usa webhooks: cada documento sigue emitiendo sus propios eventos, por lo que no necesitas consultar el grupo para saber qué se firmó.