API de verificación de identidad: arquitectura para integrar documento, selfie y resultado

Integrar una API de verificación de identidad requiere separar tres responsabilidades: capturar documento y selfie, coordinar las validaciones desde un servidor y convertir sus resultados en una decisión trazable. Las credenciales deben permanecer fuera del navegador; cada solicitud necesita un estado persistente, y los errores técnicos deben distinguirse de los resultados de identidad.

Para CIO, CTO y equipos de arquitectura, esta separación permite resolver preguntas concretas: ¿qué sucede si se interrumpe la conexión?, ¿cómo evitamos procesar dos veces una solicitud?, ¿qué evidencia recibe quien revisa una excepción?

La siguiente arquitectura es una propuesta de referencia para el sistema integrador. Sus componentes y estados no representan endpoints ni funciones confirmadas de SUMA.

1. Separa captura, orquestación y decisión

Organiza la integración en cinco componentes con responsabilidades claras:

• Canal de captura: guía al usuario para obtener imágenes utilizables y muestra el avance.
• Backend de integración: autentica la sesión, valida permisos y coordina las solicitudes.
• Adaptador del proveedor: traduce los formatos documentados de la API a un modelo interno.
• Registro de operación y evidencia: conserva estados, referencias y resultados con acceso controlado.
• Motor de decisión y revisión: aplica las políticas del negocio y canaliza excepciones.

El adaptador evita que el CRM o el sistema de originación dependan directamente de cada campo del proveedor. Si cambia una versión de la API, el ajuste queda concentrado en esa frontera.

SUMA presenta públicamente VeriDocID como una solución integrable mediante APIs y SDKs, con capacidades de análisis documental, comparación facial y prueba de vida. Esto confirma el alcance general; los formatos, mecanismos de autenticación y modalidades de entrega deben validarse con la documentación técnica correspondiente. sumamexico.com

2. Mantén los secretos en servidor y vincula las capturas

La credencial que autoriza consumir el servicio debe permanecer en un entorno controlado del servidor. No la incluyas en JavaScript público, aplicaciones distribuidas, repositorios ni URLs.

Utiliza un gestor de secretos, permisos mínimos y procedimientos de rotación y revocación. OWASP recomienda administrar centralmente el ciclo de vida de las credenciales y controlar quién puede consultarlas o modificarlas. OWASP Cheat Sheet Series

Si la modalidad contratada permite captura directa mediante SDK, confirma si utiliza una autorización temporal y limitada. Esa posibilidad no justifica entregar al dispositivo la credencial principal.

Desde el inicio, asigna un identificador interno a la operación. Vincula documento, selfie y resultados con ese identificador, el usuario autorizado y el intento de captura. El servidor debe comprobar la relación: recibir un identificador enviado por el navegador no demuestra que la persona tenga permiso para modificar ese expediente.

Define también formatos admitidos, tamaños máximos y caducidad de las capturas. Una imagen nueva debe generar una versión identificable, sin sustituir silenciosamente la evidencia utilizada en una decisión anterior.

3. Modela estados y trata los reintentos como decisiones

Una integración operable necesita más información que “aprobado” o “rechazado”. Conviene separar el avance técnico, el resultado de las verificaciones y la decisión comercial.

Esta tabla propone estados internos; no describe códigos de SUMA:

Un timeout no demuestra que la operación haya fallado: el proveedor pudo procesarla aunque la respuesta no llegara. Repetirla inmediatamente puede duplicar trabajo y, según el esquema comercial, consumo.

RFC 9110 desaconseja reintentar automáticamente solicitudes no idempotentes salvo que exista una forma de saber que repetirlas es seguro o que la operación original no se aplicó. rfc-editor.org

Por eso, confirma si la API ofrece idempotencia o consulta de operaciones. Un identificador interno ayuda a controlar duplicados locales, pero no garantiza deduplicación del lado del proveedor.

Para fallas transitorias, establece reintentos limitados, espera progresiva y un tiempo máximo. Los errores de credenciales requieren atención técnica; los datos inválidos requieren corrección. Ninguno debe convertirse automáticamente en “identidad rechazada”.

