Endpoint de Verificación Biométrica KYC

Descripción General

El endpoint /api/v1/kyc/verify permite procesar verificaciones biométricas completas combinando detección de vida (liveness), comparación facial y validación de documentos de identidad. Este endpoint es flexible y acepta diferentes combinaciones de datos según las necesidades de tu flujo de verificación.

Configuración Inicial

URLs de API según Ambiente

Métodos de Inicio de Sesión

JAAK ofrece DOS MÉTODOS para iniciar el proceso de verificación KYC. Ambos métodos obtienen un access_token que se utilizará en todos los servicios posteriores.

Comparación de Métodos

¿Cuál método elegir?

Elige Método A (Por Licencia) si:

• Quieres control total del frontend y UX
• Implementas todo el flujo de captura en tu aplicación
• No necesitas las pantallas de captura de JAAK
• No requieres notificaciones automáticas
• Prefieres un flujo más directo con menos pasos

Elige Método B (Sesión + ShortKey) si:

• Quieres usar las pantallas de captura de JAAK
• Necesitas enviar notificaciones automáticas (email/SMS/WhatsApp)
• Prefieres una implementación híbrida
• Quieres gestionar múltiples sesiones con identificadores únicos
• Necesitas una URL de sesión compartible

💡 Nota: Ambos métodos obtienen traceparent para trazabilidad distribuida. La diferencia principal es el control sobre la UI y las capacidades de notificación.

MÉTODO A: Inicio por Validación de Licencia

Este método proporciona acceso directo a los servicios de verificación.

Paso 1A: Validar Licencia

Endpoint

POST /api/v1/license/validate

Headers

Content-Type: application/json
traceparent: 00-<trace-id>-<span-id>-<flags>

Ejemplo de traceparent:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Request Body

{
  "license": "TU_CODIGO_DE_LICENCIA",
  "product": "KYC",
  "product_version": "1.0",
  "app_id": "mi-app-id",
  "origin": "https://mi-app.com",
  "challenge": "string",
  "attestation_token": "string",
  "integrity_token": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string"
  }
}

Parámetros

Requeridos:

• license (string): Código de licencia proporcionado por JAAK
• product (string): Nombre del producto (ej: "KYC")
• product_version (string): Versión del producto
• app_id (string): Identificador de la aplicación
• origin (string): Origen de la solicitud

Opcionales:

• challenge (string): Token de desafío para validación adicional
• attestation_token (string): Token de attestation
• integrity_token (string): Token de integridad
• metadata (object): Metadatos adicionales

Response (200 OK)

Headers de Respuesta:

traceparent: 00-<trace-id>-<span-id>-<flags>

Body:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_at": "2024-01-15T12:00:00Z",
  "session_id": "uuid-session-id",
  "jti": "jwt-token-id",
  "license": "TU_CODIGO_DE_LICENCIA",
  "step": 0,
  "document": "INE",
  "assets": {
    "document": "string",
    "liveness": "string"
  }
}

Ejemplo de Llamada

curl -X POST https://sandbox.api.jaak.ai/api/v1/license/validate \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{
    "license": "TU_CODIGO_DE_LICENCIA",
    "product": "KYC",
    "product_version": "1.0",
    "app_id": "mi-app-id",
    "origin": "https://mi-app.com"
  }'

⚠️ Consideraciones Importantes

• Consumo de Token: Cada llamada a este endpoint consume un token de la cuota de tu licencia
• Access Token: El access_token recibido debe ser utilizado en todas las llamadas subsecuentes
• Traceparent Crítico: El header traceparent retornado en la respuesta DEBE ser enviado en TODOS los endpoints subsecuentes para mantener la trazabilidad distribuida

MÉTODO B: Inicio por Creación de Sesión

Este método crea una sesión gestionada e intercambia un shortkey por un access token.

Paso 1B: Crear Sesión KYC

Inicializa una nueva sesión de verificación para un cliente.

Endpoint

POST /api/v1/kyc/flow

Headers

Content-Type: application/json

Request Body

{
  "name": "María González Pérez",
  "flow": "Cliente-001-Onboarding",
  "redirectUrl": "https://tu-empresa.com/kyc-completado",
  "countryDocument": "MEX",
  "flowType": "KYC",
  "verificationType": "email",
  "verification": {
    "SMS": "",
    "EMAIL": "[email protected]",
    "WHATSAPP": ""
  }
}

Parámetros Detallados

Opciones de Notificación

Response Esperado

{
  "sessionUrl": "https://sandbox.kyc.jaak.ai/session/ABC123X"
}

💡 Nota: El shortKey es: ABC123X (últimos 7 caracteres de la URL)

