API de Verificación de Identidad: Guía de Integración y Evaluación (ES)

Una API de verificación de identidad permite que una aplicación recopile o envíe evidencia de identidad y reciba resultados estructurados sobre una persona reclamada. Dependiendo del flujo de trabajo, puede validar un documento de identidad, extraer atributos, comparar un solicitante en vivo con un retrato de referencia, verificar la vivacidad, corroborar datos u orquestar varias verificaciones en una sola sesión.

La respuesta de la API es evidencia, no una decisión comercial completa. Una integración de producción también debe definir la captura confiable, la propiedad del estado del cliente, las transiciones de estado, los reintentos, la revisión, la privacidad, el mantenimiento de registros y la política que convierte los resultados técnicos en aprobación, reintento, escalada, revisión o rechazo.

Conclusiones clave

• Una API de verificación de identidad es más que un solo endpoint. El contrato real incluye captura, estados asincrónicos, evidencia, eventos, conciliación, revisión y eliminación.
• El backend es el dueño de la decisión. Una redirección del cliente o una pantalla de éxito visual no es autoritativa; el estado final debe confirmarse en el lado del servidor.
• Los resultados necesitan alcance y razones. La autenticidad del documento, la vinculación del titular, la vivacidad, la calidad y el riesgo contextual deben permanecer separables en lugar de colapsar en un booleano sin explicación.
• La fiabilidad aparece en las rutas de fallo. La idempotencia, la verificación de webhooks, la repetición de eventos, los tiempos de espera, los reintentos, el versionado y la paridad del sandbox importan tanto como el camino feliz.
• La evaluación debe usar poblaciones similares a las de producción. La cobertura, la resistencia al fraude, la finalización, los resultados falsos, la carga de revisión y la privacidad deben medirse por documento, dispositivo, geografía y segmento de usuario relevante.

¿Qué hace una API de verificación de identidad?

Una API de verificación de identidad proporciona una interfaz legible por máquina para las capacidades de prueba de identidad. Una integración típica crea un intento de verificación, dirige al solicitante a través de una experiencia de captura segura, recibe eventos de progreso o finalización, recupera la evidencia final y aplica la política de la organización que confía.

El modelo de prueba de identidad NIST SP 800-63A-4 separa tres funciones importantes:

• Resolución: distinguir a la persona reclamada dentro de la población relevante.
• Validación: determinar si la evidencia y los atributos de identidad son auténticos, precisos y aceptables.
• Verificación: establecer que el solicitante es el sujeto asociado con esa evidencia.

Una API puede realizar una, dos o las tres. Los nombres de los productos no garantizan el alcance, por lo que los requisitos deben indicar la conclusión exacta esperada de cada resultado.

Comparación entre API de verificación de identidad, API de documentos, API de KYC y OCR

Interfaz	Propósito principal	Salida útil	Lo que no prueba por sí misma
API de OCR	Convertir los píxeles del documento en texto o campos	Nombre, fecha, número, dirección extraídos	Autenticidad, posesión o riesgo del cliente
API de verificación de documentos	Validar un documento y su evidencia capturada	Verificaciones de autenticidad, caducidad, consistencia de campos, indicadores de manipulación	Que el solicitante actual sea el propietario
API de coincidencia facial	Comparar un rostro enviado con una referencia	Similitud o decisión de coincidencia en un umbral	Vivacidad, autenticidad del documento o identidad legal
API de vivacidad	Estimar la presencia en vivo en la captura biométrica	Evidencia de buena fe, ataque, reintento o puntuación	La identidad de la persona
API de verificación de identidad	Combinar la validación de la evidencia y la vinculación del solicitante	Resultados a nivel de evidencia y resultado del flujo de trabajo	KYC completo o elegibilidad comercial
API de KYC	Apoyar un flujo más amplio de diligencia debida del cliente	Identidad, selección, riesgo, flujo de trabajo y registros	Cumplimiento automático sin política de la organización

Esta distinción previene errores arquitectónicos. Por ejemplo, añadir OCR a un formulario de carga acelera la entrada de datos, pero no autentica el documento. Añadir la coincidencia facial conecta dos imágenes, pero no puede establecer si alguna de las imágenes provino de una captura confiable y en vivo.

Para el contexto de política más amplio, la selección, el riesgo y la revisión continua en torno a estas interfaces, consulte la guía del ciclo de vida de KYC. Este artículo se mantiene en el límite de confianza del desarrollador: captura, estado de la API, evidencia, eventos, conciliación y decisiones de backend.

