JAAK
Documentacion
Contactar
guia

Guía rápida

Esta guía te llevará paso a paso para integrar verificación de identidad KYC en tu aplicación. En menos de 10 minutos tendrás tu primera verificación funcionando.

Requisitos previos

Necesitas credenciales de API (API Key y Secret). Si aún no las tienes, contacta a ventas para obtenerlas.

Paso 1: Obtén tus credenciales

Inicia sesión en el dashboard de JAAK y navega a Configuración > API Keys. Encontrarás:

  • API Key: Identificador público de tu aplicación
  • API Secret: Clave secreta para firmar solicitudes

Seguridad

Nunca expongas tu API Secret en código del lado del cliente. Todas las llamadas a la API deben realizarse desde tu servidor.

Paso 2: Crea una sesión de verificación

Crea una sesión para iniciar el proceso de verificación.

POST/api/v1/sessions

Crea una nueva sesión de verificación de identidad

curl -X POST https://api.dev.jaak.ai/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tu_api_key" \
  -H "X-API-Secret: tu_api_secret" \
  -d '{
    "verificationType": "kyc_full",
    "redirectUrl": "https://tu-app.com/verificacion-completada",
    "webhookUrl": "https://tu-app.com/api/webhooks/jaak",
    "externalId": "usuario-12345",
    "metadata": {
      "userId": "12345",
      "plan": "premium"
    }
  }'

Respuesta:

{
  "id": "ses_abc123xyz",
  "status": "pending",
  "verificationType": "kyc_full",
  "verificationUrl": "https://verify.dev.jaak.ai/ses_abc123xyz",
  "externalId": "usuario-12345",
  "expiresAt": "2024-01-16T10:30:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

URL de verificación

El verificationUrl es el enlace que debes mostrar al usuario. Puede completar la verificación desde cualquier dispositivo con cámara.

Paso 3: Redirige al usuario

Tienes dos opciones para que el usuario complete la verificación:

Opción A: Redirección

Redirige al usuario a la URL de verificación:

// Redirigir al usuario
window.location.href = session.verificationUrl;

Cuando el usuario complete (o cancele) la verificación, será redirigido a tu redirectUrl con parámetros:

https://tu-app.com/verificacion-completada?sessionId=ses_abc123xyz&status=completed

Opción B: Embed con SDK

Integra el widget de verificación directamente en tu página:

<div id="jaak-verification"></div>

<script src="https://cdn.jaak.ai/sdk/v1/jaak-kyc.min.js"></script>
<script>
  const jaak = new JaakKYC({
    sessionId: 'ses_abc123xyz',
    container: '#jaak-verification',
    onComplete: (result) => {
      console.log('Verificación completada:', result);
    },
    onError: (error) => {
      console.error('Error:', error);
    }
  });

  jaak.start();
</script>

Paso 4: Obtén los resultados

Una vez que el usuario complete la verificación, puedes obtener los resultados de dos formas:

Opción A: Consultar la API

GET/api/v1/sessions/:id

Obtiene los detalles y resultados de una sesión

curl -X GET https://api.dev.jaak.ai/api/v1/sessions/ses_abc123xyz \
  -H "X-API-Key: tu_api_key" \
  -H "X-API-Secret: tu_api_secret"

Respuesta (verificación exitosa):

{
  "id": "ses_abc123xyz",
  "status": "completed",
  "verificationType": "kyc_full",
  "result": {
    "decision": "approved",
    "confidence": 0.98,
    "checks": {
      "documentAuthenticity": "passed",
      "faceMatch": "passed",
      "liveness": "passed",
      "dataConsistency": "passed"
    }
  },
  "person": {
    "fullName": "JUAN PEREZ GARCIA",
    "firstName": "JUAN",
    "lastName": "PEREZ",
    "secondLastName": "GARCIA",
    "dateOfBirth": "1990-05-15",
    "gender": "M",
    "curp": "PEGJ900515HDFRRS09",
    "address": {
      "street": "AV REFORMA 123",
      "city": "CIUDAD DE MEXICO",
      "state": "CDMX",
      "postalCode": "06600"
    }
  },
  "document": {
    "type": "ine",
    "number": "1234567890123",
    "issueDate": "2020-01-15",
    "expiryDate": "2030-01-15"
  },
  "completedAt": "2024-01-15T10:35:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}

Opción B: Recibir webhook

Si configuraste un webhookUrl, recibirás una notificación automática:

{
  "event": "session.completed",
  "timestamp": "2024-01-15T10:35:00Z",
  "data": {
    "sessionId": "ses_abc123xyz",
    "status": "completed",
    "decision": "approved",
    "externalId": "usuario-12345"
  }
}

Verificación de webhooks

Valida la firma del webhook usando el header X-JAAK-Signature para asegurar que proviene de JAAK. Consulta la guía de webhooks para más detalles.

Estados de la sesión

| Estado | Descripción | |--------|-------------| | pending | Sesión creada, esperando que el usuario inicie | | processing | Usuario en proceso de verificación | | completed | Verificación completada exitosamente | | failed | Verificación fallida (documento inválido, liveness fallido, etc.) | | expired | La sesión expiró sin completarse |

Decisiones posibles

| Decisión | Descripción | Acción recomendada | |----------|-------------|-------------------| | approved | Identidad verificada exitosamente | Permitir acceso al usuario | | rejected | Identidad no pudo ser verificada | Solicitar verificación manual | | review | Requiere revisión manual | Revisar en dashboard de JAAK |

Siguientes pasos