JAAK KYC Mosaic Web

Authorization: Bearer YOUR_API_KEY

POST /api/v1/kyc/flow HTTP/1.1
Host: sandbox.kyc.jaak.ai
Content-Type: application/json
Authorization: Bearer sk_test_abc123xyz456def789...

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "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": ""
  }
}

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

curl -X POST https://sandbox.kyc.jaak.ai/api/v1/kyc/flow \
  -H "Authorization: Bearer sk_test_abc123xyz456..." \
  -H "Content-Type: application/json" \
  -d '{
    "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": ""
    }
  }'

async function createKYCSession(clientData) {
  try {
    const response = await fetch('https://sandbox.kyc.jaak.ai/api/v1/kyc/flow', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.JAAK_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: clientData.name,
        flow: clientData.flow,
        redirectUrl: clientData.redirectUrl,
        countryDocument: 'MEX',
        flowType: 'KYC',
        verificationType: 'email',
        verification: {
          SMS: '',
          EMAIL: clientData.email,
          WHATSAPP: ''
        }
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error creating KYC session:', error);
    throw error;
  }
}

// Uso
const sessionData = await createKYCSession({
  name: 'María González Pérez',
  flow: 'Cliente-001-Onboarding',
  email: '[email protected]',
  redirectUrl: 'https://tu-empresa.com/kyc-completado'
});

console.log('Session URL:', sessionData.sessionUrl);

function extractShortKey(sessionUrl) {
  // sessionUrl: "https://sandbox.kyc.jaak.ai/session/ABC123X"
  const parts = sessionUrl.split('/');
  return parts[parts.length - 1]; // "ABC123X"
}

// Uso
const sessionUrl = "https://sandbox.kyc.jaak.ai/session/ABC123X";
const shortKey = extractShortKey(sessionUrl);
console.log(shortKey); // "ABC123X"

const config = {
  steps: [
    { key: 'DOCUMENT_EXTRACT' },
    { key: 'DOCUMENT_VERIFY' },
    { key: 'IVERIFICATION' }
  ],
  shortKey: 'ABC123X'  // El shortKey obtenido en el paso 2
};

// ====================================
// BACKEND: Crear sesión y obtener shortKey
// ====================================
async function initializeKYCSession(userData) {
  // Paso 1: Crear sesión en el backend
  const session = await fetch('https://sandbox.kyc.jaak.ai/api/v1/kyc/flow', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.JAAK_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: userData.name,
      flow: `user-${userData.id}-${Date.now()}`,
      redirectUrl: 'https://tu-empresa.com/kyc-success',
      countryDocument: 'MEX',
      flowType: 'KYC',
      verificationType: 'email',
      verification: {
        SMS: '',
        EMAIL: userData.email,
        WHATSAPP: ''
      }
    })
  });

  const data = await session.json();
  
  // Paso 2: Extraer shortKey de la URL
  const shortKey = extractShortKey(data.sessionUrl);
  
  return { shortKey, sessionUrl: data.sessionUrl };
}

function extractShortKey(sessionUrl) {
  const parts = sessionUrl.split('/');
  return parts[parts.length - 1];
}

// ====================================
// FRONTEND: Usar shortKey en tu integración
// ====================================
async function startKYCVerification(userId, userName, userEmail) {
  try {
    // Llamar a tu backend para crear sesión
    const response = await fetch('/api/kyc/create-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId: userId,
        name: userName,
        email: userEmail
      })
    });
    
    const { shortKey } = await response.json();
    
    // Opción A: Usar con Embed (iframe)
    const embedConfig = {
      steps: [
        { key: 'DOCUMENT_EXTRACT' },
        { key: 'DOCUMENT_VERIFY' },
        { key: 'IVERIFICATION' }
      ],
      shortKey: shortKey
    };
    
    document.getElementById('kycMosaic').contentWindow.postMessage({
      type: 'CONFIG',
      data: embedConfig
    }, '*');
    
    // Opción B: Generar Link para campaña
    const kycLink = `https://mosaic.sandbox.jaak.ai/link?shortKey=${shortKey}&steps=DOCUMENT_EXTRACT,DOCUMENT_VERIFY,IVERIFICATION`;
    console.log('Link de verificación:', kycLink);
    
    // Opción C: Abrir en Direct mode
    const directUrl = `https://mosaic.sandbox.jaak.ai/direct`;
    const directWindow = window.open(directUrl, 'kyc', 'width=800,height=600');
    
    // Esperar señal READY y enviar config
    window.addEventListener('message', function(event) {
      if (event.data.type === 'READY' && directWindow) {
        directWindow.postMessage({
          type: 'CONFIG',
          data: embedConfig
        }, '*');
      }
    });
    
  } catch (error) {
    console.error('Error al iniciar KYC:', error);
    alert('No se pudo iniciar la verificación. Intente nuevamente.');
  }
}