Modelos de integración comunes

Sesión de verificación alojada

El backend de la aplicación crea una sesión y recibe una URL o token de corta duración. El usuario completa la captura en un viaje alojado por el proveedor y luego regresa a la aplicación. Este modelo puede reducir la complejidad del frontend y del dispositivo al tiempo que conserva el control del lado del servidor.

Las preguntas clave incluyen la marca, la transferencia de dominio, la accesibilidad, la localización, el soporte del navegador móvil, la caducidad de la sesión, el comportamiento de retorno y cómo se reanuda la aplicación cuando el usuario cambia de dispositivo.

SDK web o móvil incrustado

Un SDK ejecuta la experiencia de captura dentro de la aplicación. Puede proporcionar un control de interfaz más estricto y acceso a las capacidades del dispositivo, pero la calidad de la integración afecta la seguridad. El soporte de versiones, la integridad de la aplicación, los permisos de la cámara, el manejo de la cámara virtual, la política de actualización y la telemetría se convierten en parte de la revisión.

Verificación autónoma de servidor a servidor

El sistema del cliente envía datos estructurados o medios directamente a un endpoint. Esto es útil para capturas ya confiables, operaciones por lotes o módulos individuales. También traslada la responsabilidad de la integridad de la captura, el consentimiento, la calidad, la seguridad de la carga útil y la prevención de repeticiones hacia el integrador.

Flujo de trabajo orquestado

Una sesión puede ramificarse en validación de documentos, verificaciones de bases de datos, vivacidad, coincidencia facial, selección, señales de dispositivos y revisión manual. La API debe exponer el flujo de trabajo y la versión de la política para que el mismo estado pueda interpretarse más tarde.

Una secuencia de integración segura

1. Crear el intento desde el backend

El backend de confianza genera una referencia de cliente interna y llama al proveedor con el flujo de trabajo, la configuración regional y el contexto de la política requeridos. No exponga credenciales de API permanentes en el código del navegador o móvil.

Utilice una estrategia de idempotencia para las operaciones de creación. Un tiempo de espera del cliente no debe crear un segundo intento facturable ni desvincular el resultado del cliente original.

2. Emitir una transferencia de captura de corta duración

Proporcione al frontend solo el token o la URL con alcance necesario para ese intento. Vínculelo a la aplicación esperada, la referencia del cliente, el flujo de trabajo y la caducidad. Evite colocar datos personales innecesarios en URL, eventos analíticos o registros de clientes.

3. Capturar y validar evidencia

Guíe al usuario a través de la evidencia compatible y los requisitos de calidad. Separe los problemas de calidad recuperables de los ataques sospechosos. "Acercarse", "documento caducado" y "fallo de integridad de captura" no deben convertirse en un error genérico.

4. Recibir un evento autenticado

Trate los webhooks como entrada no confiable hasta que se verifiquen. Valide la firma del evento o la autenticación del mensaje, el control de la marca de tiempo o la frescura, el destino esperado, el tipo de contenido y el identificador del evento. RFC 9421 define un mecanismo general para las firmas de mensajes HTTP, aunque un proveedor puede usar un esquema de firma documentado diferente.

Almacene los identificadores de eventos y procéselos de forma idempotente. Los sistemas de entrega reintentan; los eventos duplicados son normales. No asuma el orden de llegada y no permita que un evento anterior haga retroceder a un cliente de un estado terminal.

5. Recuperar el resultado canónico

Después de un evento de finalización, obtenga el intento final de la API del proveedor. Este paso de conciliación reduce la dependencia del contenido de un solo webhook y se recupera de entregas perdidas o retrasadas.

6. Aplicar la política de la organización

Mapee la evidencia estructurada a los propios estados de decisión de la organización. El proveedor puede recomendar un resultado, pero la organización que confía conoce el producto, el historial del cliente, la base legal, el apetito de riesgo y las rutas de recuperación disponibles.

7. Registrar la transición

Persista la referencia interna del cliente, el identificador de intento del proveedor, el flujo de trabajo y la versión, la evidencia o referencias relevantes, los códigos de motivo, el historial de eventos, la versión de la política, la acción del revisor y la justificación final. Minimice los datos confidenciales copiados cuando una referencia duradera sea suficiente.

El modelo de estado que una API debe exponer

Un campo booleano verificado es demasiado pequeño para un recorrido de cliente real. Los estados útiles a menudo incluyen:

