Onboarding KYC

Los endpoints de Onboarding te permiten realizar verificación de identidad digital (KYC) de forma independiente o como parte de un flujo de firma electrónica.

El flujo consiste en crear una sesión de onboarding, enviar una invitación por correo o WhatsApp, y capturar documentos de identidad (INE frente/reverso) y selfie/video para verificación biométrica mediante IA.

Todos los endpoints de onboarding usan autenticación por API Key (Bearer token) para la creación de sesiones, y token de sesión para las operaciones públicas (captura, validación, completar).

El procesamiento de capturas (OCR + verificación IA) se ejecuta de forma asíncrona mediante Temporal workflows. El frontend debe hacer polling en /status/{token} para obtener los resultados.

POST/v2/onboarding/sessions

Crear sesión

Crea una nueva sesión de onboarding con un token único. Opcionalmente envía una invitación por correo electrónico al destinatario.

Request body

Name
target_email
Type
string
Description
Email del destinatario a verificar.
Name
target_name
Type
string
Description
Nombre del destinatario (para personalizar la invitación).
Name
target_phone
Type
string
Description
Teléfono del destinatario (para invitación por WhatsApp).
Name
config
Type
object
Description
Configuración de la sesión. Define qué capturas se requieren y qué verificaciones activar.
Name
config.required_captures
Type
array
Description
Lista de tipos de captura requeridos: id_front, id_back, selfie, video.
Name
config.ai_verification
Type
boolean
Description
Activar verificación IA con GPT-4o para las capturas. Default: false.
Name
config.enable_ocr
Type
boolean
Description
Activar OCR para extraer texto de la INE. Default: false.
Name
config.enable_liveness
Type
boolean
Description
Activar detección de vida (liveness). Default: false.
Name
config.callback_url
Type
string
Description
URL a la que AllSign enviará un POST con el resultado cuando la sesión se complete. Recibirás el evento onboarding.completed con los datos extraídos.
Name
send_invitation
Type
boolean
Description
Enviar invitación por email automáticamente al crear la sesión. Default: false.
Name
expires_in_hours
Type
integer
Description
Tiempo de expiración del token en horas. Default: 48.
Name
signature_id
Type
string
Description
UUID de la firma a vincular con esta sesión (para flujo integrado con firma electrónica).

Response

Devuelve la sesión creada con su token y URL pública. 201 Created en éxito.

Request

POST

/v2/onboarding/sessions

curl -X POST "https://api.allsign.io/v2/onboarding/sessions" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "target_email": "persona@ejemplo.com",
    "target_name": "Juan Pérez",
    "config": {
      "required_captures": ["id_front", "id_back", "selfie"],
      "ai_verification": true,
      "enable_ocr": true
    },
    "send_invitation": true,
    "expires_in_hours": 48
  }'

Response

Response (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "token": "abc123def456...",
  "status": "pending",
  "target_email": "persona@ejemplo.com",
  "target_name": "Juan Pérez",
  "config": {
    "required_captures": ["id_front", "id_back", "selfie"],
    "ai_verification": true,
    "enable_ocr": true
  },
  "url": "https://app.allsign.io/verificar/abc123def456...",
  "expires_at": "2024-11-25T20:00:00Z",
  "created_at": "2024-11-23T20:00:00Z",
  "existing_contact": null
}

Si el email ya tiene un contacto verificado en tu tenant, el campo existing_contact contendrá la información del contacto existente con identity_verified: true, para que puedas decidir si reutilizar la verificación previa.

POST/v2/onboarding/validate

Validar token

Valida un token de sesión y devuelve la configuración de captura. Este endpoint es público — no requiere API Key, solo el token de sesión.

Request body

Name
token
Type
string
Description
Token de la sesión de onboarding.
Name
device
Type
string
Description
Tipo de dispositivo: desktop o mobile. Afecta la generación de QR para transferencia al celular.

Request

POST

/v2/onboarding/validate

curl -X POST "https://api.allsign.io/v2/onboarding/validate" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "abc123def456...",
    "device": "desktop"
  }'

Response (200)

{
  "valid": true,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "config": {
    "required_captures": ["id_front", "id_back", "selfie"],
    "ai_verification": true
  },
  "target_name": "Juan Pérez",
  "mobile_url": "https://app.allsign.io/verificar/abc123.../mobile",
  "completed_captures": []
}

POST/v2/onboarding/capture

Subir captura

Sube una imagen o video capturado. El archivo se almacena en S3 y el procesamiento (OCR + verificación IA) se ejecuta de forma asíncrona mediante un Temporal workflow.

