Integración — cómo aceptar verificado.do

El modelo

Es el mismo patrón del itsme belga: la identidad vive en el teléfono del ciudadano, no en su base de datos. Usted nunca ve el número de cédula, ni la fotografía, ni los datos del chip. Recibe un seudónimo.

Su servidor abre una sesión y recibe un QR.
El usuario lo escanea con la app verificado.do.
Su pantalla muestra dos dígitos; el usuario los escribe en el teléfono. Esto no se puede aprobar por reflejo, que es como funcionan los ataques de fatiga de notificaciones.
El usuario confirma con su huella o su PIN. El teléfono firma el reto con una clave que nunca sale del dispositivo.
Su servidor consulta el resultado y recibe el seudónimo.

Dos endpoints

Base: https://verificado.do/api

Abrir la sesión

POST/api/session/start

# petición
{
  "rp":     "su-servicio.do",
  "scope":  "Identidad verificada",
  "verb":   "Entrar",
  "claims": ["name", "aal"]
}

# respuesta
{
  "sid":       "…",   // id de sesión — NO es secreto, va en el QR
  "qr":        "data:image/png;base64,…",
  "qrPayload": "verificado://login?sid=…",
  "icon":      "…",   // muéstrelo: el usuario lo compara en su teléfono
  "pollToken": "…"    // SECRETO. Guárdelo en el servidor, nunca en el navegador
}

El sid no es una credencial. Está impreso en un QR en una pantalla que cualquiera puede fotografiar. Lo que libera el resultado es el pollToken, que sólo conoce quien abrió la sesión. No los confunda.

Consultar el resultado

GET/api/session/{sid}/status

Con la cabecera x-vdo-poll: {pollToken}. Sin ella la respuesta dice sólo si la sesión se concedió o se bloqueó, nunca quién.

# mientras espera
{ "status": "pending", "result": null }

# concluida, con el pollToken correcto
{
  "status": "done",
  "result": {
    "sub":      "vdo_…",   // el seudónimo. Esto es lo que usted guarda
    "aal":      1,
    "sigValid": true,
    "granted":  true,
    "blocked":  false,
    "at":       "2026-08-22T…Z"
  }
}

Qué es `sub`, y por qué no es la cédula

Es un seudónimo por servicio: HMAC-SHA256(clave, cuenta | su-dominio). La misma persona entrando en dos servicios distintos produce dos identificadores distintos y sin relación aparente. Ni usted ni otro servicio pueden cruzarlos, y de él no se puede deducir el número de cédula.

Es estable: la misma persona en su servicio devuelve siempre el mismo sub. Úselo como la clave primaria de su usuario.

Los tres niveles de garantía

Cada resultado lleva un campo aal con un número del 1 al 3, y ese número lo concluye nuestro servidor, no la app del usuario. Lo que la app pide se guarda para auditoría y nunca se usa para decidir: si el servidor no comprobó el chip por sí mismo, el nivel es 1.

`aal`	Nombre	Qué exige	Hoy
1	Bajo	El punto de partida. Es también el techo cuando la prueba del chip no se pudo evaluar —por ejemplo, cuando no tenemos cargado el certificado raíz del emisor—, cuando el chip no acredita el mismo identificador con el que se abrió la cuenta, o cuando el documento está vencido.	SE EMITE
2	Sustancial	Las tres condiciones a la vez: la autenticación pasiva del documento se comprueba contra un certificado raíz que ya tenemos cargado —nunca uno que ofrezca el propio chip—; el chip acredita el mismo identificador con el que se abrió la cuenta; y el documento no está vencido.	SÓLO CON ANCLA CARGADA
3	Alto	Exige además autenticación activa del chip comprobada en el servidor: un reto criptográfico que sólo puede responder el chip físico emitido. Nuestro servidor todavía no ejecuta esa comprobación, de modo que ninguna respuesta devuelve hoy este valor.	NO SE EMITE

Con una cédula dominicana el valor es 1. No por el documento: el chip responde y sus datos están íntegros. Es porque el nivel 2 exige comprobar la firma del emisor del documento contra el certificado raíz de la Junta Central Electoral, y ese certificado no está publicado. Mientras no lo esté, ninguna cédula pasa de 1.

El nivel no cambia lo que usted recibe: el seudónimo sub es el mismo en los tres. Dice cuánto se comprobó, no cuánto se entrega. Usted decide a partir de qué nivel acepta cada operación.

Bajo, sustancial y alto son el vocabulario de eIDAS, usado aquí como escala legible. No implican conformidad ni notificación.

Nivel de garantía — lo que hoy podemos afirmar

El campo aal dice cuánto se comprobó. Con una cédula dominicana hoy vale 1, y decimos por qué sin adornos: el chip responde correctamente al reto criptográfico —es el chip físico emitido, no una copia— y sus datos están íntegros. Lo que todavía no se puede comprobar es la autoría de la firma, porque la Junta Central Electoral no ha publicado su certificado raíz. Lo hemos solicitado formalmente.

Con un pasaporte que sí publica su raíz, la cadena se comprueba completa. El registro fechado de qué se ha verificado y qué no está en Evidencia.

Compruébenos usted

GET /api/pubkey — la clave con la que se autentican nuestras respuestas.
GET /api/csca — las anclas de confianza cargadas, con emisor y vigencia.

Ninguno de los dos exige cuenta, contrato ni permiso.

Para empezar

Los servicios que pueden abrir sesión están en una lista blanca del lado del servidor: hace falta registrar su dominio, la URL a la que devolvemos al usuario y el nombre que verá en la pantalla de confirmación. Eso evita que un tercero abra sesiones en su nombre, y es también lo que impide que la página de identificación se convierta en un redirector abierto.

Escríbanos desde contacto con esos tres datos y le respondemos con las credenciales de prueba.

Cómo aceptar verificado.do.