API operation details
- API operation: InitializeV2
- Request method: HTTPS POST
Description: Before starting an authentication flow, call this API operation to obtain a transactionId. This ID links the API operations in the authentication request.
-
Límite de QPS: cada API tiene su propio límite de QPS. Para obtener más información, consulte QPS limits of ID Verification server-side APIs.
-
Service 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 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 suelen ser complejos. Consulte Optimize server network latency para ajustar su integración, reducir la latencia de red y disminuir 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 invocar las API en la plataforma OpenAPI y obtener el SDK.
Puede invocar esta operación de API en OpenAPI Explorer para depurar la solicitud, y generar ejemplos de código del SDK.
Notas sobre la integración
Condición para devolver TransactionId: el campo TransactionId se devuelve únicamente si la inicialización es exitosa.
Periodo de validez de la autenticación: el cliente debe completar la autenticación en un plazo de 30 minutos después de obtener el TransactionId o el TransactionUrl.
Límites de TransactionUrl: este campo solo se devuelve en escenarios H5 móviles y se puede usar una única vez. No concatene, modifique ni acceda repetidamente a la URL.
Obtención del resultado de autenticación: la notificación CallbackUrl puede retrasarse debido a la latencia de red. Cuando el cliente reciba la notificación de finalización de la autenticación, debe invocar la operación de API CheckResult en el servidor para recuperar los detalles finales. No dependa exclusivamente de la notificación de callback ni del resultado que muestra la página.
Diferencias entre las funciones del SDK: el App SDK y el Web SDK tienen funciones distintas. En el caso del Web SDK, también existen pequeñas diferencias entre los navegadores H5 móviles y los de PC. Para más detalles, consulte los documentos de integración.
Límites regionales en los tipos de certificado: los tipos de certificado compatibles varían según la región de despliegue. Antes de integrar, revise la tabla de tipos de certificado correspondiente a su región de destino.
Parámetros de solicitud
Descripción de los campos
|
Método de integración |
Escenario |
Respuesta de la operación de API de inicialización |
Parámetros de solicitud |
|
App SDK |
Completar la autenticación dentro de una aplicación nativa de Android o iOS. |
|
Parámetros comunes + parámetros específicos de la aplicación |
|
Web SDK |
Autenticación en una página H5 móvil o en 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: se pueden enviar con ambos métodos de integración.
Específicos de la aplicación: se utilizan para el método de escaneo de certificados.
Específicos del Web SDK: sirven para controlar las redirecciones de página, el idioma y la interfaz, las páginas de OCR y el comportamiento de respaldo (fallback) en H5.
Parámetros de solicitud (comunes)
Campo | Tipo | Obligatorio | Descripción | Ejemplo |
ProductCode | String | Sí | El identificador del plan de producto. Establezca el valor en: ID_OCR_PRO. El usuario debe completar el proceso de OCR del certificado. Nota El Web SDK admite la integración directa. Para la integración en aplicaciones, solo son compatibles las versiones 1.3.9 y posteriores del Native SDK. | ID_OCR_PRO |
SceneCode | String | No | Un identificador personalizado para el escenario de autenticación. Puede usarlo para buscar registros en la consola. Admite hasta 10 caracteres, que pueden ser letras, dígitos y guiones bajos (_). | 1234567890 |
MerchantBizId | String | Sí | Un identificador de negocio único para el comerciante, utilizado para solucionar problemas. Admite hasta 32 caracteres, que pueden ser letras y dígitos. El servidor no comprueba que este identificador sea único, por lo que el comerciante debe garantizar dicha unicidad. | e0c34a77f5ac40a5aa5e6ed20c35**** |
MetaInfo | String | Sí | Información del entorno del cliente. Genere estos datos mediante el SDK correspondiente. Si los crea manualmente, como mínimo debe enviar 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 genera un valor estático de MetaInfo, asegúrese de que | |
MerchantUserId | String | Sí | Un identificador de usuario personalizado para el comerciante u otro dato como un número de celular o una dirección de correo electrónico. Se recomienda aplicar técnicas de anonimización o hash a este campo de antemano. | 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. Si configura este parámetro, se devolverá junto con CallbackUrl para realizar comprobaciones contra ataques de repetición y manipulación de datos. | NMjvQanQgplBSaEI0sL******** |
IdThreshold | String | No | Comprobación de calidad de la tarjeta mediante OCR:
| 3 |
IdSpoof | String | No | [Configuración de OCR] Indica si se habilita la comprobación antifalsificación del certificado:
Para ver el resultado, consulte | N |
OcrValueStandard | String | No | [Configuración de OCR] Indica si se devuelven campos de OCR estandarizados:
Para ver el resultado, consulte | 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 de los modelos.
| Ejemplos de los tres métodos de entrada:
|
Pages | String | No | [Configuración de OCR] Las páginas del certificado que se van a recopilar:
Nota Solo algunos certificados permiten recopilar 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 la versión 1.4.0 y posteriores del Native SDK. |
|
ShowGuidePage | String | No | [Configuración de la interfaz] Indica si se muestra la página de guía:
Esta configuración no es compatible con el modo de navegador de PC. Se admite en la versión 1.2.8 y posteriores del Native SDK. | 1 |
Parámetros de solicitud (específicos de la aplicación)
Solo el App SDK nativo admite los campos siguientes.
Campo | Tipo | Obligatorio | Descripción | Ejemplo |
DocScanMode | String | No | [Configuración de OCR] El modo de escaneo del certificado mediante OCR:
Este parámetro solo es compatible con la versión 1.2.8 y posteriores del Native SDK, y requiere integrar el componente de escaneo automático. | shoot |
Parámetros de solicitud (específicos del Web SDK)
Solo el Web SDK admite los campos siguientes.
Campo | 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 basándose en la plantilla proporcionada y pásela como este parámetro. Para obtener más información, consulte Customize Web SDK languages. Nota Solo es compatible con el modo de integración móvil del Web SDK. | |
StyleConfig | String | No | Una cadena JSON para la configuración de interfaz 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 obtener más información, consulte Customize IDV UI styles. Nota Solo es compatible con el modo de integración móvil del Web SDK. | |
ShowAlbumIcon | String | No | [Configuración de OCR] Indica si se muestra la opción de carga desde el álbum durante el paso de OCR:
| 1 |
ShowOcrResult | String | No | [Configuración de OCR] Indica si se muestra la página de resultados de reconocimiento durante el paso de OCR:
| 1 |
EditOcrResult | String | No | [Configuración de OCR] Indica si se permite a los usuarios editar el resultado del reconocimiento de OCR:
| 1 |
ReturnUrl | String | Condicionalmente obligatorio | La URL de redirección del negocio una vez que termina la autenticación. Este parámetro no es obligatorio cuando se utiliza el modo de inserción iframe, pero debe proporcionarse en escenarios de redirección de páginas sin iframe. | https://www.alibabacloud.com |
ProcedurePriority | String | No | Indica si se permite un método alternativo cuando ocurre un problema de compatibilidad durante la autenticación H5 móvil.
| url |
Response data
Diferencias en los campos de respuesta
|
Campo |
App SDK |
Web SDK |
Descripción |
|
RequestId / Code / Message |
Sí |
Sí |
Información común de la respuesta. |
|
Result.TransactionId |
Sí |
Sí |
Identificador único del flujo de autenticación. Este campo se utiliza para la facturación y como parámetro de solicitud en la operación de API |
|
Result.Protocol |
Sí |
Sí |
Protocolo cifrado estándar para la autenticación. Se recomienda pasarlo al SDK del cliente. El método de embedding mediante iframe del Web SDK depende de este campo. |
|
Result.TransactionUrl |
No |
Sí |
URL de autenticación del Web SDK. Tras completar la autenticación, se redirige al usuario a |
Nombre | Tipo | Descripción | Ejemplo | |
Código de estado HTTP | Integer | El código de estado HTTP. | 200 | |
Cuerpo HTTP | RequestId | String | El identificador de la solicitud. | 130A2C10-B9EE-4D84-88E3-5384FF03**** |
Code | String | El código de respuesta. Para más información, consulte Server-side HTTP status codes. | Success | |
Message | String | Descripción detallada del código de respuesta. | success | |
Result.TransactionId | String | Identificador único del flujo de autenticación. Se utiliza para la facturación y es obligatorio en las llamadas a la API CheckResult. Importante
| hksb7ba1b28130d24e015d6******** | |
Result.TransactionUrl | String | URL de autenticación del Web SDK. Una vez completada la autenticación, se redirige al usuario según el ReturnUrl especificado como parámetro de solicitud. Importante
| https://www.alibabacloud.com/index.html?clientcfg=**** | |
Result.Protocol | String | Cadena cifrada correspondiente al protocolo estándar de autenticación. Pasar este parámetro al SDK del cliente reduce las interacciones de red y admite 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": "ID_OCR_PRO",
"MerchantBizId": "e0c34a77f5ac40a*****",
"MetaInfo": "{\"deviceType\":\"android\"}",
"MerchantUserId": "user_hash_value",
"DocType": "GLB03001"
}
Ejemplo completo de solicitud
{
"ProductCode": "ID_OCR_PRO",
"MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
"MetaInfo": "{\"deviceType\":\"android\",\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"bioMetaInfo\":\"4.1.0:1150****,0\",\"appName\":\"com.aliyun.antcloudauth\",\"osVersion\":\"Android 10\",\"apdidToken\":\"\",\"deviceModel\":\"Pixel 4\"}",
"MerchantUserId": "123456789",
"DocType": "GLB03001",
"SceneCode": "1234567890",
"CallbackUrl": "https://www.aliyun.com?callbackToken=100000****",
"CallbackToken": "NMjvQanQgplBSaEI0sL********",
"IdThreshold": "3",
"IdSpoof": "N",
"OcrValueStandard": "0",
"Pages": "01",
"ShowGuidePage": "1",
"DocScanMode": "shoot"
}
Web SDK
Ejemplo mínimo de solicitud
{
"ProductCode": "ID_OCR_PRO",
"MerchantBizId": "e0c34a77f5ac40a5a*****",
"MetaInfo": "{\"deviceType\":\"h5\"}",
"MerchantUserId": "user_hash_value",
"DocType": "GLB03001",
"ReturnUrl": "https://example.com/ekyc/callback"
}
Ejemplo completo de solicitud
{
"ProductCode": "ID_OCR_PRO",
"MerchantBizId": "e0c34a77f5ac40a5aa5e6ed20c35****",
"MetaInfo": "{\"deviceType\":\"h5\",\"zimVer\":\"3.0.0\",\"appVersion\":\"1\",\"bioMetaInfo\":\"4.1.0:1150****,0\",\"appName\":\"com.aliyun.antcloudauth\",\"osVersion\":\"iOS 10.3.2\",\"apdidToken\":\"\",\"deviceModel\":\"iPhone9,1\"}",
"MerchantUserId": "123456789",
"DocType": "GLB03001",
"SceneCode": "1234567890",
"CallbackUrl": "https://www.aliyun.com?callbackToken=100000****",
"CallbackToken": "NMjvQanQgplBSaEI0sL********",
"IdThreshold": "3",
"IdSpoof": "N",
"OcrValueStandard": "0",
"Pages": "01",
"ShowGuidePage": "1",
"LanguageConfig": "{\"languageContent\":{},\"ocrResultContent\":{},\"supportedLanguage\":[\"zh\"],\"titleTranslate\":{}}",
"StyleConfig": "{\"guidepage\":{},\"ocrPage\":{},\"ocrResultPage\":[],\"facePage\":{}}",
"ShowAlbumIcon": "1",
"ShowOcrResult": "1",
"EditOcrResult": "1",
"ReturnUrl": "https://www.alibabacloud.com",
"ProcedurePriority": "url"
}