Manual de Integración API de KYC - JAAK

⏱️ Tiempo estimado: 2-3 horas para integración completa

📋 Índice de Contenidos

1. Antes de Empezar
2. Configuración Inicial
3. Métodos de Inicio de Sesión
4. Flujo de Verificación KYC
5. Automatización y Webhook
6. Pruebas y Validación
7. Solución de Problemas
8. Recursos Adicionales

Antes de Empezar

🎯 ¿Qué lograrás con esta guía?

Al finalizar esta integración habrás implementado un sistema completo de verificación de identidad KYC mediante API, con control total sobre la experiencia de usuario y flujo personalizado.

📚 Requisitos Técnicos

Conocimientos Necesarios:

• API REST básico (GET, POST, Headers)
• Formato JSON
• Manejo de tokens de autenticación
• Codificación Base64 para imágenes

Herramientas Requeridas:

• Cliente HTTP (Postman, Insomnia, cURL)
• Acceso a la Plataforma JAAK
• API Key de JAAK
• Licencia (para Método A) o configuración de flujo (para Método B)
• Entorno de desarrollo configurado

Información de la Empresa:

• Países donde opera (configurados en JAAK)
• URL de webhook (opcional pero recomendado)
• URL de redirección para usuarios

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

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

Continúa al Flujo de Verificación KYC

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

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

Authorization: Bearer [ACCESS-TOKEN]

2. 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.

Continúa al Flujo de Verificación KYC

Flujo de Verificación KYC

Una vez que tengas tu access_token (obtenido mediante Método A o Método B), sigue esta secuencia de servicios.

⚠️ NOTA SOBRE TRACEPARENT:

• Método A: El traceparent se obtiene del endpoint /api/v1/license/validate
• Método B: El traceparent se obtiene del endpoint /api/v1/kyc/session
• En AMBOS casos: El header traceparent debe incluirse en TODOS los siguientes endpoints de verificación

Paso 3: Registrar Geolocalización

Registra la ubicación desde donde se realiza la verificación.

Endpoint

POST /api/v1/kyc/session/location

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

Request Body

{
  "latitude": 19.432608,
  "longitude": -99.133209
}

Response

{}

Status Code: 200 OK indica éxito.

Paso 4: Verificar Documento

Valida la autenticidad del documento de identidad.

Endpoint

POST /api/v3/document/verify

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

Request Body

{
  "imageFront": "[BASE64-IMAGE-FRONT]",
  "imageBack": "[BASE64-IMAGE-BACK]",
  "dataVerification": true
}

Parámetros

Response de Ejemplo

{
  "eventId": "evento-123",
  "requestId": "request-456",
  "evaluation": "APPROVED",
  "document": {
    "type": "INE",
    "side": "BOTH",
    "country": "México",
    "icaoCode": "MEX"
  },
  "state": {
    "documentCompleteSides": true,
    "dataConsistent": true,
    "documentLiveness": true,
    "securityFeatures": true,
    "documentValidity": true,
    "imageQuality": true,
    "handPresence": false,
    "photoForgery": false,
    "message": "Document verification successful",
    "validations": {
      "namesMatch": true,
      "lastNameMatch": true,
      "birthDateMatch": true,
      "personalIdNumberMatch": true,
      "message": "All validations passed"
    }
  },
  "processTime": 1250
}

Estados de Validación

Paso 5: Extraer Datos (OCR)

Extrae información del documento para validaciones posteriores.

Endpoint

POST /api/v4/document/extract

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

Request Body

{
  "imageFront": "[BASE64-IMAGE-FRONT]",
  "imageBack": "[BASE64-IMAGE-BACK]"
}

💡 Tip: Usa las mismas imágenes del paso anterior.

Response de Ejemplo

