●  29 de octubre de 2026 · Cumplimiento · Lectura de 6 min

Verifica identidad y listas de riesgo con dos llamadas a la API

Eres el único desarrollador de tu equipo, o no hay ninguno, y te toca conectar la verificación de identidad a tu app. Esta receta te lleva de una prueba en sandbox a un registro que puedes mostrar cuando un auditor pregunte.

Qué vas a lograr

Vas a hacer dos llamadas a la API de VerificaID con un DNI (documento de identidad peruano):

  • Una consulta de persona, que valida el DNI y devuelve el nombre asociado.
  • Un reporte de listas de riesgo, que te dice si esa persona aparece como PEP (persona expuesta políticamente) o en listas de sanciones.

Al final tendrás un script corto que guarda el resultado para cuando alguien pregunte «¿por qué aprobaron a este usuario?». Es una integración breve porque son dos llamadas y un archivo de registro, nada más.

Antes de empezar

Necesitas:

  • Python 3 con la librería requests, o cualquier cliente HTTP.
  • Un DNI de prueba. Usa 00000000 en tus ejemplos y no pegues DNI reales en repositorios ni en chats.
  • Un token por entorno (uno de sandbox y uno de producción). Guárdalos en variables de entorno y nunca en el código.

Los pasos

1. Prueba primero en el sandbox

El sandbox es un entorno de pruebas con su propio token, que se genera en la plataforma del sandbox, sandbox-hub.verifica.id. Ofrece los mismos servicios y la misma data que producción, con un tope de consultas por usuario. Sirve para probar sin ensuciar producción.

Genera el token del sandbox y guárdalo:

export VERIFICAID_TOKEN="token-del-sandbox"

El host del sandbox es https://sandbox-api.verifica.id/ y responde las mismas rutas de los pasos 3 y 4 con el token del sandbox. Úsalo mientras pruebas. Cuando todo funcione, repites el flujo con el host y el token de producción.

2. Entiende la autenticación

La API usa autenticación Bearer: envías el token en el encabezado Authorization, precedido de la palabra Bearer. Si el token es inválido o falta, recibes un 401. Esa es tu primera señal de que algo anda mal con el token.

3. Valida el DNI

Haces un POST con el DNI como campo de formulario (multipart/form-data). El código de abajo hace eso con curl.

curl --request POST \
  --url https://api.verifica.id/v2/consulta/personas \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $VERIFICAID_TOKEN" \
  --form dni=00000000

Qué ves: un JSON con status: 200 y un bloque data con dni, nombres, apellido_paterno, apellido_materno y caracter_verificacion (el dígito verificador del DNI). Si el DNI falta o tiene mal formato, el error es 400.

Tu app compara esos nombres con lo que escribió el usuario. Ese cruce es la verificación.

4. Consulta las listas de riesgo

Ahora un GET con el mismo DNI en la URL. El reporte agrupa las listas en tres bloques: pep_sanctions (PEP y sanciones internacionales), kyc_adverse_media (PEP históricos y personas de interés) y ubo_companies (relación con directorios y empresas del Estado).

curl -X GET "https://api.verifica.id/api/v1/solutions/aml-report?dni=00000000" \
  -H "Authorization: Bearer $VERIFICAID_TOKEN"

Qué ves: un JSON con data.aml_status y, dentro de data.compliance, un risk_level por bloque. Ambos toman uno de cinco valores: GREEN, YELLOW, ORANGE, RED o BLACK. También llega pdf_link, un enlace al reporte en PDF. Si olvidas el DNI, recibes un 422.

5. Decide qué hace tu app con cada color

Esta decisión es tuya y de quien responda por el cumplimiento en tu empresa, no de la API. Un punto de partida:

  • GREEN: aprobar y registrar.
  • YELLOW y ORANGE: dejar en revisión manual.
  • RED y BLACK: bloquear y escalar.

Escribe esa regla en un documento, aunque sea de una página. En una auditoría, la regla escrita pesa tanto como el resultado.

6. Guarda lo necesario para la auditoría

Por cada verificación, guarda:

  • La fecha y hora de la consulta.
  • El DNI consultado.
  • El aml_status y los risk_level de cada bloque.
  • El PDF del reporte, descargado y almacenado por ti.
  • La decisión que tomó tu app y quién la tomó, si fue manual.

El pdf_link es una URL firmada que vence a los 45 minutos. Se descarga sin el token, con un GET simple. Si solo guardas el enlace, más adelante ya no abre nada: descarga el archivo en el momento.

El script descargable junta los pasos 3, 4 y 6 en una sola ejecución: descarga el PDF a una carpeta reportes/ y añade una línea por consulta a un archivo .jsonl. Para probarlo en el sandbox, córrelo con VERIFICAID_SANDBOX=1 y el token del sandbox.

registro = {
    "consultado_en": momento.isoformat(),
    "dni": dni,
    "aml_status": datos.get("aml_status"),
    "risk_level": {k: v.get("risk_level") for k, v in datos["compliance"].items()},
    "pdf_guardado": pdf,  # ruta del PDF descargado, no el enlace que vence
}

Dónde se rompe

Esta integración alcanza para un equipo chico con volumen bajo. Deja de alcanzar cuando:

  • Ya no basta un script. Con muchas consultas al día necesitas reintentos ante errores temporales, una cola y alertas cuando algo falla.
  • Guardas en un archivo. Un .jsonl sirve para empezar. Cuando alguien de cumplimiento te pida buscar por fecha o por resultado, necesitas una base de datos.
  • Falta la identidad de la persona. Validar un DNI confirma que el número y el nombre existen. No confirma que quien tiene el celular en la mano sea el titular. Para eso hace falta una prueba de vida con biometría.
  • Cambian las reglas de decisión. Si hoy tu regla es «amarillo a revisión» y mañana la SBS o el MINCETUR piden otra cosa, esa lógica tiene que vivir en un solo lugar y no repartida por tu código.

El siguiente escalón

Cuando el volumen crezca, el paso natural es llevar estas llamadas a tu backend como servicio propio y sumar la verificación biométrica en el mismo flujo. La documentación completa está en developers.verifica.id, con los demás servicios que usan el mismo token.

Si tu duda es el precio, está en soles y se paga con créditos prepagados, así que sabes lo que gastas antes de consultar.

●  Empieza hoy

Lleva tus procesos de identificación al siguiente nivel.

Agenda una demo con nuestro equipo o empieza a integrar hoy mismo con la documentación.