const config = {
  steps: [
    { key: 'WELCOME' },
    { key: 'DOCUMENT_EXTRACT' },
    { key: 'DOCUMENT_VERIFY' },
    { key: 'IVERIFICATION' },
    { key: 'OTO' },
    { key: 'FINISH' }
  ],
  shortKey: 'ABC123X'
};

<iframe 
  id="kycMosaic" 
  src="https://mosaic.sandbox.jaak.ai/"
  width="100%" 
  height="600"
  allow="camera; geolocation">
</iframe>

const config = {
  steps: [
    { key: 'DOCUMENT_EXTRACT' },
    { key: 'DOCUMENT_VERIFY' },
    { key: 'IVERIFICATION' }
  ],
  shortKey: 'ABC123X'  // shortKey obtenido de la API
};

document.getElementById('kycMosaic')
  .contentWindow.postMessage({
    type: 'CONFIG',
    data: config
  }, '*');

window.addEventListener('message', function(event) {
  switch(event.data.type) {
    case 'FLOW_COMPLETE':
      console.log('KYC completado', event.data);
      // Procesar resultados
      break;
      
    case 'ERROR':
      console.error('Error', event.data);
      // Manejar error
      break;
  }
});

let directWindow = null;

function openDirectKYC() {
  const url = 'https://mosaic.sandbox.jaak.ai/direct';
  const features = 'width=800,height=600';
  
  directWindow = window.open(url, 'kyc', features);
}

window.addEventListener('message', function(event) {
  if (event.data.type === 'READY') {
    const config = {
      steps: [
        { key: 'DOCUMENT_EXTRACT' },
        { key: 'IVERIFICATION' }
      ],
      shortKey: 'ABC123X'  // shortKey obtenido de la API
    };
    
    directWindow.postMessage({
      type: 'CONFIG',
      data: config
    }, '*');
  }
});

window.addEventListener('message', function(event) {
  switch(event.data.type) {
    case 'FLOW_COMPLETE':
      console.log('KYC completado en Direct', event.data);
      break;
      
    case 'ERROR':
      console.error('Error en Direct', event.data);
      break;
  }
});

function generateKYCLink(shortKey, steps, redirectUrl) {
  const baseUrl = 'https://mosaic.sandbox.jaak.ai/link';
  const params = new URLSearchParams({
    shortKey: shortKey,
    steps: steps.join(',')
  });
  
  if (redirectUrl) {
    params.append('redirectUrl', redirectUrl);
  }
  
  return `${baseUrl}?${params.toString()}`;
}

// Uso
const link = generateKYCLink(
  'ABC123X',
  ['DOCUMENT_EXTRACT', 'IVERIFICATION', 'OTO'],
  'https://mi-app.com/success'
);

console.log(link);

