Todos los productos
Search
Centro de documentos

ID Verification:InitializeV2

Última actualización: Oct 27, 2026

This topic describes how to call the InitializeV2 operation to initiate a verification request.

Información de la API

  • Operación de API: InitializeV2

  • Método de solicitud: HTTPS POST

  • Descripción: antes de iniciar un flujo de verificación, llame a esta operación para obtener un transactionId. Este identificador asocia todas las operaciones de API de la solicitud de verificación.

  • 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:

    Nota
    • Ventajas del acceso por red interna: una red interna es una red de comunicación privada que conecta los productos de Alibaba Cloud dentro de la misma región. Si el servidor de su aplicación está desplegado en la misma región, utilice el endpoint interno para acceder al servicio ID Verification y mejorar la seguridad y la estabilidad.

    • Optimización del acceso desde el extranjero: los entornos de red internacionales suelen ser complejos. Consulte Optimize server network latency para ajustar su integración y reducir la latencia de red y los errores en las solicitudes.

    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

    Indonesia

    • 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 llamar a las API en la plataforma OpenAPI y obtener el SDK.

Vaya a OpenAPI Explorer para depurar esta operación de API y generar el código de ejemplo del SDK.

Notas de integración

  • Un TransactionId se devuelve únicamente cuando la inicialización es exitosa. El cliente debe completar la autenticación en un plazo máximo de 30 minutos tras obtener el TransactionId o la TransactionUrl. El TransactionId es de un solo uso. Este identificador deja de ser válido inmediatamente después del intento de autenticación y no se puede reutilizar para invocar el SDK, sin importar si la autenticación fue exitosa, falló o el usuario la canceló. Para iniciar una nueva autenticación, solicite un nuevo TransactionId desde el lado del servidor.

  • La TransactionUrl se devuelve solo en el escenario del Web SDK y es válida para un único uso. No la concatene, modifique ni reutilice.

  • Debido a la latencia de red, las notificaciones de CallbackUrl pueden retrasarse. Después de recibir la notificación de finalización de la autenticación, el cliente debe llamar a la operación CheckResult del lado del servidor para obtener los detalles finales de la autenticación. No dependa exclusivamente de la notificación de callback ni de los resultados mostrados en la página.

  • Las funciones del App SDK y del Web SDK son distintas. Además, el comportamiento del Web SDK varía entre los entornos H5 móvil y PC. Para más información sobre las funciones compatibles, consulte los documentos de integración.

Request parameters

Descripción de los campos de solicitud

Método de integración

Escenario

Respuesta de inicialización

Parámetros de solicitud

App SDK

Completar la verificación en una aplicación nativa de Android o iOS

TransactionId, Protocol

Parámetros comunes + parámetros específicos de la aplicación

Web SDK

Verificar en una página H5 móvil, una página H5 integrada en una aplicación o un navegador de PC

TransactionId, TransactionUrl, Protocol

Parámetros comunes + parámetros específicos del Web SDK

Los campos se clasifican de la siguiente manera:

  • Parámetros comunes: aplicables a ambos métodos de integración.

  • Específicos de la aplicación: se utilizan para personalizar el flujo de acciones de detección de vitalidad.

  • Específicos del Web SDK: permiten controlar las redirecciones de página, el idioma, la interfaz de usuario y el comportamiento de respaldo en H5.

Parámetros de solicitud (comunes)

Nombre

Tipo

Obligatorio

Descripción

Ejemplo

ProductCode

String

Sí

El código del producto. Establezca el valor en FACE_LIVENESS_PRO.

FACE_LIVENESS_PRO

SceneCode

String

No

Identificador personalizado del escenario de autenticación. Utilice este identificador para recuperar registros desde la consola. Puede ser una cadena de 10 caracteres formada por letras, números y guiones bajos.

1234567890

MerchantBizId

String

Sí

Identificador comercial único del comerciante, que se utiliza para identificar y solucionar problemas. Es una cadena de 32 caracteres compuesta por letras y números. El lado del servidor no valida la unicidad de este identificador, por lo que el comerciante debe asegurarse de que sea único.

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

Sí

Información del entorno del cliente. Genere esta información con el SDK correspondiente. Si la crea manualmente, como mínimo debe pasar el valor correcto de deviceType.