Estado	Significado	Acción típica de la aplicación
Creado	El intento existe, pero la captura no ha comenzado	Presentar o reenviar la entrega segura
En progreso	El usuario o las verificaciones asincrónicas están activas	Esperar; no conceder acceso final
Esperando entrada	Se requiere más evidencia o acción del usuario	Mostrar orientación de recuperación precisa
Reintento permitido	La captura o la calidad fallaron de forma recuperable	Iniciar un nuevo intento limitado
En revisión	Un revisor capacitado es el dueño del caso	Mantener el acceso pendiente y exponer el siguiente paso esperado
Aprobado	La evidencia requerida cumplió con el flujo de trabajo configurado	Aplicar la política de la organización y la transición de estado
Rechazado	La evidencia falló un control definido	Aplicar apelación, restricción o ruta alternativa
Caducado o abandonado	El intento terminó sin una decisión	Permitir un reinicio controlado
Error técnico	El sistema no pudo producir evidencia	Reintentar o conciliar sin tratarlo como fraude

Cada estado terminal debe tener razones estructuradas. Los códigos de máquina estables permiten la política y el análisis; los mensajes humanos localizados ayudan a los usuarios y revisores. RFC 9457 proporciona un formato estándar para detalles de problemas HTTP legibles por máquina a nivel de interfaz.

¿Qué evidencia debe contener el resultado?

Evidencia a nivel de documento

Incluya el tipo de evidencia, el país emisor, la clase de documento, la caducidad, la consistencia del campo, la calidad y los indicadores de validación relevantes para el método. Aclare si el resultado provino de una inspección óptica, datos de chip, corroboración del emisor o de la base de datos, u otra fuente.

Evidencia de vinculación del solicitante

Mantenga separadas la comparación facial, la vivacidad, la integridad de la captura y la vinculación de atributos de identidad. Registre la referencia utilizada y el umbral o versión de la decisión necesarios para una interpretación posterior sin exponer material biométrico innecesario a cada consumidor.

Evidencia de riesgo y operativa

Las señales de dispositivo, IP, velocidad, intentos repetidos o flujo de trabajo pueden guiar la escalada y la revisión. No deben cambiar silenciosamente los atributos de identidad. Conserve qué subsistema produjo cada razón.

Procedencia y versión

Los resultados pueden cambiar cuando los modelos, las plantillas de documentos, las listas de vigilancia o la política cambian. Almacene la versión del proveedor, la versión del flujo de trabajo, la hora de la decisión, las referencias de origen y si un humano revisó el caso.

Requisitos de seguridad de la API

Las API de identidad procesan datos personales y biométricos valiosos y exponen flujos de negocio que los atacantes pueden automatizar. El OWASP API Security Top 10 destaca los riesgos directamente relevantes aquí: autorización de objetos rota, autenticación rota, exposición excesiva de propiedades, consumo ilimitado de recursos, automatización de flujos sensibles, inventario de API deficiente y confianza insegura en API de terceros.

Autenticación y autorización

Utilice credenciales y aplicaciones separadas para pruebas y producción. Aplique el principio de privilegio mínimo, rotación, revocación, aislamiento del entorno y autorización a nivel de objeto. Una organización autenticada no debería poder recuperar el intento de otra organización cambiando un identificador.

Controles de carga y recursos

Valide el tipo de medio, tamaño, dimensiones, estructura y fuente esperada. Establezca tiempos de espera, límites de concurrencia, controles de velocidad y límites de intentos. Las llamadas de verificación consumen computación y pueden tener un costo por verificación, lo que convierte los endpoints ilimitados en un riesgo de denegación de servicio y de costo.

Exposición de datos

Devuelva solo los campos que necesita un consumidor. Separe los roles operativos para que el soporte, los analistas, los desarrolladores y los administradores no reciban por defecto la evidencia de identidad completa. Redacte las cargas útiles sensibles de los registros y las herramientas de observabilidad.

Controles de webhook y repetición

Autentique los eventos, conserve el cuerpo sin procesar requerido para la verificación de la firma, rechace las entregas obsoletas o mal formadas, elimine los identificadores de eventos duplicados y obtenga el estado canónico. Rote los secretos de webhook sin interrumpir la entrega en curso.

Inventario y versionado

Documente cada endpoint activo, versión, host, credencial, devolución de llamada, SDK y fecha de obsolescencia. Un endpoint de prueba en la sombra con datos de producción o un SDK antiguo sin mantenimiento puede socavar la ruta revisada.