{
  "eventId": "extract-123",
  "requestId": "extract-456",
  "status": "SUCCESS",
  "processingTime": 1500,
  "state": {
    "message": "Extraction completed successfully",
    "documentCompleteSides": true
  },
  "content": {
    "data": {
      "personal": {
        "firstName": "María",
        "secondName": "",
        "surname": "González",
        "motherSurname": "Pérez",
        "fullName": "María González Pérez",
        "sex": "M",
        "dateOfBirth": "15/03/1990",
        "face": "[BASE64-FACE-IMAGE]",
        "placeOfBirth": "Ciudad de México",
        "nationality": "MEXICANA",
        "maritalStatus": "",
        "extra": {
          "ocr": "1234567890123",
          "registerYear": "2018",
          "rfc": "GOPM900315XXX"
        }
      },
      "address": {
        "fullAddress": "Av. Reforma 123, Col. Centro, 06000 Ciudad de México",
        "postalCode": "06000",
        "extra": {
          "street": "Av. Reforma",
          "externalNumber": "123",
          "internalNumber": "",
          "neighborhood": "Centro",
          "city": "Ciudad de México",
          "state": "CDMX"
        }
      },
      "document": {
        "type": "INE",
        "side": "BOTH",
        "country": {
          "name": "México",
          "isoAlpha3Code": "MEX",
          "isoAlpha2Code": "MX",
          "icaoCode": "MEX"
        },
        "number": "1234567890123",
        "personalIdNumber": "GOPM900315MDFNRR02",
        "additionalNumber": "0123",
        "dateOfIssue": "01/01/2018",
        "expiration": {
          "date": "01/01/2028",
          "isPermanent": false
        },
        "issuingAuthority": "INE",
        "extra": {}
      }
    }
  }
}

Datos Importantes para Siguientes Pasos

Para validaciones en listas:

• content.data.personal.firstName → Nombres
• content.data.personal.surname → Apellidos
• content.data.document.personalIdNumber → CURP
• content.data.personal.extra.rfc → RFC
• content.data.personal.extra.ocr → OCR
• content.data.document.number → CIC

Para comparación facial:

• content.data.personal.face → Imagen del rostro del documento

Explicación Detallada del JSON de Extracción

Nivel Superior

• eventId y requestId: Identificadores únicos de la transacción
• status: Estado de la operación

Sección: content.data.personal (Datos Personales)

• firstName: Primer nombre del titular
• secondName: Segundo nombre del titular
• surname: Apellido paterno
• motherSurname: Apellido materno
• fullName: Nombre completo concatenado
• sex: Sexo (M=Masculino, F=Femenino)
• dateOfBirth: Fecha de nacimiento en formato DD/MM/AAAA
• face: Fotografía del rostro extraída de la credencial, codificada en Base64
• placeOfBirth: Lugar de nacimiento
• nationality: Nacionalidad del titular
• maritalStatus: Estado civil
• extra.ocr: Número OCR de la credencial
• extra.registerYear: Año y mes de registro electoral
• extra.rfc: RFC calculado automáticamente

Sección: content.data.address (Dirección)

• fullAddress: Dirección completa concatenada
• postalCode: Código postal del domicilio
• extra.street: Nombre de la calle
• extra.externalNumber: Número exterior
• extra.internalNumber: Número interior o departamento
• extra.neighborhood: Colonia o fraccionamiento
• extra.city: Municipio o delegación
• extra.state: Abreviatura del estado

Sección: content.data.document (Información del Documento)

• type: Tipo de documento identificado
• side: Lados del documento procesados
• country: Información del país emisor
• number: Número de identificación del elector (CIC)
• personalIdNumber: CURP
• additionalNumber: Clave de elector
• dateOfIssue: Fecha de emisión
• expiration: Información de vencimiento
• issuingAuthority: Autoridad que emitió el documento

Paso 6: Verificar en Listas Oficiales

Valida datos contra listas oficiales (RENAPO, OFAC, Interpol, INE, SAT).

Endpoint

POST /api/v2/blacklist/investigate

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

⚠️

IMPORTANTE: Solo puedes consultar una lista por llamada.

Ejemplo: Verificación RENAPO (CURP)

{
  "services": {
    "ine": false,
    "interpol": false,
    "ofac": false,
    "renapo": {
      "curp": true
    },
    "sat": {
      "sat69b": false
    },
    "cdc": {
      "rccFico": false
    }
  },
  "payload": {
    "identifications": {
      "curp": "GOPM900315MDFNRR02"
    }
  }
}

Ejemplo: Verificación OFAC

{
  "services": {
    "ine": false,
    "interpol": false,
    "ofac": true,
    "renapo": {
      "curp": false
    },
    "sat": {
      "sat69b": false
    },
    "cdc": {
      "rccFico": false
    }
  },
  "payload": {
    "person": {
      "name": "María",
      "secondName": "",
      "lastName": "González",
      "secondLastName": "Pérez"
    }
  }
}

Configuraciones por Servicio

RENAPO (Validación positiva)

{
  "services": { "renapo": { "curp": true } },
  "payload": {
    "identifications": {
      "curp": "CURP_EXTRAIDA"
    }
  }
}

OFAC (Validación negativa)

