Información de la API
Operación de la API: InitializeV2
Método de solicitud: HTTPS POST
Descripción: Llame a esta operación antes de iniciar una sesión de verificación para obtener un
transactionId. Este identificador vincula todas las llamadas a la API dentro de dicha sesió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 del servicio:
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 su servidor de aplicaciones se despliega en la misma región, utilice el endpoint interno para acceder al servicio ID Verification y así mejorar la seguridad y la estabilidad.
Optimización del acceso desde el extranjero: los entornos de red internacionales pueden 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.
Puede ejecutar directamente esta API en OpenAPI Explorer para depurarla, así como generar un ejemplo de código del SDK.
Notas de integración
Se devuelve un
TransactionIdúnicamente cuando la inicialización es exitosa. El cliente debe completar la autenticación en un plazo máximo de 30 minutos tras recibir elTransactionIdo laTransactionUrl.La
TransactionUrlse devuelve solo en escenarios con Web SDK y es una URL de un único uso. No la concatene, modifique ni reutilice.Debido a la latencia de red, la notificación de
CallbackUrlpuede retrasarse. Una vez que reciba la notificación de finalización, el cliente debe llamar a la APICheckResultdel servidor para obtener el resultado definitivo de la autenticación. No dependa exclusivamente de la notificación de callback ni de los resultados mostrados en la página.App SDK y Web SDK difieren en sus funcionalidades. Además, el comportamiento de Web SDK varía entre los entornos H5 para celular y escritorio. Para conocer qué funciones admite cada uno, consulte la documentación de integración.
La lógica del valor enumerado
AutoRegistrationes inversa a la de un valor booleano estándar:0habilita el registro automático y1lo deshabilita. Preste especial atención a esta diferencia durante la integración para evitar errores de configuración.El identificador de usuario del comerciante (
MerchantUserId) debe mantener una correspondencia estable con los usuarios de su negocio. En los escenarios de registro facial, este identificador también debe ser único; si está duplicado, el registro facial fallará.Si el parámetro
UpdateFaceIfUserExistsse establece enYy ya existe un usuario con elMerchantUserIdespecificado, el sistema sobrescribe los datos faciales existentes de ese usuario con la nueva imagen para completar el registro y la inscripción.
Request parameters
Campos de la solicitud
La operación InitializeV2 es el endpoint de inicialización unificado del servidor para App SDK y Web SDK. El código de producto se establece en FACE_IDU. Ambos SDK comparten los tres modos de verificación, los parámetros de grupo facial, los parámetros de rostro objetivo y los parámetros de registro automático asociados con FACE_IDU. Las principales diferencias radican en las configuraciones del cliente para la detección de vida, los ajustes de la página web y los campos de respuesta.
|
Método de integración |
Caso de uso |
Respuesta de la API |
Parámetros |
|
App SDK |
Para verificar usuarios en una aplicación nativa de Android o iOS. |
|
Parámetros comunes + parámetros específicos de App SDK |
|
Web SDK |
Para verificar usuarios 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 de Web SDK |
Los parámetros se clasifican de la siguiente manera:
Parámetros comunes: se utilizan en ambos métodos de integración.
Parámetros específicos de App SDK: controlan el flujo de trabajo de detección de vida.
Parámetros específicos de Web SDK: controlan las redirecciones de página, el idioma, la interfaz de usuario y la alternativa H5.
Tres modos de verificación
|
Modo de verificación |
Valor de VerifyModel |
Lógica principal |
Caso de uso |
Parámetros clave |
Condición de registro automático |
|
Modo de validación (predeterminado) |
|
Detección de vida + validación 1:1 |
Inicios de sesión, recuperación de cuentas y confirmación de acciones sensibles. |
|
No aplica |
|
Modo de búsqueda |
|
Detección de vida + búsqueda 1:N |
Prevención de registros duplicados para nuevos usuarios y aplicación de una cuenta por persona. |
|
La detección de vida se aprueba y la búsqueda 1:N no encuentra coincidencias. |
|
Modo integral |
|
Detección de vida + validación 1:1 + búsqueda 1:N |
Registro de nuevos usuarios que requiere tanto la confirmación de identidad como la comprobación de duplicados. |
Requiere todos los parámetros clave del modo de validación (valor |
La detección de vida se aprueba, la validación 1:1 se aprueba y la búsqueda 1:N no encuentra coincidencias. |
Parámetros comunes
Parámetro | Tipo | Obligatorio | Descripción | Ejemplo |
ProductCode | String | Sí | El código del producto. Establezca el valor en FACE_IDU. | FACE_IDU |
SceneCode | String | No | Un identificador personalizado para el 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í | Un identificador comercial único para el comerciante, que sirve para identificar y solucionar problemas. Es una cadena de 32 caracteres alfanuméricos. El servidor no valida si este identificador es único, por lo que el comerciante debe asegurarse de que lo sea. | 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í | Un 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 | La URL de callback para el resultado de la autenticación. 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 | Un token de seguridad personalizado para el comerciante. Una vez configurado, este token se devuelve sin cambios junto con CallbackUrl para la verificación contra reproducción y manipulación. | NMjvQanQgplBSaEI0sL**** |
SecurityLevel | String | No | El nivel de seguridad. Valores válidos:
| 02 |
Model | String | No | Tipo de detección de vida:
| 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 grandes. En redes inestables, el sistema puede descartar el video para priorizar la carga de las imágenes esenciales. Para obtener la URL del video, consulte 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 |
VerifyModel | String | No | [Configuración del producto] El modo de verificación:
| 0 |
TargetFacePicture | String | Obligatorio cuando | [Configuración del producto - validación 1:1] La cadena codificada en Base64 de la imagen facial objetivo confiable para la comparación 1:1. | base64 |
TargetFacePictureUrl | String | [Configuración del producto - validación 1:1] La URL de la imagen facial. Debe ser un enlace HTTP o HTTPS accesible públicamente. | https://***face1.jpeg | |
TargetFacePictureFile | InputStream | [Configuración del producto - validación 1:1] El flujo de archivo de la imagen facial. | Consulte Special Scenarios: Configuring the Advance Interface for File Uploads. | |
FaceGroupCodes | String | Obligatorio cuando | [Configuración del producto - búsqueda 1:N] Los códigos de los grupos faciales para la búsqueda 1:N. Obtenga el código al crear un grupo facial en la consola de ID Verification. Especifique hasta 10 grupos faciales a la vez y sepárelos con comas (,). | sgxta,suk3j |
ReturnFaces | String | Opcional cuando | [Configuración del producto - búsqueda 1:N] La cantidad de rostros coincidentes que se devuelven cuando varios superan el umbral de coincidencia. Valor predeterminado: 1. Máximo: 5. | 1 |
AutoRegistration | String | Opcional cuando | [Configuración del producto - búsqueda 1:N] Indica si se registra automáticamente el rostro en un grupo facial después de una verificación exitosa:
| 0 |
FaceRegisterGroupCode | String | Obligatorio cuando | [Configuración del producto - búsqueda 1:N] El código del grupo facial de destino para el registro automático. | sg*xta |
UpdateFaceIfUserExists | String | Opcional cuando | [Configuración de la solución del producto - búsqueda 1:N] Si el
| N |
ShowGuidePage | String | No | Configuración de la interfaz: mostrar la 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 App SDK
A continuación se muestran los parámetros compatibles únicamente con App SDK nativo.
Parámetro | 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 solo con Native SDK v1.2.5 y versiones posteriores. Se debe integrar el módulo de detección de calidad facial. | N |
TemplateConfig | String | Condicional | [Configuración de escaneo facial] El 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 | Condicional | [Configuración de escaneo facial] El orden de ejecución de las acciones de detección de vida 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 dispositivo detecta varios rostros.
| Y |
Parámetros de Web SDK
A continuación se muestran los parámetros compatibles únicamente con Web SDK.
Parámetro | Tipo | Obligatorio | Descripción | Ejemplo |
LanguageConfig | String | No | Una cadena JSON para la configuración de idioma personalizada. Para aplicar los ajustes, convierta su configuración a una cadena JSON con base en la plantilla proporcionada y pásela como este parámetro. Para obtener más información, consulte Customize Web SDK languages. Nota Compatible solo con el modo de integración móvil de Web SDK. | |
StyleConfig | String | No | Una cadena JSON para la configuración personalizada de la interfaz de usuario. Para aplicarla, convierta sus ajustes a una cadena JSON con base en la plantilla proporcionada y pásela como este parámetro. Para obtener más información, consulte Customize IDV UI styles. Nota Compatible solo con el modo de integración móvil de Web SDK. | |
ReturnUrl | String | Condicional | La URL de redirección posterior a la autenticación. Es opcional para el patrón integrado con iframe. Proporcione esta URL en los escenarios de redirección de página que no usen 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 H5 móvil.
| url |
Response parameters
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 integrar el iframe mediante embedding. |
|
Result.TransactionUrl |
No |
Sí |
La URL de autenticación del Web SDK. Una vez completada la autenticación, redirige a |
Parámetro | Tipo | Descripción | Ejemplo | |
Código de estado HTTP | Integer | El código de estado HTTP. | 200 | |
Cuerpo HTTP | RequestId | String | El ID de la solicitud. | 130A2C10-B9EE-4D84-88E3-5384FF03**** |
Code | String | El código de retorno. Para más información, consulte Server-side HTTP status codes. | Success | |
Message | String | Una 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 para el Web SDK. Cuando finaliza la verificación, el sistema redirige al usuario a ReturnUrl, que usted proporcionó en la solicitud. 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
Modo de verificación 1:1 del App SDK
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 1, el sistema ejecuta únicamente la detección de vitalidad y una comparación 1:1 contra la cara objetivo. No realiza búsquedas en la biblioteca de caras ni activa el registro automático.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"android\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "1",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "login_check_01",
"MerchantBizId": "biz_20230805123456789",
"MetaInfo": "{\"deviceType\":\"android\",\"osVersion\":\"Android 12\",\"deviceModel\":\"Pixel 6\"}",
"MerchantUserId": "user_hash_value_123",
"CallbackUrl": "https://www.example.com/callback",
"SecurityLevel": "02",
"Model": "PHOTINUS_LIVENESS",
"DocVideo": "N",
"VerifyModel": "1",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"AppQualityCheck": "Y",
"ShowGuidePage": "1"
}
Modo de verificación 1:1 del Web SDK
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 1, el sistema ejecuta únicamente la detección de vitalidad y una comparación 1:1 contra la cara objetivo. No realiza búsquedas en la biblioteca de caras ni activa el registro automático.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "1",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"ReturnUrl": "https://example.com/face-idu/result"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "web_login_01",
"MerchantBizId": "biz_20230805987654321",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value_456",
"CallbackUrl": "https://www.example.com/callback",
"ReturnUrl": "https://example.com/face-idu/result",
"SecurityLevel": "02",
"Model": "LIVENESS",
"VerifyModel": "1",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"ShowGuidePage": "1",
"ProcedurePriority": "url"
}
Modo de búsqueda 1:N del App SDK
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 0, el sistema ejecuta la detección de vitalidad y una búsqueda 1:N dentro de la biblioteca de caras especificada. En una solicitud mínima, el registro automático está deshabilitado de forma predeterminada. Por esta razón, se omiten los parámetros AutoRegistration y FaceRegisterGroupCode.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"android\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "0",
"FaceGroupCodes": "sg*****xta"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "new_user_reg_01",
"MerchantBizId": "biz_20230805abcdefg",
"MetaInfo": "{\"deviceType\":\"android\",\"osVersion\":\"Android 11\"}",
"MerchantUserId": "user_hash_value_789",
"SecurityLevel": "02",
"Model": "SILENT",
"VerifyModel": "0",
"FaceGroupCodes": "sg*****xta,sg*****uk3j",
"ReturnFaces": "3",
"AutoRegistration": "0",
"FaceRegisterGroupCode": "sg*****xta",
"UpdateFaceIfUserExists": "N",
"AppQualityCheck": "Y",
"ShowGuidePage": "1"
}
Modo de búsqueda 1:N del Web SDK
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 0, el sistema ejecuta la detección de vitalidad y una búsqueda 1:N dentro de la biblioteca de caras especificada. En una solicitud mínima, el registro automático está deshabilitado de forma predeterminada. Por esta razón, se omiten los parámetros AutoRegistration y FaceRegisterGroupCode.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "0",
"FaceGroupCodes": "sg*****xta",
"ReturnUrl": "https://example.com/face-idu/result"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "web_reg_01",
"MerchantBizId": "biz_20230805hijklmn",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value_000",
"ReturnUrl": "https://example.com/face-idu/result",
"SecurityLevel": "02",
"Model": "LIVENESS",
"VerifyModel": "0",
"FaceGroupCodes": "sg*****xta",
"AutoRegistration": "0",
"FaceRegisterGroupCode": "sg*****xta",
"ShowGuidePage": "1"
}
Modo integral del App SDK (1:1 y 1:N)
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 2, el sistema ejecuta tanto la comparación 1:1 contra la cara objetivo como la búsqueda 1:N dentro de la biblioteca de caras especificada. En una solicitud mínima, el registro automático está deshabilitado de forma predeterminada.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"ios\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "2",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"FaceGroupCodes": "sg*****xta"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "app_comprehensive_01",
"MerchantBizId": "biz_20230805opqrst",
"MetaInfo": "{\"deviceType\":\"ios\",\"osVersion\":\"iOS 15.0\",\"deviceModel\":\"iPhone 13\"}",
"MerchantUserId": "user_hash_value_111",
"SecurityLevel": "02",
"Model": "PHOTINUS_LIVENESS",
"VerifyModel": "2",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"FaceGroupCodes": "sg*****xta",
"AutoRegistration": "0",
"FaceRegisterGroupCode": "sg*****xta",
"AppQualityCheck": "Y",
"ShowGuidePage": "1"
}
Modo integral del Web SDK (1:1 y 1:N)
Solicitud mínima
Cuando el parámetro VerifyModel se establece en 2, el sistema ejecuta tanto la comparación 1:1 contra la cara objetivo como la búsqueda 1:N dentro de la biblioteca de caras especificada. En una solicitud mínima, el registro automático está deshabilitado de forma predeterminada.
{
"ProductCode": "FACE_IDU",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value",
"VerifyModel": "2",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"FaceGroupCodes": "sg*****xta",
"ReturnUrl": "https://example.com/face-idu/result"
}
Solicitud completa
{
"ProductCode": "FACE_IDU",
"SceneCode": "web_comprehensive_01",
"MerchantBizId": "biz_20230805uvwxyz",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value_222",
"ReturnUrl": "https://example.com/face-idu/result",
"SecurityLevel": "02",
"Model": "LIVENESS",
"VerifyModel": "2",
"TargetFacePictureUrl": "https://example.com/trusted-face.jpg",
"FaceGroupCodes": "sg*****xta",
"AutoRegistration": "0",
"FaceRegisterGroupCode": "sg*****xta",
"ShowGuidePage": "1"
}