Guía de integración vía Android

⏱️ Tiempo estimado: 45-60 minutos para una integración completa

Objetivo del Manual

Este manual te guiará paso a paso en la integración de la solución JAAK KYC dentro de tu aplicación Android. Aprenderás a configurar tu entorno de desarrollo y realizar todas las llamadas API necesarias para un proceso de verificación de identidad completo, desde la obtención del token de sesión hasta la finalización de la verificación.

No necesitas conocimientos profundos de SDKs de biometría - nos enfocaremos en la integración de servicios JAAK a través de sus APIs REST.

Requisitos Previos

Antes de comenzar, asegúrate de tener:

Entorno de Desarrollo

• Android Studio: Versión recomendada (ej. Meerkat)
• SDK de compilación: 35
• Java: Versión 11 para compatibilidad
• minSdkVersion: 24
• targetSdkVersion: 35

Credenciales JAAK

• ShortKey: Identificador único de sesión KYC
• API Key: Clave de autenticación válida para servicios JAAK

Contenido

1. Configuración del Entorno
2. Flujo de Integración
3. SDKs Adicionales
4. Solución de Problemas
5. Soporte
6. Glosario

1. Configuración del Entorno

1.1 Configuración del Proyecto Android

Crear nuevo proyecto:

1. Abre Android Studio
2. Selecciona "Nuevo Proyecto" → "Empty Activity"
3. Configura el lenguaje como Kotlin
4. Asigna nombre a tu aplicación

Configurar archivos de construcción:

En libs.versions.toml:

[versions]
kotlin = "1.9.0"
retrofit = "2.9.0"
okhttp = "4.11.0"
# ... otras versiones

En build.gradle (Project):

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'dagger.hilt.android.plugin'
    id 'org.jetbrains.kotlin.kapt'
}

En build.gradle (Module: app):

android {
    compileSdk 35
    
    defaultConfig {
        minSdk 24
        targetSdk 35
    }
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_11
        targetCompatibility JavaVersion.VERSION_11
    }
}

1.2 Configuración de Retrofit

Agregar dependencias:

implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.okhttp3:okhttp:4.11.0'
implementation 'com.squareup.okhttp3:logging-interceptor:4.11.0'

Configurar cliente HTTP:

interface JaakApiService {
    @POST("api/v1/kyc/session")
    suspend fun sessionApi(
        @Header("Short-Key") shortKey: String,
        @Header("Origin-Device") originDevice: String
    ): Response<SessionResponse>
    
    // ... otras definiciones API
}

2. Flujo de Integración

2.1 Paso 1: Obtener Token de Sesión

Intercambiar ShortKey por Token de Sesión KYC

@POST("api/v1/kyc/session")
suspend fun sessionApi(
    @Header("Short-Key") shortKey: String,
    @Header("Origin-Device") originDevice: String
): Response<SessionResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v1/kyc/session

Headers:

• Short-Key: Tu ShortKey de sesión KYC
• Origin-Device: Identificador del dispositivo (ej. "API")

Response: Recibirás el accessToken (Token de Sesión KYC), step actual, sessionId y assets.

2.2 Paso 2: Registro de Geolocalización

Registrar ubicación del dispositivo

Permisos en AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Dependencia:

implementation 'com.google.android.gms:play-services-location:21.0.1'

Implementación:

@SuppressLint("MissingPermission")
private fun getLastKnownLocation() {
    fusedLocationClient.lastLocation.addOnSuccessListener { location ->
        if (location != null) {
            // Usar location.latitude, location.longitude para la API
        }
    }
}

API Call:

@POST("api/v1/kyc/session/location")
suspend fun locationApi(
    @Body request: LocationRequest
): Response<LocationResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v1/kyc/session/location

Headers: Authorization: Bearer token-session-kyc

Request: {"latitude": Double, "longitude": Double}

2.3 Paso 3: Verificación de Documento

Validar autenticidad del documento oficial

@POST("api/v3/document/verify")
suspend fun verifyApi(
    @Header("Authorization") auth: String,
    @Body request: VerifyRequest
): Response<VerifyResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v3/document/verify

Headers: Authorization: Bearer token-session-kyc

Request:

{
    "imageFront": "String (Base64)",
    "imageBack": "String (Base64 - opcional)",
    "dataVerification": "Boolean (opcional)"
}

Response: Incluye evaluation (SUCCESS, WARNING, REJECTED) y state con propiedades como documentCompleteSides, documentLiveness, securityFeatures, imageQuality.

2.4 Paso 4: Extracción de Datos

Extraer información del documento

@POST("api/v4/document/extract")
suspend fun documentExtractApi(
    @Header("Authorization") auth: String,
    @Body request: DocumentExtractRequest
): Response<DocumentExtractResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v4/document/extract

Headers: Authorization: Bearer token-session-kyc

