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
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.
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
Description
Número de WhatsApp con código de país en formato E.164 (ej. +525512345678).
Opcional. Cuando config.sendInvitations=true, la API detecta automáticamente el canal: si el participante tiene email, se envía por email; si solo 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
step
Type
integer
Description
Orden de firma del participante (solo para flujos secuenciales). Si no se especifica, todos los participantes pueden firmar en paralelo.

THE PARTICIPANT OBJECT

{
  "email": "ceo@empresa.com",
  "name": "CEO Empresa",
  "whatsapp": "+525512345678",
  "invitedBy": "admin@empresa.com",
  "step": 1
}

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 inteligente de canal

Cuando config.sendInvitations=true, la API detecta automáticamente el mejor canal para cada participante:

Tiene email → se envía invitación por email (canal preferido)
Solo tiene WhatsApp → se envía por WhatsApp
Tiene ambos → se envía por email

// ✅ La API auto-detecta el canal por participante
{
  participants: [
    { email: "ceo@empresa.com", name: "CEO", whatsapp: "+525512345678" }, // → 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}/participants - Añade participantes a un documento existente
DELETE /v2/documents/{id}/participants/{email} - Elimina un participante 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 con WhatsApp para notificaciones

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

Úsalo cuando planees enviar invitaciones por WhatsApp o cuando el participante prefiera ese canal.

Participante en flujo secuencial

{
  "email": "ceo@empresa.com",
  "name": "CEO",
  "step": 1
}

El campo step define el orden de firma. Solo los participantes del paso actual pueden firmar; los demás deben esperar.

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.

Límite de participantes: Un documento puede tener hasta 50 participantes. Si intentas agregar más, el endpoint responde con 422 Unprocessable Entity.