Ir al contenido principal

Guía de integración

¿Qué es el VID y para qué sirve?

El VID (Verificador de Identidad Dominicano) es una capa adicional de seguridad que ofrece el Registro de Cuenta Única Ciudadana. Permite que una institución pública o privada confirme que la persona que está frente al dispositivo es realmente el titular de la cédula, usando una prueba biométrica de vida (reconocimiento facial).

Desde el punto de vista del ciudadano:
  1. Se autentica en el sistema de la institución con su Cuenta Única.
  2. Al momento de realizar algún trámite especial, la institución lo envía a la verificación del VID.
  3. Si todo sale bien, el VID redirige de vuelta al sistema de la institución.
La experiencia es muy parecida a un flujo de OAuth2 clásico: se construye una URL con parámetros, se valida, se realiza la prueba y se redirige al redirect_uri.  

¿Quiénes pueden usar el VID?

Una institución puede usar el VID si cumple con estas condiciones:
  1. Ya tiene una integración vigente con Cuenta Única Ciudadana, es decir, ya tiene un cliente OAuth2 creado para registro e inicio de sesión.
  2. Ese cliente OAuth2 está configurado con:
    1. Uno o varios redirect URIs para el flujo normal de Cuenta Única (inicio sesión).
    2. Un redirect URI específico al que se enviará el ciudadano cuando el VID termine de forma exitosa (por ejemplo, una pantalla de “identidad verificada” dentro de tu sistema).

Si aún no tienes el cliente OAuth2, el primer paso es gestionar con OGTIC la creación de ese cliente para tu institución.

Vista general del flujo de integración

A alto nivel, el flujo completo se ve así:
  1. La institución prepara su sistema:
    1. Confirma que tiene un cliente OAuth2 de Cuenta Única.
    2. Define el endpoint o pantalla donde quiere recibir al usuario luego del VID (redirect_uri).
  2. El sistema de la institución construye una URL y redirige al ciudadano hacia el VID.
  3. El VID valida la solicitud:
    1. Revisa el cliente, el redirect, el token de sesión y la cédula.
    2. Crea internamente un flow temporal.
  4. El ciudadano realiza la prueba de vida.
  5. Si la verificación es exitosa, el VID redirige al ciudadano hacia el redirect_uri que la institución definió.
  6. La institución recibe al ciudadano en su redirect_uri y continúa el proceso que necesite (firmar un contrato, aprobar una transacción, completar una solicitud, etc.).

Prerrequisitos para integrarse

Antes de escribir una sola línea de código, la institución debe tener claro lo siguiente:
  1. Cliente OAuth2 de Cuenta Única
    1. Se debe contar con un client_id emitido por Cuenta Única Ciudadana.
  2. Redirect URIs registrados
    1. Al menos uno para el flujo normal de inicio de sesión.
    2. Uno específico para el VID, por ejemplo:
      1. https://miinstitucion.gob.do/vid/callback
  3. Ciudadano autenticado
    1. El flujo VID necesita un access_token de Cuenta Única que ya esté activo para el ciudadano.
    2. Ese token se obtiene cuando el ciudadano inicia sesión con Cuenta Única.
  4. Ciudadano registrado en el registro civíl
    1. El VID consulta la cédula y datos básicos en las fuentes oficiales. Si el ciudadano no existe en el padrón, el flujo no puede continuar.

Paso a paso para integrar el VID

Definir el caso de uso dentro de tu institución
Primero, es importante decidir cuándo se va a usar el VID. Algunos ejemplos pudiesen ser:
  • Antes de permitir la firma digital de un contrato.
  • Para aprobar operaciones sensibles.
  • Como parte de la apertura de cuentas o servicios de alto riesgo.
La institución debe definir:
  • En qué momento del flujo se disparará el VID.
  • Qué significa “validación exitosa” en sus procesos (por ejemplo: cambiar el estado de “pendiente” a “validado por VID”).
Configurar el redirect URI del VID
En el cliente OAuth2 de Cuenta Única, se debe registrar el redirect de retorno del VID. Ejemplo:
https://miinstitucion.gob.do/vid/callback
Ese endpoint será el lugar donde el ciudadano volverá después de pasar por el VID. Desde el punto de vista del sistema, es el lugar perfecto para:
  • Marcar que la identidad fue verificada mediante el VID.
  • Retomar el flujo que estaba en pausa.
Construir la URL para iniciar el VID
Desde el sistema de la institución (web, móvil o backend), cuando se decida lanzar el VID, se debe construir una URL con el siguiente formato:  
  • GET /{lang}/vid?client_id=UUID&redirect_uri=URL&access_token=TOKEN
    • Donde:
      • lang: idioma que quieres usar en la interfaz del VID (es, en, etc.).
      • client_id: el identificador OAuth2 de tu institución en Cuenta Única.
      • redirect_uri: el mismo redirect que registraste para el VID.
      • access_token: el token de sesión del ciudadano en Cuenta Única (ya autenticado).

¿Qué pasa dentro del VID?

Cuando el ciudadano llega a esa URL, el VID  hace varias cosas de seguridad:  
  • Valida que el client_id existe y está activo.
  • Revisa que el redirect_uri coincida exactamente con uno de los que tiene el cliente.
  • Introspecciona el access_token para obtener la cédula del ciudadano.
  • Verifica que la cédula existe en el registro civíl.
  • Realiza prueba de vida
Si algo falla, aparece una página 404.

Si todo está bien:
  • Se crea una sesión temporal (un “flow”) con una duración corta (alrededor de 120 segundos).
  • Se guarda la información básica (cédula, nombre, redirect) en una cookie segura.
  • Se redirige al ciudadano a una URL limpia que solo contiene ?flow=... en lugar de mostrar el access_token en la barra de direcciones.

Esto se hace para que el token no quede en el historial, capturas de pantalla o enlaces compartidos.

Luego, la interfaz muestra:
o Un saludo con el nombre del ciudadano.
o Unas condiciones simples (tener cámara, permitir uso de la cámara, advertencia sobre luces intermitentes, etc.).
o Un botón para iniciar el proceso.
Al hacer clic, se abre un componente de prueba de vida con la cámara que guía al ciudadano paso a paso. Si hay algún problema (cámara bloqueada, dispositivo no soportado, mala iluminación, el rostro no coincide con la foto del registro), se muestran mensajes claros y el sistema permite reintentar.  

Redirección de vuelta

Cuando la prueba de vida indica que hay coincidencia entre el rostro del ciudadano y su foto oficial, el VID ejecuta la lógica de redirección. Para la institución, lo importante es que:
  • El ciudadano va a regresar al redirect_uri.
  • Se puede reconocer qué operación estaba haciendo con el parámetro state u otro mecanismo propio.
A partir de ese momento, se puede marcar en el sistema que la identidad fue verificada mediante VID y continuar el proceso con más confianza.
Volver arriba