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:
NotaVentajas 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.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com
Indonesia
Endpoint público:
cloudauth-intl.ap-southeast-5.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com
China (Hong Kong)
Endpoint público:
cloudauth-intl.cn-hongkong.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.cn-hongkong.aliyuncs.com
Asia Pacific SE 3 (Kuala Lumpur)
Endpoint público:
cloudauth-intl.ap-southeast-3.aliyuncs.comEndpoint interno:
cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com
Depuración e integración en línea
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
TransactionIdse 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 elTransactionIdo laTransactionUrl. ElTransactionIdes 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 nuevoTransactionIddesde el lado del servidor.La
TransactionUrlse 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
CallbackUrlpueden retrasarse. Después de recibir la notificación de finalización de la autenticación, el cliente debe llamar a la operaciónCheckResultdel 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 |
|
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 |
|
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 Código de ejemplo: Valores válidos para
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 | |
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 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:
| 02 |
Model | String | No | Tipo de detección de vitalidad:
| 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:
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 | N |
FaceAttributeCheck | String | No | Configuración de reconocimiento facial: indica si se devuelven atributos faciales adicionales.
El resultado se devuelve en | N |
ShowGuidePage | String | No | Configuración de la interfaz de usuario: mostrar página de guía:
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.
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.
Tabla de referencia de códigos de acción:
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.
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.
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. | |
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. | |
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 |
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 |
|
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 |
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
| 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
| 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"
}