Este endpoint es público — usa el token de sesión para autenticación.

Request body (multipart/form-data)

Name
token
Type
string
Description
Token de la sesión de onboarding.
Name
capture_type
Type
string
Description
Tipo de captura: id_front, id_back, selfie, liveness, video.
Name
file
Type
file
Description
Archivo de imagen (JPEG/PNG) o video (WebM).
Name
device_info
Type
string
Description
JSON con información del dispositivo (browser, OS, resolución).

Request

POST

/v2/onboarding/capture

curl -X POST "https://api.allsign.io/v2/onboarding/capture" \
  -F "token=abc123def456..." \
  -F "capture_type=id_front" \
  -F "file=@./ine_frente.jpg" \
  -F "device_info={\"browser\":\"Chrome\",\"os\":\"Android\"}"

Response

Response (201)

{
  "success": true,
  "capture_id": "660e8400-e29b-41d4-a716-446655440099",
  "capture_type": "id_front",
  "ocr_status": "processing",
  "verification_status": "processing"
}

El estado "processing" indica que el workflow de Temporal está procesando la captura. Usa el endpoint de polling (GET /status/{token}) para obtener los resultados de OCR y verificación IA.

GET/v2/onboarding/status/{token}

Consultar estado

Consulta el estado actual de la sesión. El frontend debe hacer polling cada 2-3 segundos mientras hay capturas en estado "processing".

Path parameters

Name
token
Type
string
Description
Token de la sesión de onboarding.

Response (200)

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "in_progress",
  "captures": [
    {
      "capture_type": "id_front",
      "ocr_status": "success",
      "verification_status": "passed",
      "verification_confidence": 0.97,
      "pipeline_agents": ["document_quality", "face_detection"]
    },
    {
      "capture_type": "selfie",
      "ocr_status": "skipped",
      "verification_status": "processing"
    }
  ],
  "completed_captures": ["id_front"],
  "pending_captures": ["id_back", "selfie"]
}

POST/v2/onboarding/complete/{token}

Completar sesión

Marca la sesión como completada. Fusiona los resultados de OCR, crea o actualiza el contacto, y copia las capturas al perfil de identidad del usuario. Se ejecuta como un Temporal workflow con reintentos automáticos.

Path parameters

Name
token
Type
string
Description
Token de la sesión de onboarding.

Request body

Name
confirmed
Type
boolean
Description
El usuario confirma que los datos son correctos.
Name
corrections
Type
object
Description
Correcciones manuales a los datos extraídos por OCR (ej. nombre mal leído).

Request

POST

/v2/onboarding/complete/{token}

curl -X POST "https://api.allsign.io/v2/onboarding/complete/abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "confirmed": true,
    "corrections": {
      "full_name": "Juan Carlos Pérez López"
    }
  }'

Response

Response (200)

{
  "success": true,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "result_data": {
    "full_name": "Juan Carlos Pérez López",
    "document_type": "ine",
    "identity_verified": true,
    "captures_count": 3
  },
  "message": "Verificación completada exitosamente"
}

GET/v2/onboarding/prior-verification

Verificación previa

Consulta si un firmante ya tiene una identidad verificada en tu tenant. Útil para decidir si se puede reusar la verificación previa y saltar pasos de ID en el flujo de firma.

Query parameters

Name
email
Type
string
Description
Email del firmante a consultar.
Name
phone
Type
string
Description
Teléfono del firmante (fallback para firmantes solo WhatsApp).

Response (200) — Verificado

{
  "verified": true,
  "verified_at": "2024-11-20T15:30:00Z",
  "onboarding_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "captures": [
    {
      "capture_type": "id_front",
      "s3_key": "identities/USER_ID/id_front.jpg",
      "verification_status": "passed"
    },
    {
      "capture_type": "selfie",
      "s3_key": "identities/USER_ID/selfie.jpg",
      "verification_status": "passed"
    }
  ]
}

Response (200) — No verificado

{
  "verified": false
}

GET/v2/onboarding/sessions/{session_id}/result

Resultado de sesión

Obtiene los resultados completos de una sesión de onboarding, incluyendo datos extraídos, tipo de documento, y URLs pre-firmadas de las capturas. Requiere API Key con scope document:read.

Este endpoint proporciona aislamiento por tenant — solo puedes consultar sesiones de tu propia organización.

Path parameters

Name
session_id
Type
string
Description
UUID de la sesión de onboarding.

Request

GET

/v2/onboarding/sessions/{session_id}/result

curl "https://api.allsign.io/v2/onboarding/sessions/SESSION_UUID/result" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK"