window.addEventListener('message', function(event) {
  const message = event.data;
  
  switch(message.type) {
    case 'READY':
      console.log('Mosaic listo');
      // Enviar configuración
      break;
      
    case 'STEP_COMPLETE':
      console.log('Paso completado:', message.data.stepKey);
      console.log('Datos del paso:', message.data.data);
      // Guardar datos del paso si es necesario
      break;
      
    case 'FLOW_COMPLETE':
      console.log('KYC completado exitosamente');
      console.log('Datos finales:', message.data);
      // Procesar resultados finales
      break;
      
    case 'ERROR':
      console.error('Error en KYC:', message.data.error);
      console.error('Mensaje:', message.data.message);
      // Mostrar mensaje de error al usuario
      break;
      
    case 'SESSION_EXPIRED':
      console.warn('Sesión expirada');
      // Reiniciar flujo o mostrar mensaje
      break;
  }
});

{
  type: 'STEP_COMPLETE',
  data: {
    stepKey: 'DOCUMENT_EXTRACT',
    data: {
      face: 'data:image/jpeg;base64,...'
      // Datos específicos del paso
    }
  }
}

{
  type: 'FLOW_COMPLETE',
  data: {
    completedSteps: ['DOCUMENT_EXTRACT', 'IVERIFICATION', 'OTO'],
    allData: {
      DOCUMENT_EXTRACT: { /* datos */ },
      IVERIFICATION: { /* datos */ },
      OTO: { /* datos */ }
    }
  }
}

{
  type: 'ERROR',
  data: {
    error: 'AUTHENTICATION_FAILED',
    message: 'Invalid shortKey provided'
  }
}

<!-- Configuración correcta del iframe -->
<iframe 
  id="kycMosaic" 
  src="https://mosaic.sandbox.jaak.ai/"
  allow="camera; geolocation"
  width="100%" 
  height="600">
</iframe>

// Verificar que la API Key esté correctamente configurada
const API_KEY = process.env.JAAK_API_KEY;
if (!API_KEY || API_KEY.trim() === '') {
  console.error('API Key no configurada');
}

const config = {
  steps: [
    { 
      key: 'OTO',
      data: {
        face: 'data:image/jpeg;base64,...',        // Imagen del documento
        bestFrame: 'data:image/jpeg;base64,...'   // Imagen de liveness
      }
    }
  ],
  shortKey: 'ABC123X'
};

// Buena práctica: abrir desde un evento de click
button.addEventListener('click', function() {
  openDirectKYC();
});

window.addEventListener('message', function(event) {
  // Validar origen en producción
  // if (event.origin !== 'https://mosaic.jaak.ai') return;
  
  console.log('Mensaje recibido:', event.data);
});

window.addEventListener('message', function(event) {
  if (event.data.type === 'SESSION_EXPIRED') {
    console.warn('Sesión expirada');
    
    // Opción 1: Reiniciar automáticamente
    setTimeout(() => {
      sendConfiguration();
    }, 2000);
    
    // Opción 2: Mostrar mensaje y esperar acción del usuario
    // showModal('Su sesión ha expirado. ¿Desea reiniciar?');
  }
});

// ❌ MAL - API Key expuesta en frontend
const apiKey = 'sk_live_abc123xyz456...';

// ✅ BIEN - API Key en backend con variable de entorno
const apiKey = process.env.JAAK_API_KEY;

window.addEventListener('message', function(event) {
  // Validar origen en producción
  if (event.origin !== 'https://mosaic.jaak.ai') {
    console.warn('Mensaje de origen no confiable');
    return;
  }
  // Procesar mensaje
});

function handleKYCError(error) {
  const friendlyMessages = {
    'AUTHENTICATION_FAILED': 'No pudimos verificar su sesión. Por favor intente nuevamente.',
    'CAMERA_ACCESS_DENIED': 'Necesitamos acceso a su cámara para continuar.',
    'DOCUMENT_NOT_DETECTED': 'No pudimos detectar el documento. Por favor intente de nuevo.',
    'SESSION_EXPIRED': 'Su sesión ha expirado. Por favor reinicie el proceso.'
  };
  
  const message = friendlyMessages[error.error] || 'Ocurrió un error. Por favor intente nuevamente.';
  showUserMessage(message);
}

window.addEventListener('message', function(event) {
  if (event.data.type === 'STEP_COMPLETE') {
    updateProgressBar(event.data.stepKey);
  }
});

