Este tema describe cómo llamar a la operación InitializeV2 para iniciar una solicitud de eKYC-PRO.
Información de la API
Nombre de la operación: InitializeV2
Método de solicitud: HTTPS POST
Descripción: antes de iniciar un flujo de autenticación, llame a esta operación para obtener un transactionId. Este identificador vincula todas las llamadas posteriores a la API correspondientes a la solicitud de autenticació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.
-
Endpoint:
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 se despliega 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 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
Asia Pacific SE 5 (Jakarta)
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.
Acceda a OpenAPI Explorer para ejecutar y depurar esta API, así como generar ejemplos de código del SDK.
Notas sobre la integración
El valor
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.La
TransactionUrlse devuelve solo para 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. Una vez que reciba 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. 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 para celular y PC. Para más información sobre las funciones compatibles, consulte los documentos de integración.
Los tipos de certificado compatibles varían según la región de despliegue. Antes de empezar, compruebe los Certificate Type Table correspondientes a su región de destino.
Habilitar
Authorizepuede generar cargos adicionales y tiene un tiempo de respuesta de 1 a 30 segundos. Configure el tiempo de espera del lado del servidor de acuerdo con este rango.
Parámetros de la solicitud
Descripción de los campos
|
Método de integración |
Escenarios |
Respuesta de la API de inicialización |
Parámetros de la solicitud |
|
App SDK |
Autenticación en una aplicación nativa de Android o iOS |
|
Parámetros comunes + parámetros específicos de la aplicación |
|
Web SDK |
Autenticación en H5 para celular o en un navegador de PC |
|
Parámetros comunes + parámetros específicos de Web SDK |
Los campos se clasifican de la siguiente manera:
Parámetros comunes: se utilizan en ambos métodos de integración.
Específicos de App SDK: permiten personalizar el flujo de detección de vida y el método de escaneo de documentos.
Específicos de Web SDK: controlan las redirecciones de página, el idioma, la interfaz de usuario, las páginas de OCR y el comportamiento de respaldo en H5.
Parámetros de la solicitud (comunes)
Campo | Tipo | Obligatorio | Nota | Valor de ejemplo |
ProductCode | String | Sí | Identificador de la solución del producto. Valor: eKYC_PRO. El usuario debe completar la verificación del documento de identidad y la detección de vida. | eKYC_PRO |
SceneCode | String | No | 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í | Identificador de negocio único del comerciante, que se utiliza para identificar y solucionar problemas. Es una cadena de 32 caracteres compuesta por letras y números. El servidor no valida que este identificador sea ú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í | Identificador de usuario personalizado u otro identificador reconocible, como un número de celular o una dirección de correo electrónico. Se recomienda aplicar hash o anonimizar este campo. | 123456789 |
IdThreshold | String | No | Comprobación de calidad de la tarjeta mediante OCR:
| 2 |
IdSpoof | String | No | Detección antisuplantación mediante OCR:
Consulte el resultado en CheckResult, dentro de | Y |
OcrValueStandard | String | No | Configuración de OCR: indica si se devuelven campos de OCR estandarizados:
El resultado se devuelve en el campo | 0 |
DocType | String | Sí | [Configuración de OCR] Admite los tres métodos de entrada siguientes:
Importante Los tipos de certificado compatibles varían según la región debido a limitaciones del modelo.
| Ejemplos de los tres métodos de entrada:
|
Pages | String | No | Configuración de OCR para la página de captura del certificado:
Nota Solo algunos certificados admiten la captura de varias páginas. Para obtener más información, consulte Certificate type table. | 01 |
AutoDocPageConfig | String | No | [Configuración de OCR] Este parámetro solo surte efecto cuando Este parámetro solo es compatible con Native SDK 1.4.0 y versiones posteriores. |
|
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 la 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, 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 |
ShowGuidePage | String | No | Configuración de la interfaz de usuario: mostrar la página de guía:
El modo para PC no admite esta configuración. Compatible con Native SDK versión 1.2.8 y posteriores. | 1 |
CallbackUrl | String | No | URL de devolución de llamada 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 para el comerciante. Una vez configurado, este token se devuelve sin cambios junto con CallbackUrl para verificar que no haya repeticiones ni alteraciones. | NMjvQanQgplBSaEI0sL**** |
Security level | String | No | Nivel de seguridad. Valores válidos:
| 02 |
Authorize | String | No | Interruptor de validación con fuentes de datos oficiales:
Nota
| T |
Mobile | String | Condicionalmente obligatorio | Número de celular de Indonesia con el formato | +6281293671234 |
String | Condicionalmente obligatorio | Buzón de correo del usuario. Obligatorio cuando | a*@gmail.com |
Parámetros de la solicitud (específicos de App SDK)
Solo App SDK nativo admite los siguientes campos.
Campo | Tipo | Obligatorio | Descripción | Valor de ejemplo |
AppQualityCheck | String | No | [Configuración de escaneo facial] Indica si se habilita la detección estricta de calidad facial.
Solo compatible con Native SDK v1.2.5 y versiones posteriores. Se debe integrar el módulo de detección de calidad facial. | N |
TemplateConfig | String | Condicionalmente obligatorio | [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 | Condicionalmente obligatorio | [Configuración de escaneo facial] Orden de ejecución de las acciones de detección de vida definidas 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.
Compatible con Native SDK versión 1.4.1 y posteriores. | Y |
DocScanMode | String | No | [Configuración de OCR] Modo de escaneo de certificados por OCR.
Solo compatible con Native SDK v1.2.8 y versiones posteriores. Se debe integrar el componente de escaneo automático. | shoot |
Parámetros de la solicitud (específicos de Web SDK)
Solo Web SDK admite los siguientes campos.
Campo | Tipo | Obligatorio | Nota | Valor de 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 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 Solo compatible con el modo de integración móvil de Web SDK. | |
StyleConfig | String | No | Cadena JSON para la configuración personalizada de la interfaz de usuario. Para aplicar la configuración, 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 Solo compatible con el modo de integración móvil de Web SDK. | |
ShowAlbumIcon | String | No | Configuración de OCR: indica si se muestra la opción de cargar desde un álbum durante el paso de OCR:
| 1 |
ShowOcrResult | String | No | Configuración de OCR: controla si se muestra la página de resultados de detección durante el paso de OCR:
| 1 |
EditOcrResult | String | No | Configuración de OCR: indica si los usuarios pueden editar los resultados del reconocimiento de OCR:
| 1 |
ReturnUrl | String | Condicionalmente obligatorio | URL de redirección después de la autenticación. Es opcional para el patrón integrado en iframe. 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 para celular.
| URL |
Datos de retorno
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 |
Nombre | Tipo | Descripción | Valor de ejemplo | |
Código de estado HTTP | Integer | Código de estado HTTP. | 200 | |
Cuerpo HTTP | RequestId | String | El ID de la solicitud. | 130A2C10-B9EE-4D84-88E3-5384FF03**** |
Code | String | 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 autenticación del Web SDK redirige tras la autenticación según el parámetro de entrada ReturnUrl. Importante
| https://www.alibabacloud.com/index.html?clientcfg=**** | |
Result.Protocol | String | La cadena cifrada del 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 de solicitud mínima
{
"ProductCode": "eKYC_PRO",
"MerchantBizId": "e0c34a77f5ac40a*****",
"MetaInfo": "{\"deviceType\":\"android\"}",
"MerchantUserId": "user_hash_value",
"DocType": "GLB03001"
}
Ejemplo de solicitud completa
{
"ProductCode": "eKYC_PRO",
"SceneCode": "1234567890",
"MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
"MetaInfo": "{\"deviceType\":\"android\",\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"appName\":\"com.aliyun.antcloudauth\",\"osVersion\":\"Android 12\",\"deviceModel\":\"Pixel 6\"}",
"MerchantUserId": "user_hash_value_123",
"DocType": "GLB03001",
"Pages": "01,02",
"Model": "TEMPLATE",
"DocVideo": "N",
"FaceAttributeCheck": "N",
"ShowGuidePage": "1",
"CallbackUrl": "https://www.aliyun.com/callback",
"CallbackToken": "NMjvQanQgplBSaEI0sL********",
"SecurityLevel": "02",
"Authorize": "F",
"IdThreshold": "2",
"IdSpoof": "Y",
"OcrValueStandard": "0",
"AutoDocPageConfig": "{\"BRA01001\": \"01\", \"BRA01002\": \"01,02\"}",
"AppQualityCheck": "Y",
"TemplateConfig": "01,02,07",
"TemplateType": "Seq",
"TemplateRanCount": "2",
"DocScanMode": "shoot"
}
Web SDK
Ejemplo de solicitud mínima
{
"ProductCode": "eKYC_PRO",
"MerchantBizId": "e0c34a77f5ac40a5a*****",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value",
"DocType": "GLB03001",
"ReturnUrl": "https://example.com/ekyc/callback"
}
Ejemplo de solicitud completa
{
"ProductCode": "eKYC_PRO",
"SceneCode": "1234567890",
"MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
"MetaInfo": "{\"deviceType\":\"h5\",\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"appName\":\"Chrome\",\"osVersion\":\"Windows 10\",\"deviceModel\":\"PC\"}",
"MerchantUserId": "user_hash_value_123",
"DocType": "GLB03001",
"Pages": "01",
"Model": "PHOTINUS_LIVENESS",
"DocVideo": "N",
"FaceAttributeCheck": "N",
"ShowGuidePage": "1",
"CallbackUrl": "https://www.aliyun.com/callback",
"CallbackToken": "NMjvQanQgplBSaEI0sL********",
"SecurityLevel": "02",
"Authorize": "F",
"IdThreshold": "2",
"IdSpoof": "Y",
"OcrValueStandard": "0",
"AutoDocPageConfig": "{\"BRA01001\": \"01\", \"BRA01002\": \"01,02\"}",
"LanguageConfig": "{\"languageContent\":{},\"ocrResultContent\":{},\"supportedLanguage\":[\"zh-CN\"],\"titleTranslate\":{}}",
"StyleConfig": "{\"guidepage\":{},\"ocrPage\":{},\"ocrResultPage\":[],\"facePage\":{}}",
"ShowAlbumIcon": "1",
"ShowOcrResult": "1",
"EditOcrResult": "1",
"ReturnUrl": "https://example.com/ekyc/callback",
"ProcedurePriority": "url"
}