Integración de Veriff para Verificación de Identidad

Esta guía describe cómo funciona la solución completa de integración con Veriff, qué componentes la conforman, qué dependencias requiere y cómo comenzar a usarla.

---

1. Descripción general

El proyecto implementa un flujo de verificación de identidad con Veriff mediante:

• Front-end HTML/JavaScript: Muestra la interfaz de usuario, carga el SDK de Veriff, lanza la ventana de verificación y gestiona el estado de la verificación.

• Back-end PHP:

  • Endpoint GET para que el cliente realice polling de la decisión (index.php?docNumber=...).
  • Webhook que recibe los eventos de Veriff ($_SERVER REQUEST_METHOD === POST) y guarda la decisión final en archivos JSON.
  • Clase DesicionVeriff para formatear la respuesta de Veriff.
  • Log de eventos para depurar y auditar.

• Interfaz de visualización de eventos (view_events.php).

---

2. Requisitos

• Servidor web con soporte PHP 8+.
• Escritura en disco para directorios: /decisions y /logs.
• Clave pública de Veriff (API Key) para la inicialización del SDK.
• Conexión HTTPS para seguridad (cookie Secure).
• Navegador moderno con JavaScript habilitado.

---

3. Instalación y configuración

1. Clona el repositorio en tu servidor:

   git clone https://github.com/miusarname2/TestVeriff
   cd TestVeriff

2. Configura la API Key

   • Edita app.js y reemplaza:

     apiKey: 'Public API Key',

     por tu clave real.

3. Asegura los permisos

   • Crea y otorga permisos de escritura a los directorios:

     mkdir decisions logs
     chmod 755 decisions logs

4. Despliegue HTTPS

   • Configura tu servidor (Apache/Nginx) con un certificado TLS válido.

5. Puntos de entrada

   • index.html (o equivalente) carga app.js.
   • index.php maneja tanto polling en GET como webhook en POST.
   • DesicionVeriff.php contiene la clase de formateo.
   • view_events.php muestra el log de eventos.

---

4. Flujo de la aplicación

4.1 Front-end

1. El usuario abre la página HTML.

2. Al hacer clic en "Iniciar verificación", se crea la instancia de Veriff:

   • Se pasa un objeto vendorData con el documentNumber y campos adicionales.
   • Se ocultan los inputs de nombre, ya que person ya está preconfigurado.

3. En el callback onSession, se recibe la URL de la sesión y el ID:

   • Se guarda en data-veriff-session-id.
   • Se monta el iFrame de Veriff.

4. El front-end escucha el mensaje VERIFF_FINISHED para iniciar el polling.

5. La función pollVerificationResult() consulta index.php?docNumber=... hasta obtener un resultado no pending.

6. Una vez disponible, muestra el resultado en el contenedor #verification-results.

4.2 Back-end PHP

4.2.1 Endpoint GET (Polling)

• Ruta: index.php?docNumber={docNumber}

• Lógica:

  1. Obtiene docNumber de GET o de cookie sessionId.
  2. Construye la ruta al archivo JSON: /decisions/{sessionId}.json.
  3. Si no existe, responde { status: 'pending' }.
  4. Si existe, lee y devuelve el contenido JSON.

4.2.2 Webhook POST

• Recepción de eventos started, submitted: responde {'status':'received'} para ACK.

• Evento fullauto con status==='success':

  1. Decodifica vendorData para extraer documentNumber.
  2. Genera sessionId a partir de él y crea cookie HttpOnly/Secure.
  3. Formatea la respuesta con DesicionVeriff::formatVerificationJson().
  4. Guarda el objeto resultante en /decisions/{sessionId}.json.
  5. Registra el evento en logs/veriff_events.log.
  6. Responde con { status: 'success', message: 'Webhook processed...' }.

4.2.3 Clase DesicionVeriff

class DesicionVeriff {
    // Recibe decision ('approved'|'rejected') y score
    public function __construct(string $decision, string|float $decisionScore, string|int $document) { ... }
    // Convierte 'approved' a true, otro caso false
    protected function convertDescicionToBool(string $decision): bool { ... }
    // Formatea el JSON bruto del webhook a un objeto con campos esenciales
    public static function formatVerificationJson(string $jsonDecision): object { ... }
}

4.2.4 Ver Logs

• view_events.php muestra el contenido de logs/veriff_events.log en reversa para ver los eventos más recientes arriba.

---

5. Personalización y buenas prácticas

• Campos adicionales: Añade en vendorData otros identificadores (ej.: user_id, company_id).

• Seguridad:

  • Valida y sanitiza vendorData y docNumber.
  • Usa HTTPS y cookies seguras.

• UI: Adapta estilos con Tailwind o tu propio CSS.

• Escalabilidad: En lugar de archivos, almacena las decisiones en base de datos.

---

6. Detectar y resolver errores comunes

• data-veriff-vendor-data no encontrado: Asegúrate de setear el atributo antes de iniciar Veriff.
• Permisos de archivos: Verifica lecto-escritura en /decisions y /logs.
• Cookie no enviada: Revisa ruta y dominio en setcookie().