<!-- Precargar en el head -->
<link rel="preconnect" href="https://mosaic.sandbox.jaak.ai">

let iframeLoaded = false;

setTimeout(() => {
  if (!iframeLoaded) {
    showError('El servicio está tardando más de lo usual. Por favor recargue la página.');
  }
}, 10000); // 10 segundos

// Configuración de producción recomendada
const PRODUCTION_CONFIG = {
  mosaicUrl: 'https://mosaic.jaak.ai/',
  apiUrl: 'https://kyc.jaak.ai/api/v1',
  apiKey: process.env.JAAK_API_KEY_PROD,
  allowedOrigins: ['https://mosaic.jaak.ai'],
  timeout: 900000, // 15 minutos
  retryAttempts: 3
};

// Uso seguro en producción
function initKYC() {
  if (!PRODUCTION_CONFIG.apiKey) {
    console.error('API Key no configurada');
    return;
  }
  
  // Continuar con inicialización...
}

<!DOCTYPE html>
<html>
<head>
  <title>Onboarding - Mi App</title>
  <style>
    #kycContainer {
      max-width: 800px;
      margin: 0 auto;
      padding: 20px;
    }
  </style>
</head>
<body>
  <div id="kycContainer">
    <h1>Verificación de Identidad</h1>
    <p>Complete el proceso de verificación para activar su cuenta</p>
    
    <iframe 
      id="kycMosaic" 
      src="https://mosaic.sandbox.jaak.ai/"
      width="100%" 
      height="600"
      allow="camera; geolocation">
    </iframe>
  </div>

  <script>
    // Obtener shortKey desde el backend
    async function getShortKey() {
      const response = await fetch('/api/kyc/create-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          userId: 'user123',
          name: 'Juan Pérez',
          email: '[email protected]'
        })
      });
      const data = await response.json();
      return data.shortKey;
    }

    // Configurar KYC
    async function initializeKYC() {
      const shortKey = await getShortKey();
      
      const config = {
        steps: [
          { key: 'WELCOME' },
          { key: 'DOCUMENT_EXTRACT' },
          { key: 'DOCUMENT_VERIFY' },
          { key: 'IVERIFICATION' },
          { key: 'OTO' }
        ],
        shortKey: shortKey
      };

      setTimeout(() => {
        document.getElementById('kycMosaic')
          .contentWindow.postMessage({
            type: 'CONFIG',
            data: config
          }, '*');
      }, 1000);
    }

    // Manejar eventos
    window.addEventListener('message', function(event) {
      if (event.data.type === 'FLOW_COMPLETE') {
        window.location.href = '/dashboard?verified=true';
      }
    });

    // Iniciar cuando cargue la página
    window.addEventListener('load', initializeKYC);
  </script>
</body>
</html>

class KYCVerification {
  constructor(apiEndpoint) {
    this.apiEndpoint = apiEndpoint;
    this.directWindow = null;
    this.setupMessageListener();
  }

  setupMessageListener() {
    window.addEventListener('message', (event) => {
      this.handleMessage(event.data);
    });
  }

  async open(userId, userName, userEmail) {
    try {
      // Obtener shortKey del backend
      const shortKey = await this.getShortKey(userId, userName, userEmail);
      
      const url = 'https://mosaic.sandbox.jaak.ai/direct';
      const features = 'width=800,height=600,scrollbars=yes,resizable=yes';
      
      this.directWindow = window.open(url, 'kycVerification', features);
      
      if (!this.directWindow) {
        alert('Por favor permita ventanas emergentes para continuar');
        return false;
      }
      
      this.shortKey = shortKey;
      return true;
    } catch (error) {
      console.error('Error al abrir KYC:', error);
      return false;
    }
  }

