API description
- Operation name: CheckResult
- Request method: HTTPS POST
-
Description: Cuando el servidor recibe una notificación de callback que indica la finalización de la autenticación, llame a esta API para obtener el estado y la información correspondientes. Este callback se envía cuando el código de resultado del cliente es 1001 o 1002. Para más información, consulte Native SDK client result codes and sub-codes.
-
Importante
El servicio ID Verification almacena los resultados de verificación durante 30 días de forma predeterminada. Consúltelos dentro de este periodo, ya que se eliminan automáticamente después.
-
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:
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 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 conocer cómo llamar a las API en la plataforma OpenAPI y obtener el SDK.
Puede probar esta operación en OpenAPI Explorer y generar código de ejemplo del SDK.
Notas de integración
Especificaciones de almacenamiento de TransactionId: TransactionId es el identificador confiable del servidor para un registro de autenticación. Debe vincularlo con su identificador de negocio y almacenarlo de forma persistente en el servidor.
Periodo de retención de registros: los registros de resultados de autenticación se almacenan durante 30 días de forma predeterminada y se eliminan automáticamente después de ese periodo. Consulte los resultados dentro de este plazo y guarde correctamente los datos obligatorios conforme a la normativa vigente.
Cumplimiento normativo en la obtención y retención de videos: los videos solo se devuelven cuando la función correspondiente está habilitada y el proceso de autenticación es exitoso. El enlace de descarga de un video de evidencia tiene una vigencia de 15 minutos. El video original se elimina automáticamente 30 minutos después de finalizar la autenticación. Si su negocio requiere conservar los videos, descárguelos de inmediato y cumpla estrictamente con los requisitos locales de privacidad y protección de datos.
Especificaciones para obtener imágenes: las imágenes de autenticación solo se devuelven cuando IsReturnImage se establece en Y y la verificación facial es exitosa. Dado que los datos en Base64 son voluminosos, mantenga este parámetro en su valor predeterminado N si no necesita mostrar ni conservar las imágenes.
Diferenciación entre el estado de la API y el resultado de autenticación: el valor Success en el parámetro Code solo indica que la llamada a la API fue exitosa. El resultado final de la autenticación debe basarse en los campos Result.Passed y Result.SubCode.
Solución de problemas de autenticación fallida: si Passed es N, determine la causa del fallo mediante la revisión de los campos SubCode, ExtFaceInfo, ExtIdInfo y ExtSourceInfo (si existe).
Compatibilidad en el análisis sintáctico de campos: el contenido devuelto, como los campos de reconocimiento óptico de caracteres (OCR), el número de páginas del certificado y los atributos faciales, varía dinámicamente según el tipo de certificado, las capacidades del servicio en la región y la configuración del SDK. La lógica de análisis sintáctico del cliente debe ser compatible con versiones anteriores para garantizar el funcionamiento correcto cuando falten o se agreguen campos.
Descripción de la distribución de campos
La estructura principal de respuesta, los resultados de detección de vitalidad y los campos de resultados de OCR de CheckResult son consistentes tanto en integraciones con App SDK como con Web SDK.
|
Categoría |
Campo |
Descripción |
|
Salida común |
Respuesta general, conclusión de autenticación, |
Se devuelve en ambos modos de integración. Su inclusión depende del flujo de autenticación y de la configuración de InitializeV2. |
|
Específico de Web SDK |
|
Cuando ocurre una degradación por compatibilidad durante la autenticación, se devuelve la directiva de degradación aplicada. |
|
Específico de la aplicación |
Ninguna |
Ninguna |
Request parameters (common)
Campo | Tipo | Obligatorio | Descripción | Valor de ejemplo |
MerchantBizId | String | Sí | Identificador de negocio único del comerciante, compuesto por 32 letras y números. Debe coincidir con el valor utilizado en la solicitud InitializeV2. | e0c34a77f5ac40a5aa5e6ed20c35**** |
TransactionId | String | Sí | Identificador de autenticación único que devuelve una llamada exitosa a la API init. Para evitar alteraciones, obtenga siempre este valor desde el almacenamiento del servidor y no confíe en el valor enviado por el cliente. | hksb7ba1b28130d24e015d6**** |
IsReturnImage | String | No | Especifica si se devuelven los materiales de imagen de autenticación (incluidos los certificados):
| Y |
Return Data
Nombre | Tipo | Descripción | Valor de ejemplo | |
HTTP Status Code | Integer | El código de estado HTTP. | 200 | |
HTTP Body | RequestId | String | El identificador de la solicitud, que se utiliza para solucionar problemas. | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Code | String | El código de respuesta del servidor. Para obtener más información, consulte Server-side HTTP status codes. | Success | |
Message | String | Una descripción detallada del código de respuesta. | success | |
Result.Passed | String | El resultado final de la autenticación:
| Y | |
Result.SubCode | String | La descripción del resultado de la autenticación. Para obtener más información, consulte Result.SubCode authentication result subcode descriptions. | 200 | |
Result.ExtFaceInfo | String | Los resultados relacionados con la verificación de vitalidad facial. Para obtener más información, consulte Result.ExtFaceInfo. | | |
Result.ExtIdInfo | String | Los resultados del reconocimiento óptico de caracteres (OCR) y de la detección antisuplantación del certificado. Para obtener más información, consulte Result.ExtIdInfo. | | |
Result.ExtSourceInfo | String | Los detalles de la verificación en la fuente de datos oficial. Este campo solo se devuelve cuando Authorize=T en InitializeV2 y se llama realmente a la fuente de datos correspondiente. Para obtener más información, consulte Result.ExtSourceInfo. | | |
Result.ExtInfo | String | Otra información de autenticación, que incluye principalmente los datos reales de degradación para H5 móvil. Para obtener más información, consulte Result.ExtInfo. | | |
Result.ExtFaceInfo
Nombre | Tipo | Descripción | Valor de ejemplo |
facePassed | String | El resultado general de la verificación de vitalidad facial:
| Y |
faceComparisonScore | Double | La puntuación de comparación entre el rostro en vivo y la fotografía del certificado, en un rango de 0 a 100. Una puntuación mayor o igual a 90 indica una aprobación. | 99.99 |
faceImg | String | La imagen del rostro en vivo en formato Base64. Se devuelve únicamente cuando | Base64 format |
docVideoUrl | String | La URL de descarga de OSS para el video de evidencia. Este campo puede devolverse únicamente cuando el parámetro | https://aliyun-cloudauth.oss-aliyuncs.com/.webm |
faceAttack | String | Indica si se detectó un ataque de suplantación de vitalidad:
| N |
faceAttributeInfo | String | Detecta los atributos faciales del rostro principal en una imagen de entrada. El rostro principal es el más grande, nítido y cercano a la cámara. Los resultados de la detección se devuelven como una cadena de texto. Esta cadena le permite tomar decisiones sobre el contenido. Los campos que se devuelven se definen de la siguiente manera:
| |
faceAttackScore (Offline) | Double | La puntuación de riesgo de ataque de vitalidad, en un rango de 0 a 100. Actualmente, un LLM determina el riesgo de ataques de vitalidad, por lo que el concepto de puntuación de riesgo ya no aplica. Este campo está fuera de línea. | 80 |
guardRiskScore | Double | La puntuación de riesgo del dispositivo, en un rango de 0 a 100. Una puntuación más alta indica un mayor riesgo del dispositivo. | 90 |
deviceToken | String | El DeviceToken para Face Guard. Se devuelve cuando el módulo Face Guard está completamente integrado y sirve para consultar las operaciones API del lado del servidor de Face Guard y obtener los detalles de riesgo del dispositivo.
| e0c34a77f5ac40a5aa5e6ed20c35**** |
Result.ExtIdInfo
Nombre | Tipo | Descripción | Valor de ejemplo |
ocrIdPassed | String | El resultado final de la etapa de reconocimiento OCR del certificado:
| N |
ocrDocType | String | Se devuelve únicamente cuando el parámetro | CHN01001 |
ocrIdInfoData | Map<String,Object> | Los resultados detallados de cada página del certificado. La clave es el número de página y el valor contiene los campos de una sola página. Para obtener más información, consulte ocrIdInfoData.{page} single-page fields.
| |
ocrIdEditInfo | String | La información de los campos OCR del certificado que el usuario envía después de editarla en la página de resultados de OCR. Se devuelve cuando el cliente se configura para habilitar la página de edición de resultados de OCR (ShowOcrResult). | |
ocrStandardData | String | Los campos OCR estandarizados del certificado de identificación. Nota Se devuelve únicamente cuando el tipo de documento es compatible y | |
Campos de página única de ocrIdInfoData.{page}
Nombre | Tipo | Descripción | Valor de ejemplo |
idImage | String | La fotografía OCR del certificado en formato Base64. Se devuelve únicamente cuando | Base64 format |
ocrIdPassed | String | El resultado de OCR de la página actual del certificado:
| N |
ocrIdInfo | String | La información de los campos OCR de la página actual del certificado. Está vacía si el proceso de OCR falla. Los campos específicos varían según el tipo de certificado. Para conocer los detalles de los campos, consulte Certificate OCR fields. | |
spoofInfo | String | El resultado de la detección de suplantación, que incluye la decisión de riesgo y los tipos de riesgo: Nota La detección de suplantación de tarjetas se habilita únicamente cuando IdSpoof = Y en la solicitud Initialize. De lo contrario, spoofResult se establece en N y spoofType queda vacío.
| |
Result. ExtSourceInfo
Descripciones de los campos para la fuente de datos de Indonesia:
|
Campo |
Tipo |
Descripción |
|
govId |
Double |
La puntuación de comparación del número de certificado con la fuente de datos oficial. Un valor de |
|
fullName |
Double |
La puntuación de comparación del nombre. Un valor de |
|
dob |
Double |
La puntuación de comparación de la fecha de nacimiento. Un valor de |
|
selfiePhoto |
Double |
La puntuación de comparación de la selfie. Un valor mayor que |
|
liveness |
Double |
La puntuación de riesgo de vitalidad de la fuente de datos. Un valor mayor que |
|
imgManipulationScore |
Double |
La puntuación de riesgo de alteración de la imagen. Un valor mayor que |
Result.ExtInfo
Campo | Tipo | Descripción |
procedurePriority | String | El método real de degradación para la autenticación H5 móvil:
|
Result.SubCode authentication result subcode descriptions
Código de error | ¿Se factura el registro de autenticación? | Descripción y sugerencias |
200 | Sí | La autenticación se aprobó correctamente. |
204 | Sí | [Comparación facial] El rostro en vivo no coincide con la fotografía del certificado. Esto puede deberse a que la persona no corresponde al certificado o a que la calidad de la fotografía en vivo es baja. |
205 | Sí | [Ataque de prueba de vida] Se detectó un riesgo durante la detección de prueba de vida. |
206 | Sí | [Ataque de prueba de vida] Limitado por la directiva de negocio. Cuando se habilita el modo seguro, se comprueba la seguridad del dispositivo y del entorno. Si se detecta un riesgo potencial, la autenticación falla. Para solucionar este problema, siga estos pasos:
|
212 | Sí | [Solución de certificado] Se detectó un riesgo durante la detección antifalsificación del certificado. Es posible que se hayan producido operaciones de alto riesgo, como recaptura de pantalla, manipulación o fotocopiado. |
202 | Sí | [Fuente de datos autorizada] El número de certificado no existe en los datos de la fuente autorizada. |
207 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] Los datos de la fuente autorizada indican que la información personal coincide, pero el rostro no. |
214 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] Los datos de la fuente autorizada indican que el rostro coincide, pero la información personal no. |
215 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] Los datos de la fuente autorizada indican que ni la información personal ni el rostro coinciden. |
216 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] Los datos de la fuente autorizada indican que la prueba de vida de la fotografía es anómala. En la verificación de la fuente de datos de Indonesia, el valor |
217 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] Los datos de la fuente autorizada indican que la calidad de la imagen es anómala. |
218 | Sí, la fuente autorizada se factura de forma adicional | [Fuente de datos autorizada] El proceso de negocio se completó correctamente, pero los parámetros enviados a la fuente autorizada eran incorrectos. |
209 | Sí, la fuente autorizada no se factura | [Fuente de datos autorizada] La fuente autorizada presenta un comportamiento anómalo. |
Preguntas frecuentes
faceComparisonScore: ¿Cuál es la tasa de falsa aceptación (FAR) para el umbral de comparación facial y qué umbrales corresponden a cada FAR?
La tasa de falsa aceptación (FAR) es la probabilidad de que el sistema identifique erróneamente a una persona no coincidente como coincidente. Un valor de FAR más bajo indica mayor seguridad. Los umbrales que corresponden a cada valor de FAR son los siguientes:
|
FAR del 1 % |
FAR del 0.1 % |
FAR del 0.05 % |
FAR del 0.01 % (recomendado) |
FAR del 0,005 % |
FAR del 0,001 % |
|
57.3 |
76.4 |
81.8 |
90.0 |
90.5 |
91.3 |