Todos los productos
Search
Centro de documentos

ID Verification:ID Verification integration guide

Última actualización: Oct 27, 2026

ID Verification ofrece varios modos de integración. Cada modo admite un flujo de trabajo distinto según su caso de uso.

Modos de integración

Alibaba Cloud ofrece los cuatro modos de integración que se muestran a continuación. Elija el modo que mejor se adapte a su caso de uso:

Modo Native App SDK: Proporciona un SDK del lado del cliente y las API correspondientes del lado del servidor. Integre el SDK en su aplicación nativa para que los usuarios finales accedan directamente a los servicios de Alibaba Cloud. Para consultar los enlaces de descarga del SDK, consulte Client-side SDK Release Notes.

Modo Web SDK: Ofrece un SDK web y las API del lado del servidor correspondientes para integrar aplicaciones web. Los usuarios finales acceden al servicio mediante navegadores de escritorio o celulares. Debido a las diferencias entre los entornos de los navegadores, el acceso desde la PC solo es compatible con soluciones específicas por ahora. Para más detalles, consulte la guía de integración de cada solución.

Modo WebView Embedded App: Proporciona un SDK web y las API del lado del servidor correspondientes para integrarse con su aplicación nativa mediante un navegador integrado (WebView). Para garantizar la compatibilidad con el SDK H5 móvil, configure los permisos obligatorios del WebView en su aplicación, como el acceso a la cámara y la reproducción automática de video.

Modo Server-Side-Only (API): Ofrece API del lado del servidor para invocar los servicios directamente desde su servidor de aplicaciones. Este método es adecuado para escenarios de integración de backend que no requieren interacción del lado del cliente.

Pasos de integración del SDK

  1. Activar el servicio: Antes de empezar, asegúrese de haber activado el servicio ID Verification. Para más detalles, consulte Activate ID Verification.

  2. Primeros pasos: Después de seleccionar una solución de producto, consulte los documentos de la Development Guide correspondiente para completar el registro del servicio.

    1. Inicialización del lado del servidor: Invoque la API de inicialización del lado del servidor Initialize para obtener el TransactionId (el identificador único del servicio ID Verification, que se utiliza para vincular las API en una solicitud de autenticación).

      Nota

      En la integración con el SDK web, este paso también devuelve una URL de verificación para el acceso del lado del cliente.

    2. Integración del lado del cliente: Integre el SDK con su aplicación cliente.

    3. Obtener el resultado de la verificación: Invoque la API de consulta del lado del servidor CheckResult para recuperar el estado y la información de verificación correspondientes.

Diagrama de secuencia de integración de la aplicación

El flujo de trabajo de integración de la aplicación incluye las cuatro fases siguientes:

  1. Obtener MetaInfo: El SDK del lado del cliente recopila la información del entorno del dispositivo.

  2. Inicialización del lado del servidor: El servidor de aplicaciones invoca una API para obtener el TransactionId.

  3. Verificación del lado del cliente: El SDK utiliza el TransactionId para ejecutar la verificación del usuario.

  4. Verificación del resultado: El servidor de aplicaciones recupera el resultado final de la verificación.

Nota

MetaInfo admite valores fijos proporcionados por la lógica de negocio, por lo que la fase 1 es un paso opcional. Si no necesita integrar el SDK del cliente para obtener MetaInfo, omita la fase 1 y continúe directamente con la fase 2.

Se recomienda integrar la fase 1. La información de MetaInfo obtenida dinámicamente mediante el SDK contiene datos más precisos sobre el entorno del dispositivo. Esto ayuda a que el servidor entregue una URL de verificación adecuada y proporciona contexto completo del cliente durante la resolución de problemas, lo cual mejora la eficiencia al solucionar incidencias.

image

Paso

Interacción

Descripción

1

Usuario final → Aplicación del comerciante

El usuario final inicia el flujo de negocio desde la aplicación del comerciante.

2

Aplicación del comerciante → SDK de verificación

La aplicación del comerciante invoca la API del SDK para obtener la información del entorno del dispositivo (MetaInfo).

3

SDK de verificación → Aplicación del comerciante

El SDK devuelve la cadena MetaInfo.

4

Aplicación del comerciante → Servidor de aplicaciones

La aplicación del comerciante envía una solicitud de verificación con MetaInfo al servidor de aplicaciones.

5

Servidor de aplicaciones → Alibaba Cloud

El servidor de aplicaciones invoca la API Initialize y pasa MetaInfo como parámetro.

6

Alibaba Cloud → Servidor de aplicaciones

Alibaba Cloud devuelve el TransactionId, que es el identificador único de este flujo de verificación.

7

Servidor de aplicaciones → Aplicación del comerciante

El servidor de aplicaciones envía el TransactionId a la aplicación del comerciante.

8

Aplicación del comerciante → SDK de verificación

La aplicación del comerciante inicia el flujo de verificación del SDK con el TransactionId.

Importante

Un TransactionId es una credencial única para un solo flujo de autenticación. Debe usar un TransactionId nuevo en cada invocación.