Request:

{
    "imageFront": "String (Base64)",
    "imageBack": "String (Base64 - opcional)",
    "documentSessionSelected": {
        "country": "String"
    }
}

Response: Contiene content.data con información personal, address y document.

2.5 Paso 5: Verificación en Listas Oficiales

Comparar datos contra listas gubernamentales

@POST("api/v2/blacklist/investigate")
suspend fun investigateApi(
    @Header("Authorization") auth: String,
    @Body request: InvestigateRequest
): Response<InvestigateResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v2/blacklist/investigate

Headers: Authorization: Bearer token-session-kyc

Request: Incluye services para activar listas a consultar y payload con datos de la persona.

2.6 Paso 6: Verificación de Vida (Liveness)

Asegurar que es una persona real

@POST("api/v1/liveness/verify-and-bestframe")
suspend fun livenessVerifyApi(
    @Header("Authorization") auth: String,
    @Body request: LivenessVerifyRequest
): Response<LivenessVerifyResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v1/liveness/verify-and-bestframe

Headers: Authorization: Bearer token-session-kyc

Request: {"video": "String (Base64)"}

Response: Incluye score, bestFrame y state.isRealPerson.

2.7 Paso 7: Verificación de Titularidad

Comparar rostro del video con foto del documento

@POST("api/v2/oto/verify")
suspend fun otoVerifyApi(
    @Header("Authorization") auth: String,
    @Body request: OtoVerifyRequest
): Response<OtoVerifyResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v2/oto/verify

Headers: Authorization: Bearer token-session-kyc

Request:

{
    "image1": "String (bestFrame Base64)",
    "image2": "String (face from document Base64)"
}

Response: Incluye score, distance y state.isSamePerson.

2.8 Paso 8: Finalización de Sesión

Completar y asegurar la sesión KYC

@POST("api/v1/kyc/session/finish")
suspend fun finishApi(
    @Header("Authorization") auth: String
): Response<FinishResponse>

Endpoint: POST https://sandbox.api.jaak.ai/api/v1/kyc/session/finish

Headers: Authorization: Bearer token-session-kyc

Request: {}

Response: {} con HTTP 200 OK

3. SDKs Adicionales

SDKs Recomendados para Captura de Datos

• Face-Detector SDK Android: Reconocimiento facial en tiempo real
• Document-Detector SDK Android: Identificación y extracción de documentos
• Google ML Kit Face Detection: Detección de rostros
• CameraX: Funcionalidad de cámara
• Play Services Location: Geolocalización
• Light Compressor: Compresión de video

Dependencias Adicionales

// ML Kit
implementation 'com.google.mlkit:face-detection:16.1.5'

// CameraX
implementation 'androidx.camera:camera-core:1.3.0'
implementation 'androidx.camera:camera-camera2:1.3.0'
implementation 'androidx.camera:camera-lifecycle:1.3.0'
implementation 'androidx.camera:camera-view:1.3.0'

// Compresión de video
implementation 'id.zelory:compressor:3.0.1'

4. Solución de Problemas

Problemas Comunes y Soluciones

Documentos/Videos Rechazados

Causas:

• Mala iluminación o reflejos
• Imagen borrosa o desenfocada
• Documento incompleto en el marco
• Uso de accesorios que oculten el rostro

Soluciones:

• Asegurar buena iluminación uniforme
• Verificar nitidez antes de procesar
• Capturar documento completo
• Remover lentes oscuros o accesorios

Errores de Autenticación (HTTP 401/403)

Causas:

• Token de sesión expirado
• Formato incorrecto del header Authorization

Soluciones:

• Verificar validez del accessToken
• Usar formato correcto: Bearer token-session-kyc

Problemas de Geolocalización

Causas:

• Permisos no otorgados
• Servicios de ubicación desactivados
• Dependencia de Google Play Services faltante

Soluciones:

• Solicitar permisos de ubicación al usuario
• Verificar dependencias en build.gradle
• Validar configuración de servicios

Timeouts en APIs

Causas:

• Archivos muy grandes (videos/imágenes)
• Conexión de red lenta
• Configuración de timeout insuficiente

Soluciones:

• Comprimir videos e imágenes antes del envío
• Configurar timeouts adecuados (30-60 segundos)
• Implementar reintentos con backoff exponencial

5. Soporte

Cuándo Contactar Soporte

• Errores técnicos persistentes en la integración
• Problemas con configuración del entorno Android
• Errores no documentados en respuestas API
• Necesidad de optimización de rendimiento

Información a Preparar

• Descripción específica del problema
• ShortKey o Session ID afectado
• Versión de Android Studio y SDK
• Versiones de librerías utilizadas
• Fragmentos de código relevantes (Kotlin)
• Logs completos de Logcat
• Hora aproximada del problema

6. Glosario