verifica.net.pe expone una API REST sobre la verificación oficial del DNId (DNI digital) de RENIEC, que los ciudadanos presentan desde la app Perú Pass. El usuario autoriza cada dato; nunca escribes ni almacenas su documento.
# 1. Crea una verificación (pide solo lo que necesitas) curl -X POST https://api.verifica.net.pe/v1/verifications \ -H "Authorization: Bearer vfk_live_TU_KEY" \ -H "Content-Type: application/json" \ -d '{"claims":["fechaNacimiento","nombreCompleto"]}' # Respuesta { "id": "vfy_a1b2c3...", "status": "pending", "deep_link": "openid4vp://authorize?client_id=...&request_uri=...", "qr_url": "https://api.verifica.net.pe/v1/verifications/vfy_a1b2c3.../qr.svg", "expires_at": 1795152764020 } # 2. Muestra el QR (qr_url) o abre deep_link en el móvil del usuario. # El usuario autoriza en Perú Pass qué datos compartir. # 3. Consulta el resultado (o espera el webhook) curl https://api.verifica.net.pe/v1/verifications/vfy_a1b2c3... \ -H "Authorization: Bearer vfk_live_TU_KEY"
Pega una key vfk_test_ (créala en el dashboard, gratis) y corre el flujo completo contra el sandbox de Perú Pass:
El DNId soporta divulgación selectiva: el usuario comparte solo lo que pides. Algunos patrones comunes:
| Caso | Qué pedir | Ejemplo |
|---|---|---|
| Verificación de edad (delivery, juegos, contenido +18) | fechaNacimiento → usamos mayorDeEdad / edad | {"claims":["fechaNacimiento"]} |
| Anti multicuentas (una cuenta por persona) | dni — hashea el número en tu sistema como identificador único | {"claims":["dni"]} |
| KYC / onboarding (fintech, marketplaces) | Nombre completo + DNI + fecha | {"claims":["nombreCompleto","dni","fechaNacimiento"]} |
| Encuestas / censo (1 voto por persona, sin identidad) | Solo dni para deduplicar — no guardes el valor, hashealo | {"claims":["dni"]} |
| Domicilio / logística | domicilio + nombre | {"claims":["nombreCompleto","domicilio"]} |
Principio de minimización (Ley 29733): pide solo lo que necesitas. El usuario ve exactamente qué comparte antes de autorizar en Perú Pass.
Todas las rutas /v1/* usan una API key en el header Authorization: Bearer <key>. Las keys se crean en el dashboard:
| Prefijo | Uso |
|---|---|
vfk_test_... | Modo test: flujo real con Perú Pass, limitado a tus DNIs autorizados. Sin cuota. |
vfk_live_... | Producción: verificaciones reales contra RENIEC |
Con una key vfk_test_ la verificación corre el mismo flujo real que producción: el usuario escanea el QR con la app oficial Perú Pass y presenta su DNId. La diferencia:
PUT /me/test-dnis).failed y no se dispara ningún webhook.failed con evento verification.failed (reason dni_not_whitelisted).POST /v1/verifications
| Campo | Tipo | Descripción |
|---|---|---|
| claims | string[] | Opcional. Datos que necesitas (documentativo; el perfil real lo define tu presentation definition). |
| presentation_definition_id | string | Opcional. Perfil de datos de RENIEC a solicitar. |
| retain_credential | bool | Opcional (default false). Si es true, conservamos la credencial SD-JWT para poder revalidarla después. Por privacidad (Ley 29733) está apagado por defecto — solo actívalo si necesitas /v1/reverify. |
Respuesta 201: id, deep_link, qr_url (SVG listo para incrustar), expires_at.
GET /v1/verifications/{id}
| status | Significado |
|---|---|
| pending | Esperando que el usuario escanee/autorice en Perú Pass |
| completed | Credencial verificada por RENIEC; claims disponible |
| failed | La presentación falló o la credencial fue inválida |
| expired | El enlace venció sin presentación |
Cuando status = failed, el campo error_reason explica el motivo:
| error_reason | Significado |
|---|---|
| dni_not_shared | (test) El usuario no autorizó compartir su DNI — sin DNI no se puede validar la whitelist. No se envía webhook. |
| dni_not_whitelisted | (test) El DNI compartido no está en tu lista de DNIs de prueba. |
| invalid_credential:<status> | RENIEC rechazó la credencial o la presentación. |
| provider_error | Error interno al consultar el resultado. |
| expired | El enlace venció sin presentación (status expired). |
En producción el endpoint hace long-polling interno contra RENIEC, así que una llamada puede demorar hasta ~55s mientras espera al usuario.
Cuando status = completed, el campo claims trae los datos autorizados decodificados del SD-JWT:
{
"claims": {
"dni": "47291038",
"nombres": "JUAN CARLOS",
"apellidoPaterno": "PEREZ",
"apellidoMaterno": "GOMEZ",
"nombreCompleto": "JUAN CARLOS PEREZ GOMEZ",
"fechaNacimiento": "1990-05-15",
"edad": 36,
"mayorDeEdad": true,
"sexo": "M", "nacionalidad": "PERUANA", "estadoCivil": "SOLTERO",
"raw": { "CUI_DNI": "47291038", ... } // campos originales RENIEC
}
}
Solo aparecen los campos que el usuario autorizó en Perú Pass. edad y mayorDeEdad se calculan de fechaNacimiento — ideal para verificación de edad sin recibir el documento completo.
POST /v1/reverify — revalida una credencial SD-JWT contra RENIEC (/vc-verification). Requiere retain_credential: true al crear la verificación, o pasar el credential (SD-JWT) directamente en el body.
curl -X POST https://api.verifica.net.pe/v1/reverify \
-H "Authorization: Bearer vfk_live_..." \
-d '{"verification_id":"vfy_a1b2c3..."}'
# → {"verificationStatus":"SUCCESS"}
El webhook se configura por API key (cada key puede notificar a un endpoint distinto — útil si manejas varios tipos de verificación). Configúralo en el dashboard o con PATCH /me/keys/{id}/webhook. Enviamos un POST por cada evento terminal:
| event | Cuándo |
|---|---|
| verification.completed | Claims listos |
| verification.failed | Verificación inválida |
| verification.expired | Expiró sin presentación |
Headers: X-Verifica-Signature = base64url(HMAC-SHA256(secret, timestamp.body)) y X-Verifica-Timestamp. El secret se muestra al guardar la URL.
| Código | error | Significado |
|---|---|---|
| 401 | invalid_api_key | Key inválida o revocada |
| 404 | not_found | Verificación inexistente o de otro cliente |
| 429 | quota_exceeded | Límite mensual del plan alcanzado |
| 502 | reniec_unavailable | Servicio de RENIEC no disponible |