Quickstart

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"

Pruébalo aquí

Pega una key vfk_test_ (créala en el dashboard, gratis) y corre el flujo completo contra el sandbox de Perú Pass:

Casos de uso

El DNId soporta divulgación selectiva: el usuario comparte solo lo que pides. Algunos patrones comunes:

CasoQué pedirEjemplo
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ísticadomicilio + 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.

Autenticación

Todas las rutas /v1/* usan una API key en el header Authorization: Bearer <key>. Las keys se crean en el dashboard:

PrefijoUso
vfk_test_...Modo test: flujo real con Perú Pass, limitado a tus DNIs autorizados. Sin cuota.
vfk_live_...Producción: verificaciones reales contra RENIEC

Modo test (sandbox)

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:

  • Solo completan verificaciones de usuarios cuyo DNI esté en tu whitelist (máx. 5, se configura en el dashboard o con PUT /me/test-dnis).
  • En modo test el usuario debe autorizar compartir su DNI en Perú Pass — es la única forma de validar la whitelist. Si no lo comparte, la verificación termina en failed y no se dispara ningún webhook.
  • Si comparte un DNI que no está en tu whitelist: failed con evento verification.failed (reason dni_not_whitelisted).
  • El QR de test lleva un aviso SANDBOX en el centro. No consume tu cuota mensual.

Crear verificación

POST /v1/verifications

CampoTipoDescripción
claimsstring[]Opcional. Datos que necesitas (documentativo; el perfil real lo define tu presentation definition).
presentation_definition_idstringOpcional. Perfil de datos de RENIEC a solicitar.
retain_credentialboolOpcional (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.

Consultar estado

GET /v1/verifications/{id}

statusSignificado
pendingEsperando que el usuario escanee/autorice en Perú Pass
completedCredencial verificada por RENIEC; claims disponible
failedLa presentación falló o la credencial fue inválida
expiredEl enlace venció sin presentación

Cuando status = failed, el campo error_reason explica el motivo:

error_reasonSignificado
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.
missing_claims:a,bEl usuario no autorizó todos los claims que pediste. Los que sí autorizó vienen en claims y la lista en missing_claims.
provider_errorError interno al consultar el resultado.
expiredEl 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.

Claims normalizados

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.

Reverificación

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"}

Webhooks

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:

eventCuándo
verification.completedClaims listos
verification.failedVerificación inválida
verification.expiredExpiró 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.

Errores

CódigoerrorSignificado
401invalid_api_keyKey inválida o revocada
404not_foundVerificación inexistente o de otro cliente
429quota_exceededLímite mensual del plan alcanzado
502reniec_unavailableServicio de RENIEC no disponible