Response

Response (200)

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "targetEmail": "persona@ejemplo.com",
  "targetName": "Juan Pérez",
  "verified": true,
  "verifiedAt": "2024-11-25T18:30:00Z",
  "documentType": "ine",
  "extractedName": "Juan Carlos Pérez López",
  "resultData": {
    "full_name": "Juan Carlos Pérez López",
    "curp": "PELJ900101HDFRPN09",
    "clave_elector": "PLZLPN90010109H123",
    "document_type": "ine"
  },
  "captures": [
    {
      "captureType": "id_front",
      "imageUrl": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
      "verificationStatus": "passed",
      "verificationResult": {
        "steps": [{"agent_id": "id-document-agent", "passed": true, "confidence": 0.97}]
      },
      "createdAt": "2024-11-25T18:25:00Z"
    },
    {
      "captureType": "selfie",
      "imageUrl": "https://s3.amazonaws.com/...?X-Amz-Signature=...",
      "verificationStatus": "passed",
      "verificationResult": null,
      "createdAt": "2024-11-25T18:27:00Z"
    }
  ],
  "createdAt": "2024-11-25T18:20:00Z",
  "completedAt": "2024-11-25T18:30:00Z"
}

Las URLs de imagen (imageUrl) son URLs pre-firmadas de S3 con un TTL de 1 hora. Descarga las imágenes antes de que expiren si necesitas almacenarlas.

Flujo completo

El flujo de onboarding KYC sigue este proceso:

1. Tu servidor → POST /v2/onboarding/sessions (crea sesión + envía invitación)
2. Usuario abre URL → POST /v2/onboarding/validate (obtiene config)
3. Usuario toma fotos → POST /v2/onboarding/capture (×N, una por tipo)
4. Frontend polling → GET /v2/onboarding/status/{token} (espera resultados IA)
5. Usuario confirma → POST /v2/onboarding/complete/{token}

Diagrama de arquitectura

┌────────────────┐     ┌─────────────┐     ┌──────────────────┐
│   Tu sistema   │────▶│  AllSign API │────▶│ Temporal Workflow │
│  (Backend)     │     │  (FastAPI)   │     │  (Background)    │
└────────────────┘     └──────┬──────┘     └──────────────────┘
                              │                      │
                    Crea sesión │              Procesa captura
                    + token     │              OCR + IA (async)
                              │                      │
                    ┌─────────▼─────────┐           │
                    │   Frontend/Móvil   │           │
                    │  (Captura fotos)   │◀──────────┘
                    └───────────────────┘    Resultados via
                                             polling /status

Ejemplo: Onboarding independiente (sin firma)

JavaScript — Flujo completo

// 1. Crear sesión
const session = await fetch('https://api.allsign.io/v2/onboarding/sessions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ALLSIGN_LIVE_SK',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    target_email: 'persona@ejemplo.com',
    target_name: 'Juan Pérez',
    config: {
      required_captures: ['id_front', 'selfie'],
      ai_verification: true,
    },
    send_invitation: true,
  }),
}).then(r => r.json())

// 2. Enviar la URL al usuario
console.log(`Envía esta URL al usuario: ${session.url}`)

// 3. Desde tu backend, haz polling del estado
const poll = async (token) => {
  while (true) {
    const status = await fetch(
      `https://api.allsign.io/v2/onboarding/status/${token}`
    ).then(r => r.json())

    if (status.status === 'completed') {
      console.log('✅ Verificación completada:', status.result_data)
      return status
    }

    await new Promise(r => setTimeout(r, 3000)) // Polling cada 3s
  }
}

await poll(session.token)

Ejemplo: KYC integrado con firma electrónica

cURL — Vincular con firma

# Crear un onboarding vinculado a una firma existente
curl -X POST "https://api.allsign.io/v2/onboarding/sessions" \
  -H "Authorization: Bearer ALLSIGN_LIVE_SK" \
  -H "Content-Type: application/json" \
  -d '{
    "target_email": "firmante@empresa.com",
    "target_name": "Ana García",
    "signature_id": "SIGNATURE_UUID",
    "config": {
      "required_captures": ["id_front", "id_back", "selfie", "video"],
      "ai_verification": true,
      "enable_ocr": true,
      "document_name": "Contrato de Servicios 2025"
    },
    "send_invitation": true
  }'

Cuando vinculas signature_id, el flujo de onboarding se integra con el pipeline de firma. Las capturas verificadas se asocian automáticamente al firmante y se incluyen en la evidencia del documento firmado.