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
Al menos un valor fijo del firmante que permita identificarlo: su correo electrónico (EM), su CUIT (AF) o su teléfono (PH)

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 cuyos valores fijos coincidan con todos los que indiques (ver Identificar al firmante)
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`	objeto	Sí	Identifica al firmante mediante uno o más de sus valores fijos: `EM`, `AF` o `PH` (ver Identificar al firmante).
`delivery`	string	Sí	Quién entrega el enlace. `send` envía al firmante un correo con el enlace y requiere que tenga un correo electrónico fijo. `self` no envía ninguna notificación y te deja distribuir el `access_url` por tus propios medios (ver Formas de entrega).
`complete_url`	string	No	URL `https` (hasta 200 caracteres) a la que se redirige al firmante al terminar de firmar el grupo. Reemplaza la URL de redirección del espacio de trabajo (ver Qué sucede al crear un grupo de documentos).

Identificar al firmante

El objeto signer utiliza las mismas claves que las validaciones de la creación de documentos:

Clave	Descripción
`EM`	Correo electrónico fijo del firmante. La comparación no distingue mayúsculas de minúsculas.
`AF`	CUIT fijo del firmante, con o sin guiones. Debe ser un CUIT válido de persona humana.
`PH`	Valor fijo del teléfono del firmante. Se comparan solo los dígitos, por lo que se ignoran espacios, guiones, paréntesis y el signo `+`.

Puedes enviar una o varias claves. En cada documento debe haber exactamente un firmante pendiente cuyo valor fijo coincida con cada clave enviada; un firmante que no tiene un valor fijo para esa validación (por ejemplo, porque lo ingresa al firmar) no coincide.

Por ejemplo, {"AF": "20-11111111-2"} encuentra tanto a un firmante que solo tiene la validación ARCA como a uno que además tiene un correo fijo, siempre que todos los documentos del grupo exijan las mismas validaciones.

signer.email está deprecado

La forma anterior, "signer": {"email": "..."}, sigue funcionando como equivalente de EM y, si no envías delivery, utiliza send por defecto. Dejará de aceptarse en una versión futura: reemplázala por "signer": {"EM": "..."} e indica delivery explícitamente. No se puede combinar email con EM, AF o PH en la misma solicitud.

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": {
      "EM": "firmante@example.org"
    },
    "delivery": "send"
  }'

Si el firmante solo tiene un CUIT fijo y distribuyes el enlace por tus propios medios:

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"
    ],
    "signer": {
      "AF": "20111111112"
    },
    "delivery": "self"
  }'

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 que coincida con el firmante indicado.	Ningún firmante pendiente del documento tiene valores fijos que coincidan con todas las claves de `signer`
Uno o más documentos tienen más de un firmante que coincide con el firmante indicado.	Varios firmantes del documento coinciden con `signer`, por lo que no se puede determinar cuál debe firmar. Agrega otra clave para distinguirlos
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
El firmante no tiene una dirección de correo electrónico a la cual enviar el enlace; utilice delivery "self".	Pediste `delivery: "send"` para un firmante sin correo electrónico fijo. Se informa en el campo `delivery`

Los mensajes se devuelven en el idioma que indiques en la cabecera Accept-Language. El resto de las restricciones se informan como errores de validación del campo correspondiente: lista vacía o más de 100 documentos en documents; claves desconocidas, un CUIT o teléfono inválido o un objeto vacío en signer; y la omisión de delivery.

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 completar las validaciones de identidad que exigen los documentos antes de que se complete cualquier firma; lo que cambia es cómo accede al enlace y, si tiene un correo fijo, en qué momento prueba que controla esa casilla.

`send`: entrega por Signatura

Requiere que el firmante tenga un correo electrónico fijo (EM), aunque lo hayas identificado por otra clave. 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 todas las validaciones ocurren dentro del asistente de firma, en el paso de identidad. Si los documentos exigen correo electrónico, el firmante recibe un código de validación de un solo uso en su casilla y debe ingresarlo; si exigen ARCA, inicia sesión con su clave fiscal; si exigen teléfono, recibe un código por SMS. Hasta que no las complete, no se firma ningún documento.

Es la única forma de entrega disponible para firmantes sin correo electrónico fijo, por ejemplo, los que solo tienen un CUIT fijo.

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 que complete las validaciones de identidad de los documentos.

Qué sucede al crear un grupo de documentos

Al abrir el enlace, el firmante:

Ve la lista de todos los documentos pendientes del grupo y puede revisarlos uno por uno
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", si los documentos exigen correo electrónico, este paso incluye su validación mediante un código; con delivery: "send", el correo ya quedó probado por el enlace mágico y no se vuelve a pedir
Firma todos los documentos con una única acción
Es redirigido al complete_url del grupo o, si no lo indicaste, 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

Se aplica el complete_url que hayas enviado al crear el grupo y, si no enviaste ninguno, 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. Ambas redirecciones requieren que tu cuenta tenga habilitada la personalización; si no es así, o 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 del firmante indicado en signer. 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ó.

Requisitos previos​

Endpoint​

Parámetros de la solicitud​

Identificar al firmante​

Ejemplo de solicitud​

Ejemplo de respuesta​

Campos de la respuesta​

Códigos de respuesta​

Formas de entrega​

send: entrega por Signatura​

self: entrega propia​

Qué sucede al crear un grupo de documentos​

Vigencia del enlace​

Buenas prácticas​