Sesiones alojadas

Una sesión alojada es la forma más sencilla de recopilar documentos. Usted crea la solicitud en el servidor, pide a Certivant una URL de sesión y se la entrega al solicitante. Certivant gestiona la carga de documentos, la captura con cámara, la prueba de vida, los comentarios del OCR y los reintentos: usted solo espera el webhook.

Cuándo usar una sesión

La mayoría de las integraciones usan sesiones. La carga de documentos por API es una vía de escape para casos especiales.

Generar una URL de sesión

POST /api/v1/kyc/requests/:id/session-url    Ámbito: kyc:write

La solicitud debe estar en estado PENDING_UPLOAD.

Cuerpo de la solicitud

{
  "expiresInHours": 72,
  "redirectUrl": "https://yourapp.example.com/onboarding/complete"
}

Respuesta

{
  "sessionUrl": "https://app.certivant.com/s/01HZ7K8Y...",
  "expiresAt": "2026-05-30T10:00:00.000Z"
}

La URL contiene un token firmado de un solo uso. Tras caducar (o tras el envío del solicitante), queda invalidada. Genere una nueva si el solicitante necesita otro intento.

El flujo del solicitante

graph LR
  A[You email the session URL] --> B[Applicant clicks]
  B --> C[Welcome screen with your branding]
  C --> D[Capture front of ID]
  D --> E[Capture back of ID]
  E --> F[Capture selfie + liveness]
  F --> G[Confirm details extracted from ID]
  G --> H[Submit]
  H --> I[Thank-you page]
  I --> J{redirectUrl set?}
  J -->|yes| K[Redirect to your URL]
  J -->|no| L[Stay on Certivant page]
  H -.->|automatically| M[POST /submit fires]
  M -.->|webhook| N[kyc.request.processing]

El solicitante no necesita una cuenta para usar la URL de sesión: Certivant no le emite un inicio de sesión. Hace clic, completa el flujo y se marcha. Todo el estado reside en la solicitud, no en un registro de usuario.

Marca propia y marca blanca

La interfaz alojada toma la configuración de marca blanca de su organización (logotipo, color de marca, correo de soporte, dominio personalizado si lo configuró). Configúrelo una vez en Configuración → Marca blanca del panel; todas las sesiones lo heredan.

Dominios personalizados

Por defecto, las URL de sesión y de formularios alojados viven en el host compartido de Certivant (app.certivant.com/s/…). Si las quiere en su propio dominio (verify.yourcompany.com, por ejemplo), configure un dominio personalizado en Configuración → Marca blanca → Dominio personalizado. Esto solo cambia los enlaces que ven los solicitantes: el host de la API y su ruta base /api/v1/kyc no cambian, y su organización sigue identificándose mediante su clave de API.

Móvil frente a escritorio

La sesión es adaptable y funciona en teléfonos, tabletas y ordenadores. La captura de documentos usa la cámara del dispositivo en móviles; en escritorio, Certivant pide al solicitante que cambie a su teléfono mediante un código QR, para que la prueba de vida y el escaneo del documento usen la cámara de mejor calidad. Es automático: su integración no necesita detectar nada.

Qué ocurre después del envío

Cuando el solicitante hace clic en Enviar en la página alojada:

1. Certivant llama internamente a POST /requests/:id/submit en nombre del solicitante.
2. La solicitud pasa a PROCESSING.
3. Se dispara el primer webhook: kyc.request.processing.
4. El procesamiento termina (normalmente en segundos). Se dispara un segundo webhook: kyc.request.approved, kyc.request.rejected o kyc.request.escalated.
5. Si indicó un redirectUrl, el solicitante es enviado allí. En caso contrario, ve una página de agradecimiento.

Su backend debe esperar al webhook: no consulte el endpoint de la solicitud para detectar la finalización. Consulte Webhooks.

Reutilizar una URL de sesión tras un rechazo

Si la solicitud se rechaza y llama a POST /requests/:id/resubmit, la URL de sesión existente no se reactiva. Genere una nueva:

# 1. Reset the rejected request
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../resubmit \
  -H "Authorization: Bearer ck_live_..."

# 2. Generate a fresh session URL
curl -X POST https://app.certivant.com/api/v1/kyc/requests/req_.../session-url \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{"expiresInHours": 24}'

Después, envíe la nueva URL al solicitante. Consejo: use el mismo externalRef para que la fila de su base de datos siga correlacionada.

Los formularios como alternativa

Si necesita recopilar datos estructurados (no solo documentos), como respuestas a cuestionarios de cumplimiento, detalles del origen de los fondos o campos KYB adicionales, use Formularios en lugar de la sesión (o además de ella). Los formularios viven en el panel, en KYC → Formularios, y cada uno tiene una URL pública de envío: https://app.certivant.com/forms/:slug.

Los formularios crean automáticamente una solicitud KYC al enviarse, adjuntan las respuestas del formulario como metadatos y disparan los mismos webhooks. Consulte la documentación para clientes sobre Formularios para la configuración. Los desarrolladores normalmente no interactúan con los formularios mediante la API: el creador de formularios del panel es la interfaz prevista.

Errores

• 400 BAD_REQUEST: la solicitud no está en PENDING_UPLOAD. Solo puede generar URL de sesión para solicitudes que esperan documentos.
• 400 VALIDATION_ERROR: expiresInHours está fuera del intervalo de 1 a 168, o redirectUrl no es una URL válida.

Notas de seguridad

• La URL de sesión contiene un token firmado: cualquiera que tenga la URL puede completar la verificación. Trátela como un enlace de restablecimiento de contraseña: envíela directamente al solicitante por un canal al que solo él pueda acceder.
• Use expiresInHours cortos (24 o 48) en flujos de alto riesgo. Use una caducidad más larga solo cuando se espere que el solicitante necesite tiempo para reunir los documentos.
• Si una sesión caduca sin usarse, la solicitud subyacente permanece en PENDING_UPLOAD. Genere una nueva URL o contacte con el solicitante para reenviarla.