Todos los productos
Search
Centro de documentos

ID Verification:InitializeV2

Última actualización: Oct 17, 2026

This topic describes how to initiate an ID_OCR_PRO request by calling the InitializeV2 API operation.

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.com

    • Endpoint interno: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

    Asia Pacific SE 5 (Jakarta)

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

TransactionId, Protocol

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.

TransactionId, TransactionUrl, Protocol

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 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 de 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 genera 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": "h5",
  "osVersion": "iOS 10.3.2",
  "apdidToken": "",
  "deviceModel": "iPhone9,1"
}

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

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:

  • 1: habilita el modo estricto.

  • 2: habilita el modo flexible (predeterminado).

  • 3: deshabilita la comprobación.

3

IdSpoof

String

No

[Configuración de OCR] Indica si se habilita la comprobación antifalsificación del certificado:

  • Y: habilitada (predeterminado).

  • N: deshabilitada.

Para ver el resultado, consulte Result.ExtIdInfo.ocrIdInfoData.{page}.spoofInfo en la respuesta de CheckResult.

N

OcrValueStandard

String

No

[Configuración de OCR] Indica si se devuelven campos de OCR estandarizados:

  • 0: no (predeterminado).

  • 1: sí.

Para ver el resultado, consulte Result.ExtIdInfo.ocrStandardData en la respuesta de CheckResult.

0

DocType

String

Sí

[Configuración de OCR] Admite los tres métodos de entrada siguientes:

  1. Especificar país o región: envíe un código de país de tres letras. El sistema recupera automáticamente los tipos de documento compatibles dentro del alcance indicado y devuelve el código específico del documento tras reconocerlo correctamente. Puede especificar hasta tres códigos (por ejemplo, CHN, HKG y GLB) como alcance de clasificación automática. Para consultar los códigos de país de tres letras, vea Country code abbreviations.

  2. Especificar país o región y categoría de documento (solo en la región de Malaysia): envíe un código de país de tres letras y un código de categoría de documento de dos dígitos. El sistema recupera automáticamente los tipos de documento compatibles dentro del alcance indicado y devuelve el código específico del documento tras reconocerlo correctamente. Para consultar los códigos de tipo de documento, vea Certificate type codes.

  3. Especificar el documento exacto: envíe el código exacto del tipo de documento, formado por un código de país de tres letras y un número de documento de cinco dígitos. El sistema verifica con precisión si el documento coincide con el tipo esperado. Para consultar los códigos de tipo de documento, vea Certificate code.

Importante

Los tipos de certificado compatibles varían según la región debido a limitaciones de los modelos.

  • Regiones Singapore y China (Hong Kong): admiten los certificados descritos en Certificate code.

  • Región Indonesia: solo admite tarjetas de identidad indonesias y pasaportes globales (códigos de certificado IDN01001 y GLB03002).

  • Región Malaysia: solo admite tarjetas de identidad malasias y pasaportes globales (códigos de certificado MYS01001 y GLB03002).

Ejemplos de los tres métodos de entrada:

  • MYS: código de país de Malaysia.

  • MYS01: tarjeta de identidad de Malaysia.

  • GLB03002: pasaporte global.

Pages

String

No

[Configuración de OCR] Las páginas del certificado que se van a recopilar:

  • 01: anverso (predeterminado).

  • 01.02: anverso y reverso.

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 DocType se establece en un 'código de país o región' o en 'país o región y categoría de documento'. De forma predeterminada, solo captura el anverso del documento. Para capturar tanto el anverso como el reverso de una categoría de documento específica (consulte Certificate type codes) o de un tipo de documento exacto (consulte Certificate code) de ese país, configure este parámetro según corresponda. Vea los ejemplos de la derecha para más detalles.

Este parámetro solo es compatible con la versión 1.4.0 y posteriores del Native SDK.

  • Capturar el anverso y el reverso de la nueva tarjeta de identidad nacional de Malaysia:

    {
      "MYS01002": "01,02"
    }
  • Establecer la categoría del documento:

    {
      "MYS01": "01,02"
    }

ShowGuidePage

String

No

[Configuración de la interfaz] Indica si se muestra la página de guía:

  • 1: mostrar (predeterminado).

  • 0: no mostrar.

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:

  • shoot: tomar una fotografía.

  • scan: escanear automáticamente.

  • auto: alternar automáticamente entre tomar una fotografía y escanear.

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.

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

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.

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

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: mostrar (predeterminado).

  • 0: no mostrar.

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: mostrar (predeterminado).

  • 0: no mostrar.

1

EditOcrResult

String

No

[Configuración de OCR] Indica si se permite a los usuarios editar el resultado del reconocimiento de OCR:

  • 1: permitir (predeterminado).

  • 0: no permitir.

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: se admite el método alternativo. La página muestra la URL de autenticación y el usuario puede copiarla para abrirla en otro navegador y continuar con el proceso (predeterminado).

  • keep: no se admite el método alternativo. El sistema devuelve directamente la causa del error y finaliza el flujo de autenticación. Esta opción no es compatible con PC. Se recomienda establecerla en keep para las páginas web integradas en una aplicación.

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 CheckResult. Se recomienda vincularlo con su identificador de negocio y almacenarlo únicamente en el servidor.

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 ReturnUrl. No modifique esta URL, ya que solo se puede acceder a ella una vez. La autenticación debe completarse en un plazo de 30 minutos después de obtener la URL o TransactionId.

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
  • La API init no devuelve TransactionId si la solicitud falla, por ejemplo, debido a un parámetro no válido.

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

  • TransactionId o TransactionUrl tiene una validez de 30 minutos. Debe completar la autenticación dentro de este periodo; de lo contrario, el identificador caducará.

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
  • No modifique TransactionUrl durante el proceso de integración, ya que esto provocará una excepción de verificación.

  • TransactionUrl es de un solo uso. Si lo reutiliza, se generará 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

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"
}