USIV Widget SDK 🎯

SDK de verificación biométrica para cédulas chilenas con liveness detection. Widget embebible en cualquier página web.

📦 Instalación

npm install usiv-widget-sdk

🚀 Uso Rápido

import React from 'react';
import { UsivVerificationWidget, UsivSDKProvider } from 'usiv-widget-sdk';
import 'usiv-widget-sdk/dist/styles.css';

function App() {
  const verificationData = {
    verificationId: 'abc123',
    sessionToken: 'eyJhbGc...',
    rut: '17803819-2',      // opcional
    email: '[email protected]'  // opcional
  };

  const handleComplete = (result) => {
    console.log('Verificación completada:', result);
    // result.success: true/false
    // result.status: 'Validado' | 'No Validado'
    // result.steps: detalles de cada paso
  };

  const handleError = (error) => {
    console.error('Error:', error);
  };

  return (
    <UsivSDKProvider config={{ environment: 'development' }}>
      <UsivVerificationWidget
        verificationData={verificationData}
        onComplete={handleComplete}
        onError={handleError}
      />
    </UsivSDKProvider>
  );
}

🏗️ Flujo de Integración

1. Empresa obtiene API Key

// Backend de empresa
const response = await fetch('https://usivsdkapi-27rrhfccda-rj.a.run.app/v1/verifications', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer usiv_sk_r8QguZx982Lx1zCzdx6ft0k5CNihFgrMxDn97d4WCf4',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    rut: '17803819-2',
    email: '[email protected]'
  })
});

const { verificationId, sessionToken } = await response.json();

2. Empresa embebe widget

// Frontend de empresa
<UsivVerificationWidget
  verificationData={{ verificationId, sessionToken }}
  onComplete={(result) => {
    // Enviar resultado al backend
    fetch('/api/verification-complete', {
      method: 'POST',
      body: JSON.stringify(result)
    });
  }}
/>

🎯 Pasos del Widget

1. 📱 Liveness Detection - Verificación biométrica del rostro
2. 📄 Documento Frontal - Captura del frente de la cédula
3. 🔄 Documento Reverso - Captura del reverso (MRZ)
4. ✅ Resultado - Validación completa

💰 Sistema de Créditos

• Liveness: 100 créditos
• Documento frontal: 100 créditos
• Documento reverso: 100 créditos
• Total: 300 créditos por verificación completa

🔧 Configuración por Ambiente

// Desarrollo (default)
<UsivSDKProvider config={{ environment: 'development' }}>

// Producción
<UsivSDKProvider config={{ 
  environment: 'production',
  baseUrl: 'https://tu-backend-prod.com'
}}>

📋 Props del Widget

| Prop | Tipo | Requerido | Descripción | |------|------|-----------|-------------| | verificationData | object | ✅ | { verificationId, sessionToken, rut?, email? } | | onComplete | function | ❌ | (result: VerificationResult) => void | | onError | function | ❌ | (error: Error) => void | | className | string | ❌ | Clase CSS personalizada | | style | object | ❌ | Estilos CSS inline |

🎨 Personalización CSS

/* Contenedor principal */
.usiv-widget-container {
  max-width: 460px;
  margin: 0 auto;
}

/* Estados de resultado */
.usiv-result.success {
  background: #f0fdf4;
  border-color: #bbf7d0;
}

.usiv-result.failed {
  background: #fef2f2;
  border-color: #fecaca;
}

/* Pasos del wizard */
.usiv-step {
  padding: 24px;
}

.usiv-instructions {
  background: #f9fafb;
  padding: 16px;
  border-radius: 8px;
}

🔄 Respuesta de Verificación

interface VerificationResult {
  success: boolean;
  verificationId: string;
  status: string;
  steps: {
    liveness: { completed: boolean; result: string };
    documentFront: { completed: boolean; result: string };
    documentBack: { completed: boolean; result: string };
  };
}

🛡️ Seguridad

• ✅ Tokens JWT con expiración (1 hora)
• ✅ Validación de sesión en cada paso
• ✅ AWS Rekognition para procesamiento biométrico
• ✅ HTTPS obligatorio en producción

📞 Soporte

¿Problemas? Contacta a: [email protected]

📄 Licencia

MIT License - Ver archivo LICENSE para detalles