Cómo probar una API de verificación de identidad

Pruebas de contrato y estado

Ejecute cada estado, motivo, reintento, tiempo de espera y transición terminal documentados. Verifique la paginación, el filtrado, los cuerpos de error, la compatibilidad con versiones anteriores y el comportamiento de campos desconocidos. Simule webhooks duplicados y fuera de orden.

Pruebas de evidencia

Utilice muestras permitidas y representativas de los tipos de documentos, países, escrituras, condiciones de caducidad, dispositivos, cámaras y redes en la población esperada. Realice un seguimiento por separado de la evidencia no admitida, ilegible, no coincidente, manipulada y genuina.

Pruebas de fraude

Cree un conjunto de ataques autorizados para repeticiones, evidencia impresa, documentos alterados, cámaras virtuales, emuladores, medios inyectados, identidades repetidas e intentos automatizados. Los requisitos de prueba remota del NIST distinguen la confianza del sensor de captura, el análisis de medios falsificados, los canales protegidos y la comparación biométrica porque ningún mecanismo cubre la ruta completa.

Pruebas operativas

Mida la finalización, los reintentos, el abandono, la tasa de revisión manual, el tiempo de resolución, los contactos de soporte, el retraso del webhook, la conciliación y la disponibilidad. Desglose los resultados por documento, dispositivo, red, idioma y grupo de clientes relevante.

Pruebas de calidad de decisión

No compare proveedores con un solo número de "precisión". Revise los falsos positivos y falsos negativos en el umbral previsto, los resultados específicos de ataques, los recuentos de muestras, la confianza, los casos sin respuesta y los resultados confirmados posteriores.

Pruebas de privacidad y eliminación

Verifique la configuración de retención, exportación, eliminación, registros de acceso, manejo regional, controles de subprocesadores y el comportamiento cuando una solicitud de eliminación llega durante una revisión abierta o una retención legalmente requerida.

Cómo evaluar a los proveedores

Alcance y aseguramiento

¿Qué funciones de prueba se incluyen? ¿Qué modelos de aseguramiento y pruebas independientes se aplican? ¿Qué componentes y versiones se probaron? ¿Puede el proveedor explicar qué significa un pase y qué no?

Cobertura

Pida una matriz de país y documento, no solo un total. Pruebe la evidencia que presentan sus clientes, incluidos dispositivos antiguos, múltiples escrituras, cámaras de menor calidad y documentos poco comunes pero legítimos.

Experiencia del desarrollador

Revise la consistencia de la API, la calidad de OpenAPI, el mantenimiento del SDK, los ejemplos, los escenarios del sandbox, las herramientas de webhook, la disciplina del registro de cambios, la política de migración, la página de estado y la escalada de soporte. Una muestra de cinco líneas de ruta feliz no es una guía de integración de producción.

Operaciones y explicabilidad

Inspeccione las colas de revisión, las vistas de evidencia, los permisos de roles, los registros de auditoría, los códigos de motivo, las apelaciones y las exportaciones. Confirme que los humanos pueden distinguir el fallo técnico, el reintento de calidad, el ataque probable y la falta de coincidencia de identidad.

Comercial y portabilidad

Comprenda la facturación basada en el éxito versus la basada en intentos, las tarifas de revisión, los mínimos, los límites, el almacenamiento, las opciones regionales y los términos de salida. Mantenga su referencia de cliente interna y el límite de la política portátiles para que un cambio de proveedor no requiera reescribir el estado de la cuenta.

Errores de integración comunes

Conceder acceso desde la URL de retorno

El usuario controla la ruta del navegador. Una redirección de éxito es un estado de interfaz, no una prueba. Confirme el estado final desde el backend de confianza.

Tratar cada fallo como fraude

La denegación de permisos, el tiempo de espera, la evidencia no admitida, el desenfoque y la manipulación sospechosa son diferentes. Mezclarlos crea rechazos falsos y análisis inutilizables.

Procesar webhooks exactamente una vez

Las redes no pueden prometer una entrega exactamente una vez. Diseñe para eventos de al menos una vez con deduplicación, transiciones monotónicas y recuperación canónica.

Registrar cargas útiles completas

El registro de depuración conveniente puede copiar documentos y datos biométricos en sistemas con acceso más amplio y retención más prolongada. Utilice identificadores, razones estructuradas y acceso controlado a la evidencia.

Probar solo el caso de éxito del sandbox