Código de ejemplo:

{
      "deviceType": "h5"
    }

Valores válidos para deviceType:

  • Aplicación nativa de Android: android

  • Aplicación nativa de iOS: ios

  • Página H5 integrada: h5

  • Página web para PC: web

Importante

Utilice el SDK de autenticación para obtener MetaInfo. Esto proporciona información del cliente más precisa y detallada para escenarios como la emisión de URL de autenticación, la investigación de registros y las comprobaciones de seguridad. Si crea un valor estático de MetaInfo, asegúrese de que deviceType coincida con el entorno real. Un valor incorrecto provocará errores al emitir la URL de autenticación.

{
  "zimVer": "3.0.0",
  "appVersion": "1",
  "bioMetaInfo": "4.1.0:1150****,0",
  "appName": "com.aliyun.antcloudauth",
  "deviceType": "ios",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

MerchantUserId

String

Sí

Identificador de usuario personalizado, u otro identificador reconocible, como un número de celular o una dirección de correo electrónico. Se recomienda anonimizar o aplicar un hash a este campo.

123456789

CallbackUrl

String

No

URL de callback para el resultado de la autenticación. Esta URL debe comenzar con https. La plataforma envía una solicitud GET a esta URL y añade automáticamente los parámetros transactionId, passed y subcode.

La plataforma devuelve un error HTTP 400 si la URL no es accesible públicamente.

https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

CallbackToken

String

No

Token de seguridad personalizado del comerciante. Una vez configurado, este token se devuelve sin modificaciones junto con CallbackUrl para verificar la protección contra reproducción y manipulación.

NMjvQanQgplBSaEI0sL****

SecurityLevel

String

No

Nivel de seguridad. Valores válidos:

  • 01: modo normal. Recomendado para entornos de prueba con el fin de mejorar la eficiencia de las pruebas.

  • 02: modo seguro (predeterminado). Altamente recomendado para entornos de producción.

02

Model

String

No

Tipo de detección de vitalidad:

  • SILENT: silencioso (compatible con Naive SDK 1.3.6 y versiones posteriores)

  • LIVENESS: parpadeo (predeterminado)

  • PHOTINUS_LIVENESS: parpadeo y destello de color (no compatible con el modo PC)

  • TEMPLATE: acción personalizada de detección de vitalidad (no compatible con Web SDK; compatible con Naive SDK 1.3.6 y versiones posteriores)

PHOTINUS_LIVENESS

DocVideo

String

No

Indica si se captura un video de evidencia de 1 a 2 segundos durante el proceso de verificación facial. Valores válidos:

  • Y: Sí

  • N (predeterminado): No

Los archivos de video son pesados. En redes inestables, el sistema puede descartar el video para priorizar la carga de las imágenes esenciales.

Para obtener la URL del video, revise el parámetro Result.ExtFaceInfo.docVideoUrl en la respuesta de CheckResult.

N

FaceAttributeCheck

String

No

Configuración de reconocimiento facial: indica si se devuelven atributos faciales adicionales.

  • N: No (predeterminado)

  • Y: Sí, se devuelven.

El resultado se devuelve en Checkresult mediante Result.ExtFaceInfo.faceAttributeInfo.

N

ShowGuidePage

String

No

Configuración de la interfaz de usuario: mostrar página de guía:

  • 1: Mostrar (predeterminado)

  • 0: No mostrar

El modo PC no admite esta configuración.

Compatible con Native SDK versión 1.4.0 y posteriores.

1

Parámetros de solicitud (específicos de la aplicación)

A continuación se muestran los campos que admite únicamente el App SDK nativo.

Nombre

Tipo

Obligatorio

Descripción

Ejemplo

AppQualityCheck

String

No

[Configuración de escaneo facial] Indica si se habilita la detección estricta de calidad facial.

  • Y: Habilitar (predeterminado)

  • N: Deshabilitar

Compatible únicamente con Native SDK v1.2.5 y versiones posteriores. Debe integrar el módulo de detección de calidad facial.

N

TemplateConfig

String

Obligatorio bajo condición

[Configuración de escaneo facial] Pool de acciones personalizadas. Este parámetro es obligatorio cuando Model se establece en TEMPLATE.

  • Regla de configuración: separe varios códigos de acción con comas.

  • Mejor práctica: se requiere una acción de parpadeo y el número total de acciones no debe superar tres.

Tabla de referencia de códigos de acción:

  • Parpadear: 01 (obligatorio)

  • Abrir la boca: 02

  • Girar la cabeza a la izquierda: 03

  • Girar la cabeza a la derecha: 04

  • Alejar la cámara: 05

  • Acercar la cámara: 06

  • Detección de vitalidad por color: 07

Compatible con Native SDK v1.3.6 y versiones posteriores.

01,02,07

TemplateType

String

Obligatorio bajo condición

[Configuración de escaneo facial] Orden de ejecución de las acciones de detección de vitalidad en TemplateConfig.

Este parámetro es obligatorio cuando Model se establece en TEMPLATE.

  • Seq: las acciones se ejecutan de izquierda a derecha en el orden configurado en TemplateConfig.

Compatible con Native SDK v1.3.6 y versiones posteriores.

Seq

NeedMultiFaceCheck

String

No

[Configuración de escaneo facial] Determina si se bloquea la solicitud cuando el terminal detecta varias caras.

  • Y: bloquea la solicitud e indica al cliente que reintente el reconocimiento facial.

  • N: no bloquea; selecciona la cara más grande del encuadre y la envía al servidor para la verificación de seguridad. (Predeterminado)

Compatible con Native SDK versión 1.4.1 y posteriores.

Y

Parámetros de solicitud (específicos del Web SDK)

A continuación se muestran los campos que admite únicamente el Web SDK.

Campo

Tipo

Obligatorio

Descripción

Ejemplo

LanguageConfig

String

No

Cadena JSON para la configuración de idioma personalizada. Para aplicar los ajustes, convierta su configuración a una cadena JSON basándose en la plantilla proporcionada y pásela como este parámetro. Para más información, consulte Customize Web SDK languages.

Nota

Compatible únicamente con el modo de integración móvil del Web SDK.

{
  "languageContent": {****},
  "ocrResultContent": {****},
  "supportedLanguage": [****],
  "titleTranslate": {****},
}

StyleConfig

String

No

Cadena JSON para la configuración de interfaz de usuario personalizada. Para aplicar la configuración, convierta sus ajustes a una cadena JSON basándose en la plantilla proporcionada y páselos como este parámetro. Para más información, consulte Customize IDV UI styles.

Nota

Compatible únicamente con el modo de integración móvil del Web SDK.

{
  "guidepage:": {****}, 
  "ocrPage": {****},
  "ocrResultPage": [****],
  "facePage": {****},
}

ReturnUrl

String

Obligatorio bajo condición

URL de redirección posterior a la autenticación. Es opcional para el patrón de iframe integrado. Proporcione esta URL en los escenarios de redirección de página que no utilicen un iframe.

https://www.alibabacloud.com

ProcedurePriority

String

No

Indica si se muestra un método alternativo cuando ocurre un problema de compatibilidad durante la autenticación en H5 móvil.

  • url: admite el método alternativo. La página muestra la URL de autenticación. Los usuarios pueden copiar la URL y abrirla en otro navegador para continuar con la autenticación. (Predeterminado)

  • keep: no admite el método alternativo. Se devuelve el motivo del error y el flujo de autenticación finaliza. Esta opción no es compatible con PC. Recomendada para páginas web integradas en una aplicación.

url

Returned data

Diferencias en los campos devueltos

Campo

App SDK

Web SDK

Nota

RequestId / Code / Message

Sí

Sí

Información general de la respuesta.

Result.TransactionId

Sí

Sí

Es el identificador único del flujo de autenticación. Se utiliza como campo para las estadísticas de facturación y como parámetro de solicitud en la operación CheckResult. Vincule este identificador con el ID de negocio del comerciante y almacénelo únicamente del lado del servidor.

Result.Protocol

Sí

Sí

Protocolo estándar de autenticación y cifrado. Transmítalo al SDK del cliente. El Web SDK requiere este campo para el embedding en iframe.

Result.TransactionUrl

No

Sí

La URL de autenticación del Web SDK. Una vez completada la autenticación, redirige a ReturnUrl. Esta URL no se puede modificar y solo admite un acceso. Debe completar la autenticación dentro de los 30 minutos posteriores a la obtención de la URL o del TransactionId.

Nombre

Tipo

Descripción

Ejemplo

HTTP Status Code

Integer

El código de estado HTTP.

200

HTTP Body

RequestId

String

El ID de la solicitud.

130A2C10-B9EE-4D84-88E3-5384FF03****

Code

String

El código de retorno. Para obtener más información, consulte Server-side HTTP status codes.

Success

Message

String

Descripción detallada del código de retorno.

success

Result.TransactionId

String

Identificador único del flujo de autenticación. Este identificador se usa para la facturación y es obligatorio en las llamadas a la API CheckResult.

Importante
  • La API init no devuelve un TransactionId si la solicitud falla, por ejemplo, debido a un parámetro no válido.

  • Vincule el TransactionId con el ID de su proceso de negocio y almacénelo del lado del servidor. Cuando llame a la API CheckResult, recupere este identificador desde el almacenamiento de su servidor.

  • El TransactionId o el TransactionUrl tiene una vigencia de 30 minutos. Debe completar la autenticación dentro de este periodo; después, el identificador caduca.

hksb7ba1b28130d24e015d6

Result.TransactionUrl

String

La URL de verificación del Web SDK. Tras la verificación, la página redirige según el parámetro de entrada ReturnUrl.

Importante
  • No modifique TransactionUrl durante el proceso de integración. Hacerlo provocará una excepción de verificación.

  • TransactionUrl es de un solo uso. Reutilizarlo causará una excepción de verificación.

  • Después de obtener TransactionId o TransactionUrl, dispone de 30 minutos para completar la verificación antes de que el identificador o la URL caduquen.

https://www.alibabacloud.com/index.html?clientcfg=****

Result.Protocol

String

La cadena cifrada correspondiente al protocolo estándar de autenticación.

Transmitir este parámetro al SDK del cliente reduce las interacciones de red y permite el cambio dinámico de red, lo cual mejora la experiencia del usuario.

hksb7ba1b28130d24e015d*****

Ejemplos de solicitud

App SDK

Ejemplo mínimo de solicitud

{
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5ac***e6ed20c35",
  "MetaInfo": "{\"deviceType\":\"android\"}",
  "MerchantUserId": "user_hash_value"
}

Ejemplo completo de solicitud

{
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"bioMetaInfo\":\"4.1.0:1150****,0\",\"appName\":\"com.aliyun.antcloudauth\",\"deviceType\":\"android\",\"osVersion\":\"Android 12\",\"apdidToken\":\"\",\"deviceModel\":\"Pixel 6\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "TEMPLATE",
  "DocVideo": "Y",
  "FaceAttributeCheck": "Y",
  "ShowGuidePage": "1",
  "AppQualityCheck": "Y",
  "TemplateConfig": "01,02,07",
  "TemplateType": "Seq",
  "TemplateRanCount": "2"
}

Web SDK

Ejemplo mínimo de solicitud

{
  "ProductCode": "FACE_LIVENESS_PRO",
  "MerchantBizId": "e0c34a77f5a***6ed20c35",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value",
  "ReturnUrl": "https://example.com/liveness/result"
}

Ejemplo completo de solicitud

{
  "ProductCode": "FACE_LIVENESS_PRO",
  "SceneCode": "SCENE_001",
  "MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
  "MetaInfo": "{\"deviceType\":\"h5\"}",
  "MerchantUserId": "user_hash_value_12345",
  "CallbackUrl": "https://www.example.com/callback",
  "CallbackToken": "NMjvQanQgplBSaEI0sL********",
  "SecurityLevel": "02",
  "Model": "PHOTINUS_LIVENESS",
  "DocVideo": "N",
  "FaceAttributeCheck": "N",
  "LanguageConfig": "{\"languageContent\":{},\"ocrResultContent\":{},\"supportedLanguage\":[\"zh-CN\"],\"titleTranslate\":{}}",
  "StyleConfig": "{\"guidepage\":{},\"ocrPage\":{},\"ocrResultPage\":[],\"facePage\":{}}",
  "ShowGuidePage": "1",
  "ReturnUrl": "https://www.example.com/liveness/result",
  "ProcedurePriority": "url"
}