{
  "services": { "ofac": true },
  "payload": {
    "person": {
      "name": "NOMBRE_EXTRAIDO",
      "lastName": "APELLIDO_EXTRAIDO"
    }
  }
}

INE (Validación positiva)

{
  "services": { "ine": true },
  "payload": {
    "identifications": {
      "ine": {
        "cic": "CIC_EXTRAIDO",
        "ocr": "OCR_EXTRAIDO"
      }
    }
  }
}

Response de Ejemplo

{
  "eventId": "blacklist-123",
  "responseId": "response-456",
  "processTime": 0.5,
  "organization": "renapo",
  "service": "validaCurp",
  "result": {
    "curp": "GOPM900315MDFNRR02",
    "nombres": "MARIA",
    "apellidos": "GONZALEZ PEREZ"
  },
  "state": {
    "foundInService": true,
    "mustBeFound": true,
    "message": "Person found in RENAPO database"
  }
}

Interpretación de Resultados

Paso 7: Verificación de Vida (Liveness)

Valida que el usuario es una persona real presente en el momento.

Endpoint

POST /api/v3/liveness/verify

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

Request Body

{
  "video": "[BASE64-VIDEO]",
  "returnBestFrame": true
}

Response de Ejemplo

{
  "eventId": "liveness-123",
  "requestId": "liveness-456",
  "evaluation": "APPROVED",
  "score": 0.95,
  "bestFrame": "[BASE64-BEST-FRAME]",
  "state": {
    "liveness": true,
    "facesDetected": 1,
    "isRealPerson": true,
    "message": "Liveness verification successful"
  },
  "processTime": 2000
}

💡 Tip: Guarda bestFrame para el siguiente paso.

Paso 8: Comparación Facial (One-to-One)

Verifica que la persona del documento es la misma que realizó la prueba de vida.

Endpoint

POST /api/v2/oto/verify

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]
traceparent: [TRACEPARENT-OBTENIDO-EN-PASO-1]

📍 Importante: El header traceparent debe ser el mismo que recibiste en el Paso 1A (Validación de Licencia) o en el Paso 2B (Intercambio de ShortKey).

Request Body

{
  "eventId": "oto-comparison-001",
  "image1": "[BASE64-BEST-FRAME-FROM-LIVENESS]",
  "image2": "[BASE64-FACE-FROM-DOCUMENT]"
}

Response de Ejemplo

{
  "eventId": "oto-comparison-001",
  "requestId": "oto-456",
  "score": 0.89,
  "distance": 0.11,
  "process_time": 800,
  "metadata": {
    "image1": {
      "accessories": {
        "glass": false,
        "sunGlass": false,
        "hat": false,
        "mask": false
      },
      "image_quality": {
        "isCorrectBrightness": true,
        "isCorrectBlur": true,
        "isCorrectHeight": true,
        "isCorrectWidth": true,
        "isCorrectResolution": true,
        "isCorrectVerticalRotation": true,
        "isCorrectHorizontalRotation": true,
        "isCorrectRotation": true,
        "isCorrectSizeFace": true,
        "isCorrectNumberFaces": true
      }
    },
    "image2": {
      "accessories": {
        "glass": false,
        "sunGlass": false,
        "hat": false,
        "mask": false
      },
      "image_quality": {
        "isCorrectBrightness": true,
        "isCorrectBlur": true,
        "isCorrectHeight": true,
        "isCorrectWidth": true,
        "isCorrectResolution": true,
        "isCorrectVerticalRotation": true,
        "isCorrectHorizontalRotation": true,
        "isCorrectRotation": true,
        "isCorrectSizeFace": true,
        "isCorrectNumberFaces": true
      }
    }
  },
  "codes": null,
  "state": {
    "rejectedBadQuality": false,
    "rejectedAccessories": false,
    "isSamePerson": true,
    "message": "Face comparison successful"
  }
}

Criterios de Evaluación

Paso 9: Finalizar Sesión KYC

Cierra la sesión y consolida todos los resultados.

Endpoint

POST /api/v1/kyc/session/finish

Headers

Content-Type: application/json
Authorization: Bearer [ACCESS-TOKEN]

Request Body

{}

Response

{}

Status Code: 200 OK confirma finalización exitosa.

Automatización y Flujo Completo

Secuencia Recomendada de Llamadas

Flujo con Método A (Por Licencia):

