Todos los productos
Search
Centro de documentos

ID Verification:InitializeV2

Última actualización: Oct 27, 2026

Inicia una sesión de verificación de ID_NFC y devuelve un transactionId para las llamadas a la API posteriores.

Initiate a verification request

  • Operación de API: InitializeV2

  • Método de solicitud: HTTPS POST

  • Descripción: después de que el cliente obtiene MetaInfo, llame a esta operación para conseguir un transactionId. El cliente utiliza este identificador para iniciar la autenticación.

    Importante

    Cada transactionId es de un solo uso. El identificador caduca inmediatamente después de un intento de autenticación, sin importar si el resultado fue exitoso, fallido o cancelado. No reutilice el identificador para llamar al SDK. Para volver a autenticar, solicite un nuevo transactionId desde el lado del servidor.

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

    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 su servidor de aplicaciones está desplegado en la misma región, utilice el endpoint interno para acceder al servicio ID Verification. Esto mejora 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, reducir la latencia de red y evitar fallos 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 cómo llamar a las API en la plataforma OpenAPI y obtener el SDK.

Ejecute esta operación en OpenAPI Explorer para hacer pruebas, y genere ejemplos de código del SDK para esta operación en Ejemplos de código del SDK.

Request parameters

Nombre

Tipo

Obligatorio

Descripción

Ejemplo

ProductCode

String

Sí

La solución de verificación que se va a utilizar.

Establezca el valor en ID_NFC.

ID_NFC

SceneCode

String

No

Identificador de escenario personalizado para consultar los registros relacionados en la consola.

Debe ser una cadena de 10 caracteres que contenga únicamente letras, dígitos y guiones bajos.

1234567890

MerchantBizId

String

Sí

Identificador comercial único para la resolución de problemas. Debe ser una cadena alfanumérica de 32 caracteres.

Nota

Alibaba Cloud no valida que este valor sea único. Asegúrese de garantizar la unicidad en su sistema para un seguimiento eficaz.

e0c34a77f5ac40a5aa5e6ed20c35****

MetaInfo

String

Sí

Información del entorno del cliente. Genere esta información con el SDK correspondiente. Si la construye manualmente, como mínimo debe pasar 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 en la 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 construye un valor estático de MetaInfo, asegúrese de que deviceType coincida con el entorno real. Un valor incorrecto provocará errores cuando se emita la URL de autenticación.

{
        "appVersion": "1",
        "bioMetaInfo": "4.1.0:1150****,0",
        "appName": "com.aliyun.antcloudauth",
        "deviceType": "ios",
        "osVersion": "iOS 10.3.2",
        "apdidToken": "",
        "deviceModel": "iPhone9,1"
    }

MerchantUserId

String

No

Identificador de usuario personalizado, como un número de celular o una dirección de correo electrónico. Aplique técnicas de ofuscación a este valor (por ejemplo, mediante hashing) antes de pasarlo.

123456789

DocType

String

Sí

Tipo de documento expresado como un código de 8 dígitos. Solo son compatibles los pasaportes globales. Establezca el valor en 01000000.

01000000

MRTDInput

String

Sí

Origen de entrada para los parámetros de verificación MRTD. NFC utiliza este valor para descifrar los datos del chip del certificado.

  • 0: entrada del usuario

  • 1: lectura OCR

  • 2: entrada mediante operación de API

0

DocumentNumber

String

No

Número de documento.

Obligatorio cuando MRTDInput = 2.

DateOfBirth

String

No

Fecha de nacimiento indicada en el certificado.

Obligatorio cuando MRTDInput = 2.

DateOfExpiry

String

No

Fecha de vencimiento indicada en el certificado.

Obligatorio cuando MRTDInput = 2.

CallbackUrl

String

No

URL de devolución de llamada para el resultado de la autenticación. Esta URL debe comenzar con https. La plataforma envía una solicitud GET a esta URL y añade 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

Token de seguridad que usted genera para evitar ataques de repetición y manipulación.

Cuando se configura, el campo CallbackToken se incluye en la devolución de llamada de CallbackUrl.

NMjvQanQgplBSaEI0sL86

ShowGuidePage

String

No

Configuración de la interfaz: mostrar página de guía:

  • 1: mostrar (valor predeterminado)

  • 0: no mostrar

Compatible con la versión 1.4.0 y posteriores del SDK nativo.

1

Datos devueltos

Nombre

Tipo

Descripción

Ejemplo

HTTP Status Code

Integer

Código de estado HTTP

200

HTTP Body

RequestId

String

Identificador de la solicitud

130A2C10-B9EE-4D84-88E3-5384****

Code

String

Código de retorno. Para 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 utiliza para la facturación y es obligatorio en las llamadas a la API CheckResult.

Importante
  • La API de inicialización no devuelve un TransactionId si la solicitud falla, por ejemplo, debido a un parámetro no válido.

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

  • El TransactionId o TransactionUrl tiene una vigencia de 30 minutos. Debe completar la autenticación dentro de este periodo; después, el identificador caduca.

hksb7ba1b28130d24e015d6****

Result.Protocol

String

Cadena cifrada del protocolo de autenticación estándar.

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