@quickcheck/device-intel-sdk

QuickCheck Device Intelligence SDK for Web (JavaScript / TypeScript)

Device fingerprinting, IP intelligence, and real-time risk scoring for AML/KYC compliance. Cumple con el Artículo 14 del Acuerdo SBP sobre vinculación remota de clientes por medios digitales.

Instalación

npm (recomendado para React / Vue / Angular / Next.js)

npm install @quickcheck/device-intel-sdk

CDN (vanilla JS / HTML)

<script src="https://qcassetsprod.blob.core.windows.net/sdk/web/v1/qcdi.min.js"></script>

Uso rápido

import { QuickCheckDeviceIntel } from '@quickcheck/device-intel-sdk';

const qcdi = new QuickCheckDeviceIntel({
  apiKey: 'qc_sdk_live_xxxxxxxxxxxx',  // Obtenida en tu dashboard de QuickCheck
});

// Ejecutar assessment (típicamente en login, onboarding o transacciones)
const result = await qcdi.assess({
  sessionType: 'onboarding',
  externalUserId: 'usr_12345',
  declaredCountry: 'PA',
});

// Actuar según el resultado
if (result.risk.action === 'block') {
  alert('Acceso restringido. Código: ' + result.assessment_id);
  return;
}
if (result.risk.action === 'review') {
  showWarning('Se requiere verificación adicional');
}
// allow → continuar normalmente

Configuración

interface QCConfig {
  apiKey: string;                            // REQUERIDO
  apiUrl?: string;                           // Default: https://api.quickcheck.com.pa
  autoCollect?: boolean;                     // Default: true (pre-recopila señales)
  requestGeolocation?: boolean;              // Default: false (pide permiso GPS)
  timeout?: number;                          // Default: 5000 ms
  onError?: (error: Error) => void;          // Callback para errores
  debug?: boolean;                           // Default: false
}

API

qcdi.assess(options)

Ejecuta un assessment de dispositivo. Envía señales al endpoint QuickCheck y retorna el resultado de scoring.

interface AssessOptions {
  sessionType: 'onboarding' | 'login' | 'transaction' | 'custom';
  externalUserId?: string;
  externalSessionId?: string;
  declaredCountry?: string;      // ISO 3166-1 alpha-2 (ej: 'PA', 'US')
  personName?: string;
  personDocumentId?: string;
  customFields?: Record<string, unknown>;
}

Response:

interface AssessmentResult {
  assessment_id: string;        // "dia_xxxxx"
  session_id: number;
  timestamp: string;
  risk: {
    score: number;              // 0-100
    level: 'low' | 'medium' | 'high' | 'critical';
    action: 'allow' | 'review' | 'block';
    recommendation: string | null;
  };
  flags: {
    vpn_detected: boolean;
    tor_detected: boolean;
    proxy_detected: boolean;
    datacenter_ip: boolean;
    country_mismatch: boolean;
    // ... ver tipos completos
  };
  ip_intelligence: { country_code, city, isp, is_vpn, is_tor, ... };
  coherence: { country_match, timezone_match, language_match };
  metadata: { processing_time_ms, rules_evaluated, rules_triggered };
}

qcdi.initialize()

Pre-recopila señales del dispositivo. Se llama automáticamente si autoCollect=true.

qcdi.refresh()

Re-colecta las señales del dispositivo. Útil si el entorno cambió (ej: nueva red).

qcdi.destroy()

Libera recursos. Llamar en logout.

Señales recopiladas

| Categoría | Señales | |-----------|---------| | Dispositivo | OS, versión, resolución, zona horaria, idioma, hardware concurrency, memoria, touch support | | Red | Tipo de conexión (wifi/cellular), effective type (4g/wifi), WebRTC IPs | | Privacidad | Modo incógnito, WebGL renderer, canvas hash, WebRTC leak | | Fingerprint | SHA-256 generado por ThumbmarkJS (MIT) | | Geolocalización | GPS browser (opcional, requiere permiso del usuario) |

Cuándo ejecutar assessment

Recomendado en estos puntos del journey del usuario:

• Onboarding / apertura de cuenta: assessment obligatorio (Art. 14)
• Login: opcional, pero recomendado para detectar account takeover
• Transacciones sensibles: opcional, útil para transferencias de alto monto
• Búsquedas de compliance: si ofreces acceso a información sensible

Manejo de errores

El SDK lanza QuickCheckError con código específico:

try {
  const result = await qcdi.assess({ sessionType: 'onboarding' });
} catch (err) {
  if (err.code === 'UNAUTHORIZED')  { /* API key inválida */ }
  if (err.code === 'RATE_LIMITED')  { /* cuota diaria excedida */ }
  if (err.code === 'TIMEOUT')       { /* timeout — fail-open recomendado */ }
  if (err.code === 'NETWORK_ERROR') { /* sin conexión */ }
}

Recomendación: fail-open en caso de error de red (permitir acceso) para no bloquear a usuarios legítimos por problemas de conectividad. Registrar el error para análisis posterior.

Privacidad y consentimiento

• Ninguna señal se envía sin que el usuario interactúe con tu aplicación
• El GPS solo se solicita si configuras requestGeolocation: true (requiere permiso explícito del usuario)
• El fingerprint hash NO contiene información identificable directamente

Ejemplos

Ver examples/vanilla/index.html para una demo completa con UI.

License

Proprietary — QuickCheck Panamá (CORETECH SOLUTIONS, S.A.)