1. ✅ Validar Licencia → Obtener accessToken y traceparent
2. ✅ Registrar País → Configurar país del documento
3. ✅ Registrar Geolocalización → Ubicación del usuario (enviar traceparent)
4. ✅ Verificar Documento → Validar autenticidad (enviar traceparent)
5. ✅ Extraer Datos (OCR) → Obtener información (enviar traceparent)
6. ✅ Verificar Listas → Validar contra bases oficiales (enviar traceparent)
7. ✅ Verificación de Vida → Confirmar presencia real (enviar traceparent)
8. ✅ Comparación Facial → Verificar titularidad (enviar traceparent)
9. ✅ Finalizar Sesión → Consolidar resultados

Flujo con Método B (Crear Sesión + ShortKey):

1. ✅ Crear Sesión KYC → Obtener shortKey
2. ✅ Intercambiar ShortKey → Obtener accessToken y traceparent
3. ✅ Registrar País → Configurar país del documento (enviar traceparent)
4. ✅ Registrar Geolocalización → Ubicación del usuario (enviar traceparent)
5. ✅ Verificar Documento → Validar autenticidad (enviar traceparent)
6. ✅ Extraer Datos (OCR) → Obtener información (enviar traceparent)
7. ✅ Verificar Listas → Validar contra bases oficiales (enviar traceparent)
8. ✅ Verificación de Vida → Confirmar presencia real (enviar traceparent)
9. ✅ Comparación Facial → Verificar titularidad (enviar traceparent)
10. ✅ Finalizar Sesión → Consolidar resultados

Manejo de Errores

Códigos de Error Comunes

Ejemplo de Error

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Access token has expired",
    "details": "Please obtain a new access token"
  }
}

Timeout y Reintentos

Configuración de Webhook

Recibir Resultados Automáticamente

Configuración

Configurar en Plataforma JAAK: Dashboard → Ajustes → Mi Compañía → KYC Webhook

Estructura del Webhook

{
  "sessionId": "uuid-session",
  "shortKey": "ABC123X",
  "status": "COMPLETED",
  "evaluation": "APPROVED",
  "timestamp": "2024-01-15T10:30:00Z",
  "results": {
    "document": {
      "verification": "APPROVED",
      "extraction": "SUCCESS"
    },
    "liveness": {
      "status": "APPROVED",
      "score": 0.95
    },
    "faceComparison": {
      "status": "APPROVED",
      "isSamePerson": true
    },
    "blacklists": {
      "renapo": "FOUND",
      "ofac": "NOT_FOUND"
    }
  },
  "extractedData": {
    "name": "María González Pérez",
    "curp": "GOPM900315MDFNRR02",
    "dateOfBirth": "15/03/1990"
  }
}

Pruebas y Validación

Lista de Verificación

Pruebas Obligatorias Método A:

• Validar licencia y obtener traceparent
• Registrar país del documento
• Registrar geolocalización
• Verificar documento con imágenes de buena calidad
• Extraer datos correctamente del documento
• Validar al menos en RENAPO y OFAC
• Realizar prueba de vida exitosa
• Comparar rostros con resultado positivo
• Finalizar sesión sin errores
• Recibir webhook (si configurado)
• Verificar que traceparent se envía en todos los pasos

Pruebas Obligatorias Método B:

• Crear sesión KYC exitosamente
• Obtener shortKey de la respuesta
• Intercambiar shortKey por accessToken y traceparent
• Verificar que traceparent se recibe en los headers de respuesta
• Registrar país del documento
• Registrar geolocalización (enviar traceparent)
• Verificar documento con imágenes de buena calidad (enviar traceparent)
• Extraer datos correctamente del documento (enviar traceparent)
• Validar al menos en RENAPO y OFAC (enviar traceparent)
• Realizar prueba de vida exitosa (enviar traceparent)
• Comparar rostros con resultado positivo (enviar traceparent)
• Finalizar sesión sin errores
• Recibir webhook (si configurado)

Casos de Prueba

Documento Válido (Caso Positivo)

• Documento mexicano vigente
• Imágenes nítidas, bien iluminadas
• Sin reflejos ni obstrucciones
• Resultado esperado: Todos los pasos APPROVED

Documento Inválido (Caso Negativo)

• Documento vencido o alterado
• Imágenes borrosas o mal iluminadas
• Resultado esperado: Fallas en verificación

Persona No Encontrada en RENAPO

• CURP inexistente o incorrecto
• Resultado esperado: foundInService: false

Solución de Problemas

Errores Frecuentes

Token Expirado

{
  "error": "Access token expired"
}