Paso 2B: Intercambiar ShortKey por Token

Obtiene un token de acceso para realizar operaciones en la sesión KYC.

Endpoint

POST /api/v1/kyc/session

Headers

Content-Type: application/json
Short-Key: ABC123X
Origin-Device: API

Request Body

{}

Response Esperado

Headers de Respuesta:

traceparent: 00-cf143715d7a2d4ffc3ef122f62384844-6f7048446dffdb89-00
x-trace-id: 32922b9bf22570da5e9895fa592c6852

Body:

{
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "step": 1,
  "sessionId": "uuid-sesion-id",
  "assets": {
    "document": null,
    "liveness": null
  },
  "document": "MEX"
}

⚠️ Importante

• Access Token: El accessToken debe usarse en todas las siguientes llamadas con el header:

  Authorization: Bearer [ACCESS-TOKEN]

• Traceparent: El header traceparent retornado en la respuesta DEBE ser enviado en TODOS los endpoints subsecuentes de verificación para mantener la trazabilidad distribuida de las peticiones.

Paso 2: Verificación Biométrica

Endpoint de Verificación Biométrica KYC

Descripción General

El endpoint /api/v1/kyc/verify permite procesar verificaciones biométricas completas combinando detección de vida (liveness), comparación facial y validación de documentos de identidad. Este endpoint es flexible y acepta diferentes combinaciones de datos según las necesidades de tu flujo de verificación.

Una vez validada tu licencia y obtenido el access_token, procede con la verificación biométrica.

Endpoint

• URL: /api/v1/kyc/verify
• Método: POST
• Tipo de contenido: application/json

Autenticación

Este endpoint requiere autenticación mediante Bearer Token utilizando el access_token obtenido del endpoint de validación de licencia.

Header de Autorización

Authorization: Bearer {ACCESS_TOKEN}

⚠️ Importante:

• El Bearer Token es el access_token recibido en el paso de validación de licencia
• El header traceparent debe ser enviado en todas las peticiones para trazabilidad distribuida
• El Session ID se extrae automáticamente del token JWT y se utiliza para actualizar el estado de la sesión en Redis

Headers

Ejemplo de Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Language: es

Parámetros del Request Body

Todos los campos son opcionales, lo que permite realizar diferentes combinaciones de verificación según tu caso de uso.

Estructura del Request

{
  "document": {
    "front": "string",
    "back": "string",
    "force": true
  },
  "face": {
    "image": "string",
    "force": true
  },
  "liveness": {
    "video": "string",
    "force": true
  },
  "location": {
    "latitude": 0,
    "longitude": 0,
    "force": true
  }
}

Descripción de Parámetros

document (objeto, opcional)
Imágenes del documento de identidad.

• front (string): Imagen en base64 del frente del documento
• back (string): Imagen en base64 del reverso del documento
• force (boolean): Forzar procesamiento aunque ya exista en sesión

face (objeto, opcional)
Imagen facial para comparación.

• image (string): Imagen facial en base64
• force (boolean): Forzar procesamiento aunque ya exista en sesión

liveness (objeto, opcional)
Video para detección de vida.

• video (string): Video en base64 para prueba de vida
• force (boolean): Forzar procesamiento aunque ya exista en sesión

location (objeto, opcional)
Coordenadas geográficas de la verificación.

• latitude (number): Latitud de la ubicación
• longitude (number): Longitud de la ubicación
• force (boolean): Forzar procesamiento aunque ya exista en sesión

Respuestas

200 - Verificación Exitosa

La respuesta incluye los resultados de todos los procesos de verificación ejecutados:

{
  "liveness": {
    "status": "string",
    "score": 0,
    "message": "string",
    "error": "string",
    "cached": true,
    "results": {},
    "details": {}
  },
  "face": {
    "status": "string",
    "score": 0,
    "message": "string",
    "error": "string",
    "cached": true,
    "results": {},
    "details": {}
  },
  "document": {
    "extract": {
      "status": "string",
      "score": 0,
      "message": "string",
      "results": {},
      "details": {}
    },
    "verify": {
      "status": "string",
      "score": 0,
      "message": "string",
      "results": {},
      "details": {}
    }
  },
  "blacklist": {
    "ine": {},
    "renapo": {},
    "sat": {},
    "interpol": {},
    "ofac": {}
  },
  "oto": {
    "status": "string",
    "score": 0,
    "results": {}
  },
  "location": {
    "status": "string",
    "results": {}
  },
  "summary": {
    "is_complete": true,
    "finish_called": true,
    "missing_processes": []
  }
}

Campos de la Respuesta