4. Conserva evidencia útil y habilita revisión humana

Documento, comparación facial y prueba de vida responden preguntas distintas. Extraer texto no demuestra autenticidad documental; comparar rostros no sustituye la evaluación de presencia. NIST SP 800-63A-4 distingue la validación de evidencia de identidad y la verificación de su vínculo con la persona. Aquí se utiliza como referencia técnica, no como obligación mexicana ni certificación de SUMA. pages.nist.gov

En el modelo interno, conserva por separado los resultados disponibles, sus motivos y las referencias de origen. Evita resumirlos prematuramente en un indicador único que impida explicar qué ocurrió.

Para reconstruir una decisión, registra:

• Identificador de operación e intento.
• Fechas de captura, envío, respuesta y resolución.
• Resultado recibido y referencia del proveedor, cuando exista.
• Versión de las reglas aplicadas.
• Responsable y motivo de cualquier intervención manual.

Mantén las imágenes y respuestas sensibles fuera de los logs generales. Define acceso, conservación y eliminación según las finalidades del proceso y los requisitos que correspondan.

Una señal insuficiente debe conducir a recaptura, verificación adicional o revisión, según la política. No prueba por sí sola que una persona esté cometiendo fraude. La revisión humana necesita criterios explícitos y evidencia pertinente, no solamente un botón para cambiar el resultado.

5. Lleva la arquitectura a una operación B2B

Ejemplo expresamente hipotético: una empresa de arrendamiento recibe solicitudes digitales. Su portal captura identificación y selfie; el backend crea una operación y coordina las verificaciones.

Durante un intento, la conexión se interrumpe después del envío. La solicitud permanece en “resultado desconocido”. El sistema busca conciliar mediante los mecanismos disponibles y documentados; si no puede, la canaliza a soporte operativo. No rechaza al solicitante ni inicia otra verificación sin control.

En otro caso, la imagen resulta insuficiente. El portal solicita una nueva captura y conserva la relación entre intentos. Si después aparecen señales que requieren evaluación, un analista recibe el expediente y registra su resolución.

Una vez resuelta la identidad, el proceso puede continuar hacia firma electrónica, como servicio complementario. La aprobación de identidad no sustituye las reglas comerciales del arrendamiento ni garantiza por sí misma efectos jurídicos.

Antes de producción, prueba desconexiones, respuestas duplicadas, credenciales vencidas y cambios de formato. Si existen webhooks, valida su autenticidad y controla eventos repetidos; si no están documentados, no diseñes el flujo suponiendo que existen.

Monitorea tiempos por etapa, operaciones pendientes, errores técnicos, recapturas y carga de revisión. Estos indicadores permiten localizar problemas sin confundir disponibilidad de la API con calidad de la verificación.

6. Preguntas frecuentes de integración

¿Puedo consumir la API directamente desde el navegador?

Únicamente mediante una modalidad expresamente diseñada y documentada para ello. La credencial principal debe permanecer en servidor; cualquier autorización del cliente necesita alcance y duración limitados.

¿Una respuesta HTTP exitosa significa identidad aprobada?

No. Debes interpretar el contenido conforme al contrato de la API y después aplicar las reglas del negocio. Recepción técnica, resultado de verificación y aprobación son conceptos separados.

¿Qué hago si el proveedor no ofrece idempotencia?

Controla concurrencia y duplicados en tu backend. Ante una respuesta perdida, utiliza la conciliación disponible o intervención operativa; no prometas procesamiento único de extremo a extremo.

¿Qué debo confirmar con SUMA antes de desarrollar?

Versión documental, autenticación, captura soportada, estructura de resultados, errores, límites, consulta de operaciones y condiciones de conservación. Confirma también soporte y condiciones comerciales, sin asumir SLA ni capacidades no documentadas.

Agenda una sesión técnica para revisar tu flujo de captura, manejo de excepciones y conexión con los sistemas de tu empresa.