Solución Método A: Validar licencia nuevamente para obtener nuevo token Solución Método B: Intercambiar nuevamente el shortKey por un nuevo accessToken

Imagen Base64 Inválida

{
  "error": "Invalid image format"
}

Solución: Verificar que la imagen esté correctamente codificada en Base64

País No Configurado

{
  "error": "Country not supported for this company"
}

Solución: Configurar el país en la Plataforma JAAK

Traceparent Faltante

{
  "error": "Missing traceparent header"
}

Solución: Asegúrate de incluir el header traceparent obtenido en:

• Método A: Del Paso 1A (Validación de Licencia)
• Método B: Del Paso 2B (Intercambio de ShortKey)

El traceparent debe enviarse en todos los endpoints de verificación (Paso 2 al Paso 8).

ShortKey Inválido (Solo Método B)

{
  "error": "Invalid or expired shortKey"
}

Solución: Verificar que el shortKey sea correcto y que la sesión no haya expirado

Webhook No Se Recibe

Causas posibles:

• URL incorrecta en configuración
• Servidor no responde con 200 OK
• Firewall bloqueando conexiones

Recursos Adicionales

Documentación Complementaria

• Conceptos Básicos en JAAK - Terminología y arquitectura
• Lista de Países Soportados - Códigos Alpha-3 disponibles
• Códigos de Error Completos - Referencia de todos los errores posibles

SDKs Web Recomendados

Para simplificar la captura de imágenes en el frontend:

• @jaak.ai/face-detector - Captura optimizada de rostros
• @jaak.ai/stamps - Captura de documentos de identidad

Soporte Técnico

Información necesaria para soporte:

• Método utilizado (A o B)
• ShortKey o License utilizada
• Logs completos de las llamadas API
• Headers enviados (especialmente traceparent si aplica)
• Mensajes de error específicos

📦 Collection de Postman

Importa la colección completa de Postman para probar todos los endpoints. La colección incluye:

• Variables pre-configuradas para ambos métodos
• Scripts automáticos para capturar tokens
• Ejemplos de todas las llamadas
• Headers traceparent configurados automáticamente (Método A)
• Headers Short-Key configurados automáticamente (Método B)

Variables necesarias en Postman:

Para Método A:

• baseURL: URL del ambiente (Sandbox o Producción)
• license: Tu licencia de JAAK
• traceparent: Se captura automáticamente del Paso 1A
• accessToken: Se captura automáticamente del Paso 1A

Para Método B:

• baseURL: URL del ambiente (Sandbox o Producción)
• shortKey: Se captura automáticamente de la creación de sesión
• traceparent: Se captura automáticamente del Paso 2B (intercambio)
• accessToken: Se captura automáticamente del Paso 2B (intercambio)

🎯 Resumen de Cambios Importantes

Dos Métodos de Inicio

Método A - Por Licencia:

• Obtiene access_token y traceparent directamente de /api/v1/license/validate
• Uso de traceparent es obligatorio en todos los servicios de verificación
• Ideal para integraciones totalmente personalizadas

Método B - Crear Sesión:

• Crea sesión, obtiene shortKey, intercambia por access_token y traceparent en /api/v1/kyc/session
• Uso de traceparent es obligatorio en todos los servicios de verificación
• Incluye capacidades de notificación (email/SMS/WhatsApp)
• Ideal para integraciones híbridas con UI de JAAK

Header traceparent (Ambos Métodos)

El header traceparent es CRÍTICO para la trazabilidad distribuida:

Método A:

1. Se obtiene en la respuesta del Paso 1A (Validación de Licencia) - endpoint /api/v1/license/validate
2. Debe enviarse en TODOS los servicios de verificación (Paso 2 al Paso 8)

Método B:

1. Se obtiene en la respuesta del Paso 2B (Intercambio de ShortKey) - endpoint /api/v1/kyc/session
2. Debe enviarse en TODOS los servicios de verificación (Paso 2 al Paso 8)

Formato del traceparent:

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

Ejemplos:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
traceparent: 00-cf143715d7a2d4ffc3ef122f62384844-6f7048446dffdb89-00

Header adicional disponible:

x-trace-id: 32922b9bf22570da5e9895fa592c6852

📞 Contacto y Soporte

Para más información o soporte técnico, contacta al equipo de JAAK:

• Sitio Web: https://jaak.ai
• Email de Soporte: [email protected]
• Documentación Técnica: https://docs.jaak.ai

Versión del documento: 2.0
Última actualización: Diciembre 2024
Autor: Equipo de Documentación JAAK