• liveness: Resultado de la prueba de vida
• face: Resultado de la comparación facial
• document: Extracción y verificación del documento
• blacklist: Consultas en listas negras (INE, RENAPO, SAT, Interpol, OFAC)
• oto: Verificación One-to-One (1:1)
• location: Validación de ubicación
• summary: Resumen del estado de la verificación
  • is_complete: Indica si el proceso está completo
  • missing_processes: Lista de procesos faltantes

400 - Bad Request

{
  "statusCode": 400,
  "message": "string",
  "errorCode": "string",
  "eventId": "string"
}

Causas comunes:

• Session ID no encontrado en el token
• Formato de datos inválido
• Campos requeridos faltantes

401 - Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized - requires valid access token",
  "errorCode": "string",
  "eventId": "string"
}

Causas comunes:

• Access token inválido o expirado
• Bearer token no proporcionado
• Access token no obtenido correctamente del endpoint de validación de licencia

500 - Internal Server Error

{
  "statusCode": 500,
  "message": "string",
  "errorCode": "string",
  "eventId": "string"
}

Examples of Use

Nota: En todos los ejemplos, ACCESS_TOKEN_FROM_LICENSE_VALIDATION es el access_token obtenido del endpoint /api/v1/license/validate.

Ejemplo 1: Verificación Completa

curl -X POST https://api.jaak.mx/api/v1/kyc/verify \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_LICENSE_VALIDATION" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -H "Language: es" \
  -H "Content-Type: application/json" \
  -d '{
    "liveness": {
      "video": "base64_video_string",
      "force": false
    },
    "face": {
      "image": "base64_image_string",
      "force": false
    },
    "document": {
      "front": "base64_front_image",
      "back": "base64_back_image",
      "force": false
    },
    "location": {
      "latitude": 19.4326,
      "longitude": -99.1332,
      "force": false
    }
  }'

Ejemplo 2: Solo Liveness y Face Match

curl -X POST https://api.jaak.mx/api/v1/kyc/verify \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_LICENSE_VALIDATION" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -H "Language: es" \
  -H "Content-Type: application/json" \
  -d '{
    "liveness": {
      "video": "base64_video_string"
    },
    "face": {
      "image": "base64_image_string"
    }
  }'

Ejemplo 3: Solo Documento

curl -X POST https://api.jaak.mx/api/v1/kyc/verify \
  -H "Authorization: Bearer ACCESS_TOKEN_FROM_LICENSE_VALIDATION" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -H "Language: es" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "front": "base64_front_image",
      "back": "base64_back_image"
    }
  }'

Notas Importantes

• Flexibilidad: Puedes enviar cualquier combinación de parámetros según tu flujo de verificación
• Caché: El sistema utiliza caché para optimizar procesos repetidos. Usa force: true para forzar un nuevo procesamiento
• Session ID: Se extrae automáticamente del token, no es necesario enviarlo como parámetro
• Formato Base64: Todas las imágenes y videos deben estar codificados en base64
• Estado de Sesión: Cada llamada actualiza el estado de la sesión en Redis
• Traceparent: El header traceparent obtenido de la validación de licencia debe ser enviado en todas las peticiones para trazabilidad E2E

Casos de Uso Comunes

Paso 3: Consulta Detalles de Sesión

A continuación, te mostramos cómo visualizar las sesiones KYC realizadas mediante API.

Endpoint

• URL: /api/v1/kyc/session/<sessionID>
• Método: GET
• Tipo de contenido: application/json

El parámetro <sessionID> en la URL de arriba, corresponde con el parámetro sessionID de una Sesión KYC. Este parámetro sessionID se puede encontrar dentro de las propiedades preliminares al listar las sesiones KYC.

Autenticación

Este endpoint requiere autenticación mediante Bearer Token de tipo API Key, el cual se obtiene desde el Dashboard de JAAK.

Authorization: Bearer {API_KEY_FROM_DASHBOARD}

⚠️ Nota importante: Este Bearer Token es diferente al access_token del endpoint de validación de licencia. Este debe ser una API Key obtenida directamente desde tu dashboard de JAAK.

Headers Requeridos

Ejemplo de Headers

Authorization: Bearer sk_live_abc123xyz789...
Origin-Device: web

Respuestas

200 - OK

Retorna el token JWT de sesión junto con los assets procesados (documento y liveness).

Headers de Respuesta:

• X-Trace-ID (string): OpenTelemetry trace ID para distributed tracing