Los fallos de producción ocurren en reintentos, dispositivos antiguos, documentos límite, retraso de eventos, cambios de versión y revisión. Haga que los escenarios de fallo formen parte del conjunto de aceptación.

Externalizar la decisión política

El resultado de un proveedor no puede conocer todas las jurisdicciones, tipos de clientes, riesgos de productos o restricciones comerciales. Conserve la lógica de decisión y la responsabilidad de la organización.

Una lista de verificación de implementación

Antes de la producción, confirme que:

• las credenciales de la API permanecen en el lado del servidor y tienen un alcance por entorno y rol;
• las llamadas de creación son idempotentes y se asignan a referencias de cliente internas estables;
• los tokens de captura tienen una vida corta y están vinculados al intento esperado;
• cada estado y motivo tiene una acción explícita del cliente y del backend;
• las firmas, la frescura, los duplicados y el orden de los webhooks se prueban;
• la recuperación canónica concilia los eventos perdidos o retrasados;
• las salidas a nivel de evidencia permanecen separadas de la decisión final del cliente;
• los controles de tasa, carga, concurrencia e intentos resisten el abuso automatizado;
• las pruebas de documentos, dispositivos, fraude, privacidad, accesibilidad y revisión utilizan muestras similares a las de producción;
• la retención, eliminación, respuesta a incidentes, versionado y migración tienen propietarios.

Uso de Didit para la verificación de identidad

Didit proporciona Verificación de Identidad como un módulo componible y permite a los equipos añadir Detección de Vivacidad, Análisis de Dispositivo e IP y rutas condicionales a través del Orquestador de Flujos de Trabajo. El precio publicado de la Verificación de Identidad independiente es de $0.15, mientras que el paquete KYC publicado de $0.33 combina Verificación de Identidad, Vivacidad Pasiva, Coincidencia Facial y Análisis de IP.

La página de precios enumera las tarifas actuales de los módulos, y el nivel gratuito es de 500 verificaciones gratuitas por mes. Esos resultados del producto deben alimentar una política y un estado del cliente propiedad del backend en lugar de reemplazarlos.

Preguntas frecuentes

¿Qué es una API de verificación de identidad?

Es una interfaz programática para recopilar o enviar evidencia de identidad y recibir resultados estructurados sobre la validez de la evidencia y el vínculo del solicitante con una identidad reclamada.

¿Es una API de verificación de identidad lo mismo que una API de KYC?

No necesariamente. La verificación de identidad se centra en la evidencia de identidad y la vinculación del titular. Una API de KYC también puede incluir selección, riesgo de cliente, flujos de trabajo, revisión, registros y actualización continua.

¿Debería la verificación de identidad ejecutarse desde el frontend?

La interfaz de captura puede ejecutarse en el frontend, pero las credenciales permanentes, la creación de sesiones, la recuperación de resultados finales, las decisiones políticas y los cambios de estado del cliente pertenecen a un backend de confianza.

¿Por qué son necesarios los webhooks?

Muchas verificaciones y revisiones son asincrónicas. Los webhooks notifican a la aplicación los cambios, mientras que un endpoint de recuperación proporciona el estado canónico para la conciliación.

¿Cómo se deben manejar los webhooks duplicados?

Verifique cada evento, almacene su identificador, procéselo de forma idempotente, evite que los estados antiguos sobrescriban los estados terminales más nuevos y recupere el intento canónico cuando sea necesario.

¿Qué debe incluir un sandbox?

Debe reproducir el contrato de producción y proporcionar casos deterministas para el éxito, el reintento, el rechazo, la revisión, la caducidad, el error técnico, los eventos duplicados, los eventos retrasados y los códigos de motivo relevantes.

¿Puede una API hacer que una empresa cumpla con las normativas?

No. Una API puede proporcionar evidencia y resultados del flujo de trabajo. La organización sigue siendo responsable del análisis legal, la política, las decisiones del cliente, las excepciones, los registros, la privacidad y los controles continuos.

Referencias principales

• NIST SP 800-63A-4: Prueba e Inscripción de Identidad
• OWASP API Security Top 10 — 2023
• RFC 9110: Semántica HTTP
• RFC 9421: Firmas de Mensajes HTTP
• RFC 9457: Detalles del Problema para las API HTTP

Una sólida integración de verificación de identidad hace explícito cada límite de confianza: quién crea el intento, cómo se captura la evidencia, qué resultado es canónico, cómo se autentican los eventos, qué significa cada razón y qué sistema es el propietario de la decisión final del cliente.