Global ID Recognition API
Referencia de la API Global ID Recognition, que lee y verifica documentos de identidad a partir de imágenes del anverso y reverso, país emisor y tipo de documento.
Descripción General de la API
La API de Global ID Recognition proporciona una herramienta potente para el procesamiento de documentos de identificación a nivel mundial con las siguientes capacidades:- Soporte Mundial: Procese documentos de identificación de múltiples países
- Reconocimiento Automático: Detecte automáticamente el tipo de identificación y el país emisor
- Tecnología OCR: Reconocimiento óptico de caracteres avanzado para extracción de texto
- Extracción de Datos: Extraiga datos estructurados de documentos de identificación
- Verificación: Verifique la autenticidad y validez del documento
- Soporte Multi-Formato: Maneje varios formatos de documentos de identificación
Parámetros de Solicitud
Parámetros Requeridos
- idImage: Imagen del lado frontal del documento de identificación en formato base64
- issuingCountry: El Código de País ISO 3 Alpha del país emisor del documento de identificación
- idType: El tipo del documento de identificación
Parámetros Opcionales
- idBackImage: Imagen del lado posterior del documento de identificación en formato base64
- callbackUrl: La URL donde se enviarán los resultados del reconocimiento al completarse
Autenticación
- x-api-key: Clave API esencial para fines de autenticación y control de acceso
Formato de Respuesta
El contenido deresult es idéntico en ambos modos de procesamiento. Solo cambia la envoltura.
- apiType: valor fijo
id_recognition - transactionId: identificador único de cada solicitud
- result: el resultado del reconocimiento
- document_type: tipo de documento reconocido. Si el motor no puede determinarlo, se usa
<issuingCountry>.<idType>(por ejemploKOR.drvlic) - review_front: indica si el anverso produjo un resultado
- review_back: indica si el reverso produjo un resultado. Presente solo si se envió
idBackImage - data.raw: salida en bruto del motor por campo. Cada campo puede incluir
- value: el valor reconocido, tal como lo devuelve el motor (string, number o boolean)
- score: puntuación de confianza 0-100. Presente solo si el motor la devuelve para ese campo
- accepted: resultado de la validación. Presente solo si el motor lo devuelve para ese campo
- coordinates: bounding box en la imagen recortada, con los vértices
first,second,thirdyfourth - original_coordinates: bounding box en la imagen original subida, antes del recorte
- data.ocr: los valores OCR finales ya corregidos. Cada clave
ocr_*puede venir acompañada deaccepted_ocr_*
- document_type: tipo de documento reconocido. Si el motor no puede determinarlo, se usa
accepted_ocr_* antes de confiar en un valor.Países y Tipos de Identificación Soportados
Países Principales
- USA: Estados Unidos
- CAN: Canadá
- MEX: México
- BRA: Brasil
- ARG: Argentina
- GBR: Reino Unido
- DEU: Alemania
- FRA: Francia
- ESP: España
- ITA: Italia
- KOR: Corea del Sur
- JPN: Japón
- CHN: China
- AUS: Australia
- NZL: Nueva Zelanda
Tipos de Identificación
- government_id: Un documento de identificación oficial emitido por un gobierno, típicamente utilizado para verificar la identidad de una persona
- passport: Un documento de viaje oficial emitido por un gobierno, que certifica la identidad y nacionalidad del titular, utilizado principalmente para viajes internacionales
- drivers_license: Un documento oficial que permite a una persona específica operar uno o más tipos de vehículos motorizados, como motocicletas, automóviles, camiones o autobuses
- residence_permit: Un documento oficial que permite a una persona extranjera residir en un país durante un período determinado, típicamente emitido por la autoridad de inmigración
- vehicle_registration_certificate: Un documento oficial que proporciona prueba de registro de un vehículo, incluyendo detalles sobre el vehículo y el propietario
- visa: Un respaldo oficial colocado en un pasaporte que indica que el titular puede entrar, salir o permanecer durante un período específico en un país
- aadhaar: Un número de identificación único de 12 dígitos emitido por el gobierno indio a los residentes de India, basado en sus datos biométricos y demográficos
- pancard: Una tarjeta de número de cuenta permanente (PAN) emitida por el gobierno indio a personas y entidades, utilizada principalmente para fines fiscales
Casos de Uso
- Procesos KYC: Optimice la verificación de identidad del cliente
- Banca: Verifique la identidad del cliente para apertura de cuentas
- Viajes: Procese documentos de viaje y visas
- Empleo: Verifique la identidad del empleado y permisos de trabajo
- Servicios Gubernamentales: Procese documentos de identificación oficiales
Modos de Procesamiento
callbackUrl es opcional. Enviarlo o no determina cómo se recibe el resultado.
Síncrono: sin callbackUrl
La conexión permanece abierta hasta que termina el procesamiento y el resultado llega en el cuerpo del HTTP 200.statusCode ni webhookUrl.Asíncrono: con callbackUrl
El HTTP 200 que se devuelve de inmediato solo confirma la recepción.callbackUrl. Ese contenido lleva el mismo result
más dos campos adicionales:
idImage, issuingCountry o idType, formato de imagen no
válido, o país o tipo de documento no admitidos) se devuelven como HTTP 400 inmediato en ambos modos.Requisitos de Imagen
Tamaño de Archivo
- Recomendado: Menos de 10MB
- Máximo: 50MB
Calidad de Imagen
- Resolución: Se recomienda un mínimo de 300 DPI
- Formato: Las imágenes de alto contraste y bien iluminadas funcionan mejor
- Orientación: El documento debe estar correctamente orientado
Formatos Soportados
- JPEG (.jpg, .jpeg)
- PNG (.png)
Manejo de Errores
El código de estado 400 indica que la solicitud fue inaceptable, a menudo debido a la falta de un parámetro requerido. En operaciones asíncronas, donde se proporciona callbackUrl, el error se detecta durante la validación de la solicitud.Tipo de errorCode
La siguiente tabla muestra los errorCodes específicos devueltos por la API:callbackUrl es opcional en este endpoint. Omitirlo selecciona el procesamiento síncrono;
no es un parámetro obligatorio que falte.Documentos relacionados
Descripción General de Global ID Recognition
Mejores Prácticas para Imágenes de Identificación
Ejemplos de Respuesta de Callback
Cuerpo
Image of the front side of the ID document in base64 format. Base64 encoded characters in the payload must not include the MIME type. For example, if the encoded base64 characters are "image/png;base64,/9j/2wBDABQODxIP...", then remove "image/png;base64," and send only the encoded data "/9j/2wBDABQODxIP...".
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
Respuesta
Successful ID recognition