Invitations & Signing Lifecycle

Los endpoints de Invitations te permiten enviar invitaciones de firma a los participantes de un documento. Cada invitación crea una sesión de firmante (guest session) con un link único y seguro, y puede entregarse por email, WhatsApp, o ambos.

Choosing your signing flow

AllSign soporta tres flujos de firma dependiendo de tu caso de uso. Los endpoints de esta página (start-signing, invite, invite-bulk) son opcionales si utilizas el flujo de una sola llamada.

Flujo 1: Una sola llamada (recomendado para APIs)

Crea el documento con todo incluido en POST /v2/documents. El backend se encarga de todo: créditos, invitaciones, y avanzar el status.

{
  "document": { "base64Content": "...", "name": "contrato.pdf" },
  "participants": [
    { "email": "firmante@empresa.com", "name": "Juan" }
  ],
  "signatureValidation": {
    "autografa": true,
    "videofirma": true,
    "id_scan": true
  },
  "config": {
    "startAtStep": 3,
    "sendInvitations": true
  }
}

Flujo 2: Paso a paso (dashboard)

Crea el documento sin participantes ni invitaciones, y luego configura cada parte con llamadas separadas:

Flujo 3: Auto-firma (owner es el único firmante)

Si el creador del documento es el único firmante, no se envían invitaciones — solo se avanza el status:

Comparación rápida

Validación de email

Los endpoints v2 implementan dos capas de validación para correos electrónicos. Ambas se ejecutan automáticamente — no necesitas hacer nada desde tu lado más que manejar las respuestas de error.

Capa 1: Validación de formato (schema)

La primera capa verifica que el email tenga un formato válido antes de procesar la petición. Esto se aplica a todos los campos de email en el request (participant.email, config.invitedByEmail, etc.).

Qué valida:

• Que el campo no esté vacío ni contenga solo espacios
• Que el formato cumpla usuario@dominio.extensión
• Trim y lowercase automático (ej. " Juan@Gmail.COM " → "juan@gmail.com")

Si el formato es inválido, la API retorna 422 inmediatamente sin procesar nada más:

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Invalid email format: 'correo-sin-arroba'. Expected format: user@example.com",
    "field": "participant.email"
  }
}

Emails vacíos también son rechazados:

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Email address cannot be empty.",
    "field": "participant.email"
  }
}

Capa 2: Validación de entregabilidad (SendGrid)

Si el formato es correcto, la segunda capa verifica que el buzón realmente exista usando la API de SendGrid Email Validation. Esta validación ocurre justo antes de enviar el correo.

Cuando la validación detecta un email inválido, la invitación falla con un mensaje descriptivo:

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Email 'usuario@dominio-invalido.xyz' is invalid: domain cannot receive email (no MX records)",
    "field": "participant.email"
  }
}

{
  "error": {
    "code": "E1200",
    "type": "validation_error",
    "message": "Invalid email addresses: ghost@dead.xyz: domain cannot receive email (no MX records)",
    "field": "participants[].email"
  }
}

Códigos de error

Todos los errores v2 usan el formato estándar con código numérico E1XXX. Usa error.code para manejo programático:

El campo error.field indica qué campo del request causó el error (ej. "participant.email", "participants[].email").

Flujo completo

Request con email "  " → 422 E1200 (Capa 1: formato vacío)
Request con email "invalido" → 422 E1200 (Capa 1: formato malo)
Request con email "user@fake-domain.xyz" → 422 E1200 (Capa 2: dominio sin MX)
Request con email "user@gmail.com" → ✅ (Ambas capas pasan)

Start signing

Avanza el documento de la fase de configuración (RECOLECTANDO_FIRMANTES o SELLOS_PDF) a ESPERANDO_FIRMAS, desbloqueando la firma para los participantes.

Este endpoint es idempotente — si el documento ya está en ESPERANDO_FIRMAS o en un estado posterior, retorna 200 sin hacer cambios.

Path parameters

curl -X POST "https://api.allsign.io/v2/documents/DOC_UUID/start-signing" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

{
  "success": true,
  "message": "Status advanced from RECOLECTANDO_FIRMANTES to ESPERANDO_FIRMAS",
  "previousStatus": "RECOLECTANDO_FIRMANTES",
  "currentStatus": "ESPERANDO_FIRMAS"
}

{
  "success": true,
  "message": "Already in ESPERANDO_FIRMAS, no change needed",
  "previousStatus": "ESPERANDO_FIRMAS",
  "currentStatus": "ESPERANDO_FIRMAS"
}

Invite participant

Envía una invitación de firma a un solo participante. Crea una sesión de firmante (GuestSession) con un token seguro y envía el link de firma por email y/o WhatsApp.

Path parameters

Request body

curl -X POST "https://api.allsign.io/v2/documents/DOC_UUID/invite" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "participant": {
      "email": "firmante@empresa.com",
      "name": "Juan Pérez"
    },
    "config": {
      "sendInvitationByEmail": true,
      "invitedByEmail": "admin@empresa.com",
      "invitedByName": "María López"
    }
  }'

{
  "success": true,
  "message": "Invitation sent successfully",
  "sentCount": 1,
  "failedCount": 0,
  "details": [
    {
      "participant": "firmante@empresa.com",
      "success": true,
      "guestLink": "https://app.allsign.io/firmar/abc123..."
    }
  ]
}

Invite bulk

Envía invitaciones de firma a múltiples participantes en una sola llamada. Cada participante recibe su propia GuestSession y link único.

Path parameters

Request body

curl -X POST "https://api.allsign.io/v2/documents/DOC_UUID/invite-bulk" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      { "email": "firmante1@empresa.com", "name": "Ana García" },
      { "email": "firmante2@empresa.com", "name": "Carlos Ruiz" }
    ],
    "config": {
      "sendInvitationByEmail": true,
      "sendInvitationByWhatsapp": false,
      "invitedByEmail": "admin@empresa.com"
    }
  }'

{
  "success": true,
  "message": "Processed 2 invitations. Sent: 2, Failed: 0",
  "sentCount": 2,
  "failedCount": 0,
  "details": [
    {
      "participant": "firmante1@empresa.com",
      "success": true,
      "guestLink": "https://app.allsign.io/firmar/token1..."
    },
    {
      "participant": "firmante2@empresa.com",
      "success": true,
      "guestLink": "https://app.allsign.io/firmar/token2..."
    }
  ]
}