Participant

El objeto Participant representa a una persona que debe firmar un documento en AllSign. Cada participante tiene información de contacto (email, nombre, WhatsApp opcional) y se asocia a uno o más campos de firma dentro del documento.

Attributes

Name
email
Type
string | null
Description
Correo electrónico del participante. Se normaliza automáticamente a minúsculas y se valida el formato. No se permiten participantes duplicados en el mismo documento.
Opcional, pero sujeto a la regla XOR: debes proporcionar exactamente uno de email o whatsapp por participante — nunca ambos y nunca ninguno. Un participante con solo whatsapp es válido; enviar los dos juntos (o ninguno) responde 422.
Name
name
Type
string
Description
Nombre completo del participante (1-255 caracteres). Aparece en las invitaciones y en el documento firmado.
Name
whatsapp
Type
string | null
Description
Número de WhatsApp con código de país en formato E.164 (ej. +525512345678).
Opcional, pero parte de la regla XOR con email: exactamente uno de los dos identificadores es obligatorio. Cada participante usa un único canal de notificación: si tiene email, se envía por email; si tiene whatsapp, se envía por WhatsApp.
Name
invitedBy
Type
string
Description
Email del usuario que invitó a este participante.
Comportamiento por defecto: Si omites este campo, se asigna automáticamente el email del usuario asociado al API key que creó el documento. Esto permite rastrear quién agregó cada participante al flujo de firma.
Name
roleName
Type
string
Description
Nombre del rol a asignar a este participante (Capa 4). Su comportamiento depende del endpoint y del modo de creación:
- POST /v2/documents/{id}/add-signer y PATCH .../signers/{id} (vía confiable): la API busca un DocumentRole con ese nombre (case-insensitive) en el documento; si existe lo vincula, si no lo crea, y auto-asigna las variables que coinciden con ese rol (la respuesta lista autoAssignedVariables).
- Crear documento simple (document/templateId, modo single-doc de v2): mismo comportamiento de find/create + auto-link.
- Crear documento compound (array documents, vía principal): roleName se ignora al persistir — el rol se crea con el name del participante, sin búsqueda de rol existente ni auto-asignación de variables.
Para garantizar el auto-link de variables por rol, agrega al firmante con roleName explícito vía add-signer. Ver el edge case #2 en la guía de roles y variables.

THE PARTICIPANT OBJECT

{
  "email": "ceo@empresa.com",
  "name": "CEO Empresa",
  "invitedBy": "admin@empresa.com",
  "roleName": "Arrendador"
}

Validaciones automáticas

Normalización de email

Todos los emails se convierten a minúsculas antes de guardarse. Esto evita duplicados por diferencias de capitalización.

// Estos dos participantes se consideran duplicados:
{ email: "CEO@empresa.com", name: "CEO" }
{ email: "ceo@empresa.com", name: "CEO" }
// ❌ El segundo será rechazado con 422

Detección de canal (regla XOR)

Cada participante usa un único canal de notificación, definido por el identificador que proporciones. La API exige exactamente uno de email o whatsapp — nunca ambos a la vez:

Tiene email → se envía invitación por email
Tiene whatsapp → se envía por WhatsApp
Tiene ambos → ❌ 422 (Provide either email or whatsapp, not both)
No tiene ninguno → ❌ 422 (At least one identifier is required)

// ✅ Cada participante con un único identificador
{
  participants: [
    { email: "ceo@empresa.com", name: "CEO" }, // → email
    { name: "Firmante móvil", whatsapp: "+528125221710" }  // → WhatsApp
  ],
  config: { sendInvitations: true, startAtStep: 3 }
}

Participantes duplicados

No se permiten dos participantes con el mismo email (después de normalización). Si intentas agregar el mismo email dos veces, recibes 422 Unprocessable Entity.

Los siguientes endpoints manipulan participantes:

POST /v2/documents - Crea documento con lista inicial de participantes
POST /v2/documents/{id}/add-signer - Añade un firmante a un documento existente
DELETE /v2/documents/{id}/signers/{signature_id} - Elimina un firmante del documento

Ejemplos de uso

Participante mínimo (solo email y nombre)

{
  "email": "firmante@empresa.com",
  "name": "Juan Pérez"
}

Este es el caso más común para el setup inicial. El sistema asigna automáticamente invitedBy al creador del documento.

Participante por WhatsApp (sin email)

{
  "name": "Juan Pérez",
  "whatsapp": "+525512345678"
}

Úsalo cuando el participante deba recibir su invitación por WhatsApp. Recuerda la regla XOR: si proporcionas whatsapp, no envíes email en el mismo participante (o recibirás 422).

Participante con rol asignado (Capa 4)

{
  "email": "arrendador@inmobiliaria.com",
  "name": "Arrendador",
  "roleName": "Arrendador"
}

Úsalo cuando el documento tiene variables prefijadas por rol (p.ej. arrendador__nombre, arrendador__fecha_inicio). El auto-link de variables por rol solo es confiable vía add-signer (o PATCH .../signers/{id}): en el create compound el roleName se ignora. Ver el detalle en el atributo roleName arriba.

Notas importantes

Participantes vs. Firmantes: En AllSign, "participante" y "firmante" son sinónimos. Ambos términos se refieren a la misma entidad: una persona que debe firmar el documento.