{
  "sessionId": "string",
  "accessToken": "string",
  "step": 0,
  "document": "string",
  "assets": {
    "document": {
      "status": true,
      "message": "string",
      "requestId": "string",
      "eventId": "string",
      "processingTime": "string",
      "documentType": {
        "type": "UNDEFINED",
        "country": "UNDEFINED"
      },
      "documentMetadata": "string",
      "documentData": {
        "mechanicalReadingZone": "string",
        "generalData": {
          "type": "string",
          "name": "string",
          "secondName": "string",
          "surname": "string",
          "motherSurname": "string",
          "gender": "string",
          "birthDate": "string",
          "country": "string",
          "validUntil": "string",
          "address": {
            "street": "string",
            "externalNumber": "string",
            "internalNumber": "string",
            "neighborhood": "string",
            "city": "string",
            "council": "string",
            "state": "string",
            "zipCode": "string",
            "fullAddress": "string"
          },
          "documentImage": {
            "photo": "string",
            "position": {
              "top": 0,
              "left": 0,
              "bottom": 0,
              "right": 0
            }
          }
        },
        "specificData": [
          {
            "label": "string",
            "value": "string"
          }
        ]
      },
      "state": {
        "supportedDocument": true,
        "isExpired": true,
        "isUnderAge": true,
        "message": "string"
      }
    },
    "liveness": {
      "requestId": "string",
      "eventId": "string",
      "score": 0,
      "processTime": 0,
      "bestFrame": "string",
      "state": {
        "isRealPerson": true,
        "message": "string"
      }
    }
  }
}

Campos de la Respuesta

Campos Principales:

• sessionId (string): ID de la sesión KYC
• accessToken (string): Token JWT de sesión
• step (number): Paso actual del flujo KYC
• document (string): Tipo de documento procesado

Assets - Document:

• status (boolean): Estado del procesamiento del documento
• message (string): Mensaje descriptivo del resultado
• documentType: Tipo y país del documento procesado
• documentData: Datos extraídos del documento
  • generalData: Información general (nombre, apellidos, género, fecha de nacimiento, dirección, etc.)
  • mechanicalReadingZone: Zona de lectura mecánica (MRZ)
  • specificData: Datos específicos del documento (CURP, CIC, etc.)
• state: Estado del documento
  • supportedDocument: Si el documento es soportado
  • isExpired: Si el documento está vencido
  • isUnderAge: Si la persona es menor de edad

Assets - Liveness:

• score (number): Puntuación de la prueba de vida (0-100)
• bestFrame (string): Mejor frame capturado en base64
• state: Estado de la prueba
  • isRealPerson: Si se detectó una persona real
  • message: Mensaje descriptivo del resultado

400 - Bad Request

{
  "statusCode": 400,
  "message": "string",
  "errorCode": "string",
  "eventId": "string"
}

Causas comunes:

• Headers faltantes (Short-Key u Origin-Device)
• Shortkey expirado o inválido
• Estado de sesión inválido

500 - Internal Server Error

{
  "statusCode": 500,
  "message": "string",
  "errorCode": "string",
  "eventId": "string"
}

Ejemplo de Uso

curl -X GET https://api.jaak.mx/api/v1/kyc/session \
  -H "Authorization: Bearer sk_live_abc123xyz789..." \
  -H "Short-Key: 7f3e4d2c1b9a8f6e5d4c3b2a1" \
  -H "Origin-Device: web"

Respuesta Ejemplo

HTTP/1.1 200 OK
X-Trace-ID: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Content-Type: application/json

{
  "sessionId": "sess_abc123",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "step": 2,
  "document": "INE",
  "assets": {
    "document": {
      "status": true,
      "message": "Documento procesado exitosamente",
      ...
    },
    "liveness": {
      "score": 95,
      "state": {
        "isRealPerson": true,
        "message": "Persona real detectada"
      },
      ...
    }
  }
}

Flujo de Uso Típico

1. Crear un flow KYC mediante POST /api/v1/kyc/flow y obtener el shortkey
2. Intercambiar el shortkey usando este endpoint para obtener el JWT de sesión
3. Utilizar el accessToken devuelto para consultas subsecuentes o para obtener los assets procesados

Notas Importantes

• API Key vs Access Token: No confundir el Bearer Token de este endpoint (API Key del dashboard) con el access_token del endpoint de validación de licencia
• Shortkey válido: El shortkey debe ser válido y no haber expirado
• Distributed Tracing: El header X-Trace-ID en la respuesta permite el seguimiento distribuido de la petición
• Origin Device: Es obligatorio especificar el origen del dispositivo (web, android, ios)
• Assets disponibles: Los assets (documento y liveness) solo estarán disponibles si ya fueron procesados en la sesión

Soporte

Si tienes dudas o necesitas asistencia con la integración, contacta a nuestro equipo de soporte:

• E-mail: [email protected]
• Documentación: https://docs.jaak.mx