# Guía de integración

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

<div id="bkmrk-el-vid-%28verificador-" style="text-align: justify;">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).</div><div id="bkmrk-">  
</div><div id="bkmrk-desde-el-punto-de-vi">Desde el punto de vista del ciudadano:</div>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.

<div id="bkmrk-la-experiencia-es-mu">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*. </div><div id="bkmrk--1"></div>#### ¿Quiénes pueden usar el VID?

<div id="bkmrk-una-instituci%C3%B3n-pued">Una institución puede usar el VID si cumple con estas condiciones:</div><div id="bkmrk-ya-tiene-una-integra">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).

</div><p class="callout info">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.</p>

#### Vista general del flujo de integración

<div id="bkmrk-a-alto-nivel%2C-el-flu">A alto nivel, el flujo completo se ve así:</div><div id="bkmrk-la-instituci%C3%B3n-prepa">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.).

</div>#### Prerrequisitos para integrarse

<div id="bkmrk-antes-de-escribir-un">Antes de escribir una sola línea de código, la institución debe tener claro lo siguiente:</div><div id="bkmrk-cliente-oauth2-de-cu">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](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.

</div>#### Paso a paso para integrar el VID

##### Definir el caso de uso dentro de tu institución

<div id="bkmrk-primero%2C-es-importan">Primero, es importante decidir cuándo se va a usar el VID. Algunos ejemplos pudiesen ser:</div><div id="bkmrk-antes-de-permitir-la">- 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.

</div><div id="bkmrk-la-instituci%C3%B3n-debe-">La institución debe definir:</div><div id="bkmrk-en-qu%C3%A9-momento-del-f">- 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”).

</div>##### Configurar el redirect URI del VID

<div id="bkmrk-en-el-cliente-oauth2">En el cliente OAuth2 de Cuenta Única, se debe registrar el redirect de retorno del VID. Ejemplo:</div><div id="bkmrk-https%3A%2F%2Fmiinstitucio">https://miinstitucion.gob.do/vid/callback</div><div id="bkmrk--2"></div><div id="bkmrk-ese-endpoint-ser%C3%A1-el">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:</div><div id="bkmrk-marcar-que-la-identi">- Marcar que la identidad fue verificada mediante el VID.
- Retomar el flujo que estaba en pausa.

</div>##### Construir la URL para iniciar el VID

<div id="bkmrk-desde-el-sistema-de-">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: </div><div id="bkmrk-get-%2F%7Blang%7D%2Fvid%3Fclie">- GET /{lang}/vid?client\_id=UUID&amp;redirect\_uri=URL&amp;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).

</div>#### ¿Qué pasa dentro del VID?

<div id="bkmrk-cuando-el-ciudadano-">Cuando el ciudadano llega a esa URL, el VID hace varias cosas de seguridad: </div><div id="bkmrk-valida-que-el-client">- 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

</div><div id="bkmrk-si-algo-falla%2C-apare">Si algo falla, aparece una página 404.</div><div id="bkmrk--3">  
</div><div id="bkmrk-si-todo-est%C3%A1-bien%3A">Si todo está bien:</div><div id="bkmrk-se-crea-una-sesi%C3%B3n-t">- 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.

</div><div id="bkmrk--4">  
</div><div id="bkmrk-esto-se-hace-para-qu">Esto se hace para que el token no quede en el historial, capturas de pantalla o enlaces compartidos.</div><div id="bkmrk--5">  
</div><div id="bkmrk-luego%2C-la-interfaz-m">Luego, la interfaz muestra:</div><div id="bkmrk-o-un-saludo-con-el-n">o Un saludo con el nombre del ciudadano.</div><div id="bkmrk-o-unas-condiciones-s">o Unas condiciones simples (tener cámara, permitir uso de la cámara, advertencia sobre luces intermitentes, etc.).</div><div id="bkmrk-o-un-bot%C3%B3n-para-inic">o Un botón para iniciar el proceso.</div><div id="bkmrk--6"></div><div id="bkmrk-al-hacer-clic%2C-se-ab">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. </div>#### Redirección de vuelta

<div id="bkmrk-cuando-la-prueba-de-">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:</div><div id="bkmrk-el-ciudadano-va-a-re">- 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.

</div><div id="bkmrk-a-partir-de-ese-mome">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.</div><div id="bkmrk--16"></div>