  async getShortKey(userId, userName, userEmail) {
    const response = await fetch(`${this.apiEndpoint}/create-session`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId: userId,
        name: userName,
        email: userEmail
      })
    });
    
    const data = await response.json();
    return data.shortKey;
  }

  handleMessage(message) {
    switch(message.type) {
      case 'READY':
        this.sendConfiguration();
        break;
        
      case 'FLOW_COMPLETE':
        this.onComplete(message.data);
        break;
        
      case 'ERROR':
        this.onError(message.data);
        break;
    }
  }

  sendConfiguration() {
    if (this.directWindow && !this.directWindow.closed) {
      this.directWindow.postMessage({
        type: 'CONFIG',
        data: {
          steps: [
            { key: 'DOCUMENT_EXTRACT' },
            { key: 'IVERIFICATION' },
            { key: 'OTO' }
          ],
          shortKey: this.shortKey
        }
      }, '*');
    }
  }

  onComplete(data) {
    console.log('Verificación completada', data);
    this.saveResults(data);
  }

  onError(error) {
    console.error('Error en verificación', error);
    alert('Hubo un error en la verificación. Por favor intente nuevamente.');
  }

  async saveResults(data) {
    try {
      const response = await fetch(`${this.apiEndpoint}/save-results`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data)
      });
      
      if (response.ok) {
        window.location.href = '/verification-success';
      }
    } catch (error) {
      console.error('Error guardando resultados', error);
    }
  }
}

// Uso
const kycBtn = document.getElementById('startKYC');
kycBtn.addEventListener('click', async function() {
  const kyc = new KYCVerification('/api/kyc');
  await kyc.open('user456', 'María González', '[email protected]');
});

// Script backend para generar enlaces de campaña
async function generateCampaignLinks(campaign, recipients) {
  const baseUrl = 'https://mosaic.sandbox.jaak.ai/link';
  
  const links = await Promise.all(
    recipients.map(async (recipient) => {
      // Crear sesión para cada destinatario
      const session = await fetch('https://sandbox.kyc.jaak.ai/api/v1/kyc/flow', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.JAAK_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: recipient.name,
          flow: `${campaign.id}-${recipient.id}`,
          redirectUrl: `https://mi-app.com/campaign-complete?user=${recipient.id}&campaign=${campaign.id}`,
          countryDocument: 'MEX',
          flowType: 'KYC',
          verificationType: 'email',
          verification: {
            SMS: '',
            EMAIL: recipient.email,
            WHATSAPP: ''
          }
        })
      });
      
      const data = await session.json();
      const shortKey = extractShortKey(data.sessionUrl);
      
      const params = new URLSearchParams({
        shortKey: shortKey,
        steps: 'DOCUMENT_EXTRACT,DOCUMENT_VERIFY,IVERIFICATION',
        redirectUrl: `https://mi-app.com/campaign-complete?user=${recipient.id}&campaign=${campaign.id}`
      });
      
      return {
        recipient: recipient.email,
        name: recipient.name,
        link: `${baseUrl}?${params.toString()}`
      };
    })
  );
  
  return links;
}

function extractShortKey(sessionUrl) {
  const parts = sessionUrl.split('/');
  return parts[parts.length - 1];
}

// Generar enlaces para campaña
const campaign = {
  id: 'onboarding-q1-2025',
  name: 'Onboarding Q1 2025'
};

const recipients = [
  { id: 'user123', name: 'Juan Pérez', email: '[email protected]' },
  { id: 'user456', name: 'María González', email: '[email protected]' }
];

const campaignLinks = await generateCampaignLinks(campaign, recipients);

// Enviar emails
campaignLinks.forEach(item => {
  sendEmail({
    to: item.recipient,
    subject: 'Complete su verificación de identidad',
    html: `
      <h2>Hola ${item.name},</h2>
      <p>Para completar su registro, por favor complete el proceso de verificación
      haciendo clic en el siguiente botón:</p>
      <a href="${item.link}" style="background: #0066cc; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">
        Verificar mi identidad
      </a>
      <p>Este enlace es válido por 30 días.</p>
      <p>Saludos,<br>Equipo de Mi App</p>
    `
  });
});

console.log('Enlaces de campaña generados:', campaignLinks);