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. Flujo de Verificación KYC
4. Automatización y Webhook
5. Pruebas y Validación
6. Solución de Problemas
7. 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
• 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

1. URLs de API según Ambiente

Flujo de Verificación KYC

Paso 1: Validación de Licencia

Antes de utilizar cualquier endpoint de verificación, debes validar tu licencia y obtener un token de acceso.

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 (Paso 5 al Paso 10) para mantener la trazabilidad distribuida de las peticiones

{
  "country": "MEX"
}

Response

{}

SERVICIOS DE VERIFICACIÓN

Paso 2: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

Request Body

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

Response

{}

Status Code: 200 OK indica éxito.

Paso 3: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

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 4: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

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 Verificación INE

Nivel Superior

eventId y requestId

Identificador único de la transacción. Sirve para rastrear y auditar cada solicitud de verificación.

status

Estado de la operación. Indica que el documento se procesó correctamente.

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. Es una imagen JPEG que puedes decodificar y mostrar.

placeOfBirth

Lugar de nacimiento (no disponible en INE, por eso aparece vacío)

nationality

Nacionalidad del titular

maritalStatus

Estado civil (no disponible en INE, por eso aparece vacío)

extra.ocr

Número OCR de la credencial (código de barras en la parte posterior)

extra.registerYear

Año y mes de registro electoral

extra.rfc

RFC (Registro Federal de Contribuyentes) calculado automáticamente a partir de los datos personales

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

fullAddress

Dirección completa concatenada en un solo string

postalCode

Código postal del domicilio

extra.street

Nombre de la calle (C = Calle, AV = Avenida, etc.)

extra.externalNumber

Número exterior del domicilio

extra.internalNumber

Número interior o departamento (vacío si no aplica)

extra.neighborhood

Colonia o fraccionamiento

extra.apartmentUnit

Unidad habitacional o condominio (vacío si no aplica)

extra.city

Municipio o delegación

extra.state

Abreviatura del estado (MEX = Estado de México, CDMX = Ciudad de México, etc.)

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

type

Tipo de documento identificado por el sistema (credencial de elector en este caso)

side

Indica qué lados del documento se procesaron (BOTH = ambos lados, FRONT = solo frente, BACK = solo reverso)

country.name

Nombre completo del país emisor del documento

country.isoAlpha3Code

Código ISO de 3 letras del país

country.isoAlpha2Code

Código ISO de 2 letras del país

country.icaoCode

Código ICAO usado en documentos de viaje internacionales

number

Número de identificación del elector (CIC - Clave de Identificación Ciudadana)

personalIdNumber

CURP (Clave Única de Registro de Población) - identificador único nacional

additionalNumber

Clave de elector - código alfanumérico adicional de la credencial

dateOfIssue

Fecha en que se emitió la credencial

expiration.date

Fecha de vencimiento del documento

expiration.isPermanent

Indica si la credencial tiene vigencia indefinida o vence en una fecha específica

issuingAuthority

Autoridad gubernamental que emitió el documento (INE = Instituto Nacional Electoral)

extra

Objeto para datos adicionales específicos del tipo de documento (vacío en este caso)

Sección: processingTime

Tiempo que tardó el sistema en procesar el documento, medido en milisegundos

Sección: state (Estado de Validaciones)

message

Mensaje descriptivo del resultado del procesamiento

documentCompleteSides

Confirma si se pudieron procesar todos los lados requeridos del documento

documentExpired

Indica si el documento está vigente o ya venció

ageValid

Valida si la persona cumple con el requisito de edad mínima (configurable, típicamente 18 años)

ageValidMessage

Mensaje adicional sobre la validación de edad (vacío si la validación es exitosa)

Paso 5: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

⚠️

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 6: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

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 7: 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-DE-VALIDACION-LICENCIA]

📍 Importante: El header traceparent debe ser el mismo que recibiste en la respuesta del Paso 1 (Validación de Licencia).

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 7: 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 Básico (Orden obligatorio):

1. ✅ Validar Licencia → Obtener accessToken y traceparent
2. ✅ Registrar Geolocalización → Ubicación del usuario (enviar traceparent)
3. ✅ Verificar Documento → Validar autenticidad (enviar traceparent)
4. ✅ Extraer Datos (OCR) → Obtener información (enviar traceparent)
5. ✅ Verificar Listas → Validar contra bases oficiales (enviar traceparent)
6. ✅ Verificación de Vida → Confirmar presencia real (enviar traceparent)
7. ✅ Comparación Facial → Verificar titularidad (enviar traceparent)
8. ✅ 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:

• Validar licencia y obtener traceparent
• 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 (5-10)

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: 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 del Paso 1) en todos los endpoints del Paso 5 al Paso 10

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:

• ShortKey de la sesión
• Logs completos de las llamadas API
• Headers enviados (especialmente traceparent)
• 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
• Scripts automáticos para capturar tokens
• Ejemplos de todas las llamadas
• Headers traceparent configurados automáticamente

Variables necesarias en Postman:

• baseURL: URL del ambiente (Sandbox o Producción)
• apiKey: Tu API Key de JAAK
• traceparent: Se captura automáticamente del Paso 1

🎯 Resumen de Cambios Importantes

Header traceparent

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

1. Se obtiene en la respuesta del Paso 1 (Validación de Licencia)
2. Debe enviarse en TODOS los endpoints del Paso 5 al Paso 10:
   • Paso 5: Geolocalización
   • Paso 6: Verificar Documento
   • Paso 7: Extraer Datos (OCR)
   • Paso 8: Verificar Listas
   • Paso 9: Verificación de Vida
   • Paso 10: Comparación Facial

Formato del traceparent:

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

Ejemplo:

00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

📞 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: 1.0
Última actualización: Diciembre 2024
Autor: Equipo de Documentación JAAK