Firmar en orden

De forma predeterminada, cuando cargas un documento con varios firmantes todos reciben la invitación al mismo tiempo. Con la opción Firmar en orden puedes organizar a los firmantes en pasos: los firmantes del paso 1 se invitan al crear el documento y cada paso siguiente se invita recién cuando todos los firmantes de los pasos anteriores hayan firmado. Este tutorial explica cómo configurarlo utilizando la API de Signatura y qué sucede durante el proceso de firma.

Los firmantes que comparten un paso firman en paralelo. Un orden estrictamente lineal (primero A, después B, después C) es el caso en que cada paso tiene un único firmante.

Casos de uso comunes

• Un gerente debe aprobar y firmar antes de que el documento llegue al empleado
• El emisor de un contrato firma primero y recién después se libera a la contraparte
• Varios socios firman en paralelo y, cuando todos terminaron, firma un apoderado

Requisitos previos

Para firmar en orden necesitas:

• Una API key válida
• Tener un plan mensual en Signatura
• Un documento con al menos dos firmantes

Configurar el orden

El orden se define al cargar el documento, junto con el resto de la configuración de los firmantes. Cada firmante acepta el campo order (entero, a partir de 1) en el endpoint POST /api/v2/documents/create, que indica el paso en el que firma.

Ten en cuenta:

• Los valores deben ser consecutivos empezando en 1: 1, 1, 2 es válido y 1, 3 se rechaza.
• Para que dos o más personas firmen en paralelo, asígnales el mismo valor de order.
• Si omites order, todos los firmantes quedan en el paso 1 y el comportamiento es el habitual.
• order no puede combinarse con required_signatures (firmas requeridas M de N): la creación devuelve 400.

Ejemplo de solicitud

POST /api/v2/documents/create
Content-Type: application/json
Authorization: Bearer <apikey>

{
  "title": "Contrato de servicios",
  "file_content": "<base64-encoded-file>",
  "signatures": [
    {
      "validations": {"EM": "gerente@example.org"},
      "invite_channel": ["EM"],
      "order": 1
    },
    {
      "validations": {"EM": "director@example.org"},
      "invite_channel": ["EM"],
      "order": 1
    },
    {
      "validations": {"EM": "empleado@example.org"},
      "invite_channel": ["EM"],
      "order": 2
    }
  ]
}

En este ejemplo, el gerente y el director se invitan de inmediato y en paralelo; el empleado recién cuando ambos hayan firmado.

Qué sucede durante el proceso de firma

1. Al crear el documento, solo los firmantes del paso 1 reciben la invitación por email o SMS.
2. Las firmas de los pasos siguientes quedan En espera (WA): la firma existe, pero la invitación no se envía.
3. Cuando el último firmante de un paso completa su firma, Signatura libera el paso siguiente: envía las invitaciones y esas firmas pasan a Inicial (IN).
4. El proceso se repite hasta que firma el último paso y el documento pasa a Completado (CO).

El estado En espera (WA) se suma a los estados de una firma y solo aparece en documentos que usan order mayor a 1.

La espera es una restricción real y no solo un envío demorado. Si un firmante en espera abre su enlace de firma (por ejemplo, porque compartiste un enlace de invitación antes de tiempo), ve la página Esperando a los firmantes anteriores con el mensaje "Todavía no es su turno de firmar. Podrá firmar este documento cuando los firmantes anteriores hayan completado sus firmas." No puede firmar ni rechazar el documento, y la página no revela quiénes son los firmantes anteriores.

Todos firman el mismo PDF

El orden define cuándo se invita a cada persona, no el contenido que ve. Los firmantes de pasos posteriores ven el mismo PDF que los anteriores; las firmas ya realizadas no se muestran en la página de firma.

Seguimiento del proceso

Al consultar el documento con GET /api/v2/documents/{id}, cada firma incluye su campo order y su estado, con lo que puedes saber en qué paso se encuentra el proceso:

Estado	Qué significa
En espera (WA)	Su paso todavía no fue liberado. El firmante será invitado cuando los firmantes de los pasos anteriores hayan firmado
Inicial (IN)	Su paso fue liberado y recibió la invitación, pero aún no la abrió
Leído (PE)	Abrió la invitación, pero aún no firmó
Completado (CO)	Completó su firma
Rechazado (DE)	Rechazó firmar el documento

No hay un evento webhook nuevo: la liberación de un paso coincide con el evento DS del último firmante del paso anterior. Usa ese evento como indicio del cambio y consulta el detalle del documento para conocer el estado actualizado de cada firma.

Mientras una firma está en espera:

• Reenviar la invitación devuelve 400: la firma está esperando a los firmantes anteriores.
• Los recordatorios automáticos del espacio de trabajo tampoco se le envían. Solo llegan a los firmantes que ya fueron invitados.

Rechazos, reemplazos y vencimientos

Si un firmante rechaza, la cadena se detiene: los pasos siguientes no se liberan y no ocurre nada automático. El rechazo se notifica con el evento SD, como en cualquier otro documento. A partir de ahí puedes:

• Invalidar la firma rechazada y reemplazar al firmante. El reemplazo conserva el mismo paso y, como ese paso ya estaba liberado, recibe la invitación de inmediato.
• Cancelar el documento.

Reemplazar a un firmante mediante invalidar la firma conserva siempre su paso. Si el firmante estaba en espera, el reemplazo también queda en espera. Si invalidas una firma ya completada de un paso anterior, el documento vuelve a Pendiente (PE), pero los pasos que ya habían sido invitados no se retiran: la liberación de un paso no se deshace.

Los vencimientos funcionan así:

• El vencimiento del documento, configurado en el espacio de trabajo, es global y no se reinicia con cada paso. Si el documento vence, vence para todos los pasos, incluidos los que nunca llegaron a invitarse.
• La vigencia del enlace de firma de cada firmante empieza a contar cuando se libera su paso, no cuando se creó el documento. Así, un paso tardío nunca se encuentra vencido antes de ser invitado.

La integración con HubSpot también permite activar Firmar en orden desde su formulario de firmantes.

Consulta la referencia de la API para ver el detalle del campo order.