El TransactionId caduca después de un solo uso, sin importar si el flujo de autenticación se completa con éxito, falla o se cancela. No reutilice un TransactionId caducado para invocar el SDK. Para iniciar una nueva autenticación, el cliente debe solicitar un TransactionId nuevo al servidor.

Reutilizar el mismo TransactionId para invocar el SDK puede provocar los siguientes problemas:

  • Estados anómalos y cierres inesperados: El SDK no distingue entre un flujo nuevo y uno reanudado. Esto puede causar fallos visuales en la interfaz, bloqueos del proceso o cierres inesperados del SDK.

  • Bloqueos por control de riesgos: La política de seguridad subyacente podría detectar la reutilización como un ataque de repetición. Esta acción bloquea la autenticación y devuelve un error.

  • Fallas en la resolución de problemas: El mismo identificador queda asociado a varios registros de operación desconectados. Esto imposibilita encontrar la causa raíz si un cliente reporta un problema.

9

SDK de verificación → Alibaba Cloud

El SDK recopila y carga los materiales de verificación del usuario (como imágenes faciales y documentos de identidad) en el servidor de Alibaba Cloud.

10

Alibaba Cloud → SDK de verificación

El servidor de Alibaba Cloud completa la verificación y devuelve el resultado.

11

SDK de verificación → Aplicación del comerciante

El SDK notifica el estado de la verificación a la aplicación del comerciante mediante una devolución de llamada.

12

Aplicación del comerciante → Servidor de aplicaciones

La aplicación del comerciante solicita el resultado final de la verificación al servidor de aplicaciones.

13

Servidor de aplicaciones → Alibaba Cloud

El servidor de aplicaciones invoca la API CheckResult para consultar el resultado en el servidor de Alibaba Cloud.

14

Alibaba Cloud → Servidor de aplicaciones

Alibaba Cloud devuelve el resultado completo de la verificación y los materiales correspondientes.

15

Servidor de aplicaciones → Aplicación del comerciante

El servidor de aplicaciones procesa la información de verificación y envía los datos no confidenciales de vuelta a la aplicación del comerciante.

16

Aplicación del comerciante → Usuario final

La aplicación del comerciante notifica al usuario final que el flujo de verificación ha terminado.

Descripción de las API

API

Cuándo invocarla

Descripción

Initialize

Fase de inicialización del lado del servidor

Devuelve el TransactionId, que es el identificador único del flujo de verificación.

CheckResult

Fase de finalización de la verificación

Devuelve el estado final de la verificación y los materiales correspondientes.

Diagrama de secuencia de integración web/H5

La integración H5 es compatible con navegadores de PC y celulares. La diferencia principal respecto a la integración con aplicaciones es que la inicialización devuelve un TransactionUrl (un enlace a la página de autenticación), el cual admite dos métodos: redirección de página o inserción en un iframe.

El flujo de integración web/H5 consta de cuatro etapas principales:

  1. Obtener MetaInfo: El SDK web recopila el contexto del entorno del dispositivo del usuario final desde la página H5 del comerciante.

  2. Inicialización del lado del servidor: El servidor de aplicaciones invoca la API de inicialización de Alibaba Cloud para obtener el TransactionId que identifica esta autenticación y el enlace de la página de autenticación (TransactionUrl) para la redirección o inserción en el frontend.

  3. Autenticación del lado del cliente: La página H5 del comerciante carga el enlace de autenticación mediante una redirección de página o un iframe, y guía al usuario a través del flujo de autenticación.

  4. Verificación del resultado: El servidor de aplicaciones invoca la API de consulta de resultados para recuperar el estado final de la autenticación y los materiales.

Nota

MetaInfo admite valores fijos proporcionados por la lógica de negocio, por lo que la fase 1 es un paso opcional. Si no necesita integrar el SDK del cliente para obtener MetaInfo, omita la fase 1 y continúe directamente con la fase 2.

Se recomienda integrar la fase 1. La información de MetaInfo obtenida dinámicamente mediante el SDK contiene datos más precisos sobre el entorno del dispositivo. Esto ayuda a que el servidor entregue una URL de verificación adecuada y proporciona contexto completo del cliente durante la resolución de problemas, lo cual mejora la eficiencia al solucionar incidencias.

image

Paso

Interacción

Descripción

1

Usuario final → Página H5 del comerciante

El usuario final inicia el flujo de verificación desde una página H5 en la PC o el celular.

2

Página H5 del comerciante → SDK de verificación

La página H5 del comerciante invoca el SDK web para obtener la información del entorno del dispositivo (MetaInfo).

3

SDK de verificación → Página H5 del comerciante

El SDK devuelve la cadena MetaInfo.

4

Página H5 del comerciante → Servidor de aplicaciones

La página H5 del comerciante envía MetaInfo al servidor de aplicaciones.

5

Servidor de aplicaciones → Alibaba Cloud

El servidor de aplicaciones invoca la API Initialize y pasa MetaInfo como parámetro.

6

Alibaba Cloud → Servidor de aplicaciones

Alibaba Cloud devuelve el TransactionId (el identificador único del flujo de verificación) y el TransactionUrl. Si utiliza la inserción en un iframe, también se devuelve el Protocol.

7

Servidor de aplicaciones → Página H5 del comerciante

El servidor de aplicaciones envía el TransactionId y el TransactionUrl a la página H5 del comerciante.

8

Página H5 del comerciante → SDK de verificación

La página H5 del comerciante inicia el flujo de verificación del SDK con el TransactionId (admite redirección de página o inserción en un iframe).

Importante

Un TransactionId es una credencial única para un solo flujo de autenticación. Debe usar un TransactionId nuevo en cada invocación.

El TransactionId caduca después de un solo uso, sin importar si el flujo de autenticación se completa con éxito, falla o se cancela. No reutilice un TransactionId caducado para invocar el SDK. Para iniciar una nueva autenticación, el cliente debe solicitar un TransactionId nuevo al servidor.

Reutilizar el mismo TransactionId para invocar el SDK puede provocar los siguientes problemas:

  • Estados anómalos y cierres inesperados: El SDK no distingue entre un flujo nuevo y uno reanudado. Esto puede causar fallos visuales en la interfaz, bloqueos del proceso o cierres inesperados del SDK.

  • Bloqueos por control de riesgos: La política de seguridad subyacente podría detectar la reutilización como un ataque de repetición. Esta acción bloquea la autenticación y devuelve un error.

  • Fallas en la resolución de problemas: El mismo identificador queda asociado a varios registros de operación desconectados. Esto imposibilita encontrar la causa raíz si un cliente reporta un problema.

9

SDK de verificación → Alibaba Cloud

El SDK recopila y carga los materiales de verificación del usuario.

10

Alibaba Cloud → SDK de verificación

Alibaba Cloud completa la verificación y devuelve el resultado.

11

SDK de verificación → Página H5 del comerciante

El SDK notifica el estado de la verificación a la página H5 del comerciante mediante una devolución de llamada.

12

Página H5 del comerciante → Servidor de aplicaciones

La página H5 del comerciante solicita el resultado final de la verificación al servidor de aplicaciones.

13

Servidor de aplicaciones → Alibaba Cloud

El servidor de aplicaciones invoca la API CheckResult para consultar el resultado de la verificación.

14

Alibaba Cloud → Servidor de aplicaciones

Alibaba Cloud devuelve el resultado completo de la verificación y los materiales correspondientes.

15

Servidor de aplicaciones → Página H5 del comerciante

El servidor de aplicaciones procesa la información de verificación y envía los datos no confidenciales de vuelta a la página H5 del comerciante.

Descripción de las API

API

Cuándo invocarla

Descripción

Initialize

Fase de inicialización del lado del servidor

  • Devuelve el TransactionId, que es el identificador único del flujo de verificación.

  • Devuelve el TransactionUrl y el Protocol opcional para admitir la redirección de página o la inserción en un iframe.

CheckResult

Fase de finalización de la verificación

Devuelve el estado final de la verificación y los materiales correspondientes.

Integración en aplicaciones frente a integración web

Elemento

Integración en aplicaciones

Integración web

Valor devuelto por la inicialización

TransactionId

TransactionId + TransactionUrl + Protocol (opcional)

Método de integración del SDK

SDK nativo (iOS/Android)

SDK web (JS)

Host de la página de verificación

Página de la aplicación nativa

Página web H5 para PC/celular

Método de visualización de la página

Renderizado dentro del SDK

Redirección de página o inserción en un iframe

API principales del lado del servidor

Initialize / CheckResult

Initialize / CheckResult

Integración exclusiva por API

  1. Active el servicio ID Verification. Para más detalles, consulte Activate ID Verification.

  2. Integre una solución siguiendo la documentación de la API del producto correspondiente. El modo exclusivo del lado del servidor es compatible con las siguientes soluciones:

Conceptos básicos de las API

  • Método de solicitud: HTTPS POST

  • Límite de QPS: Cada API tiene su propio límite de QPS. Para más información, consulte QPS limits of ID Verification server-side APIs.

  • Endpoints del servicio:

    Nota

    Ventajas del acceso por red interna: Una red interna es una red de comunicación privada entre los productos de Alibaba Cloud ubicados en la misma región. Si su servidor de aplicaciones está desplegado en la misma región, utilice el endpoint de red interna para lograr una conectividad más segura y estable.

    Asia Pacific SE 1 (Singapore)

    • Endpoint público: cloudauth-intl.ap-southeast-1.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

    Asia Pacific SE 5 (Jakarta)

    • Endpoint público: cloudauth-intl.ap-southeast-5.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

    China (Hong Kong)

    • Endpoint público: cloudauth-intl.cn-hongkong.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    Asia Pacific SE 3 (Kuala Lumpur)

    • Endpoint público: cloudauth-intl.ap-southeast-3.aliyuncs.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

Depuración e integración en línea

Nota

Antes de depurar e integrar, lea el documento Use OpenAPI para aprender a invocar las API en la plataforma OpenAPI y obtener el SDK.

Ejecute y depure las API directamente en OpenAPI Explorer, y genere código de ejemplo del SDK.