Document para Android

Empezando

Para proceder, es indispensable generar una clave API con un tiempo de expiración definido.

Este proceso puede completarse fácilmente mediante el panel de administrado. Esto garantiza un acceso seguro y gestionado a los recursos necesarios durante el tiempo estipulado.

Para más detalles, consulta la documentación específica de cada método disponible a través de los siguientes enlaces:

Generación de clave API el panel de administrador API Keys Panel de Administrador

Tipos de Documentos Soportados

Los tipos de documentos que el sistema acepta están dictados por la siguiente enumeración, lo cual es importante ya que el número documentType es requerido al verificar un documento a través del endpoint /api/v2/document/verify:

UNDEFINED = -1
INE_BACK = 0
PASSPORT = 1
IFE_BACK = 2
IFE_FRONT = 3
INE_DFE_FRONT = 4
INE_GH_FRONT = 5
INE_ENG_FRONT = 6
COLOMBIAN_ID_FRONT = 9
COLOMBIAN_ID_BACK = 10
COLOMBINA_YELLOW_ID_FRONT = 11
COLOMBINA_YELLOW_ID_BACK = 12

Proceso OCR y Verificación con el Servicio de Documentos

Para utilizar el servicio de OCR y autenticar un documento de identificación oficial, sigue estos pasos:

Captura la Imagen: Obtén una foto o imagen del documento.
Codifica en Base64: Convierte la imagen a una cadena en formato Base64. Para mas informacion sobre que es el formato Base64 ve a Base64.
Endpoint de Extracción: Usa el endpoint /api/v2/document/extract para procesar la imagen y obtener detalles del documento.
Endpoint de Verificación: Con los detalles obtenidos, usa el endpoint /api/v2/document/verify para verificar la autenticidad del documento.

El endpoint /api/v2/document/extract determinará el tipo de documento basado en la imagen proporcionada.

Es esencial realizar primero una extracción para obtener los detalles del documento antes de usar el endpoint /api/v2/document/verify para la verificación.

Requisitos

Debes tener una fotografía del documento de identificación oficial, tanto delantera como trasera. Para pasaportes, la fotografía trasera no es necesaria.
Necesitas una clave API válida de una empresa activa y configurarla como Bearer Token en el encabezado de tu solicitud.

Verify

POST basePath/api/v3/document/verify

Este endpoint verifica la veracidad de un documento, validando si una imagen es real o falsa. Sus resultados son de 0 a 1.

Descripción de la Solicitud

Petición

@POST("api/v3/document/verify")
    suspend fun verify(@Header("Authorization") auth: String, @Body request: VerifyRequest): Response<VerifyResponse>

data class VerifyRequest(
       @SerializedName("imageFront") val document: String, //base64
			 @SerializedName("imageBack") val document2: String?, //base64
			 @SerializedName("documentType") val documentType: Boolean
)

Agrega localización

Si deseas agregar localización a la ejecución del evento agrega las cabeceras Longitude y Latitude con los valores numericos de la ubicación de la cual se esta ejecutando tu petición.

 @POST("api/v2/document/verify")
    suspend fun suspectVerify(@Header("Authorization") auth: String, @Header("Longitude") longitude: String, @Header("Latitude") latitude: String, @Body request: VerifyRequest): Response<VerifyResponse>

Descripción de los parámetros

Parámetro	Descripción
document	Cadena codificada en Base64 que representa la imagen del documento.
documentType	Tipo de documento a validar.
eventId	Identificador del evento.

Respuesta

{
  "document": {
    "country": "string",
    "icaoCode": "string",
    "side": "string",
    "type": "string",
    "evaluation": "SUCCESS | WARNING | REJECTED"
  },
  "eventId": "string",
  "processTime": "number",
  "requestId": "string",
  "state": {
    "dataConsistent": "boolean",
    "documentCompleteSides": "boolean",
    "documentLiveness": "boolean",
    "documentValidity": "boolean",
    "handPresence": "boolean",
    "imageQuality": "boolean",
    "message": "string",
    "securityFeatures": "boolean"
  }
}

data class VeifyResponse(
    @SerializedName("document") val document: Document,
    @SerializedName("documentType") val documentType: Int,
    @SerializedName("eventId") val eventId: String,
    @SerializedName("processTime") val processTime: Long,
    @SerializedName("requestId") val requestId: String,
    @SerializedName("state") val state: State
)

data class Document(
    @SerializedName("country") val country: String,
    @SerializedName("icaoCode") val icaoCode: String,
    @SerializedName("side") val side: String,
    @SerializedName("type") val type: String,
    @SerializedName("evaluation") val evaluation: String
)

data class State(
    @SerializedName("dataConsistent") val dataConsistent: Boolean,
    @SerializedName("documentCompleteSides") val documentCompleteSides: Boolean,
    @SerializedName("documentLiveness") val documentLiveness: Boolean,
    @SerializedName("documentValidity") val documentValidity: Boolean,
    @SerializedName("handPresence") val handPresence: Boolean,
    @SerializedName("imageQuality") val imageQuality: Boolean,
    @SerializedName("message") val message: String,
    @SerializedName("securityFeatures") val securityFeatures: Boolean
)

Descripción de los parámetros de respuesta.

Parámetro	Tipo	Descripción
document	`object`	Información del documento procesado.
document.country	`string`	Código del país asociado al documento.
document.icaoCode	`string`	Código ICAO del documento.
document.side	`string`	Lado del documento (por ejemplo, "front" o "back").
document.type	`string`	Tipo de documento (por ejemplo, "passport" o "ID card").
document.evaluation	`string`	Resultado de la evaluación: `SUCCESS`, `WARNING`, o `REJECTED`.
eventId	`string`	Identificador único del evento.
processTime	`number`	Tiempo de procesamiento en milisegundos.
requestId	`string`	Identificador único de la solicitud.
state	`object`	Estado general de la validación del documento.
state.dataConsistent	`boolean`	Indica si los datos son consistentes.
state.documentCompleteSides	`boolean`	Indica si el documento tiene ambos lados completos.
state.documentLiveness	`boolean`	Indica si el documento pasó la validación de "liveness".
state.documentValidity	`boolean`	Indica si el documento es válido.
state.handPresence	`boolean`	Indica si se detectó la presencia de manos en el escaneo del documento.
state.imageQuality	`boolean`	Indica si la calidad de la imagen es adecuada.
state.message	`string`	Mensaje adicional sobre el estado del documento.
state.securityFeatures	`boolean`	Indica si se validaron las características de seguridad del documento.

Ejemplos de Solicitudes

{
    "document": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAYGBgYHBgcICAcKCwoLCg",
    "documentType": 4,
    "eventId": "69c0b6be-18aa-4ac7-89e4-32611ea498cf"
  }

{
  "document": {
    "country": "Mexico",
    "icaoCode": "MEX",
    "side": "front",
    "type": "passport",
    "evaluation": "SUCCESS"
  },
  "eventId": "123456789",
  "processTime": 1500,
  "requestId": "987654321",
  "state": {
    "dataConsistent": true,
    "documentCompleteSides": true,
    "documentLiveness": true,
    "documentValidity": true,
    "handPresence": true,
    "imageQuality": true,
    "message": "Document verified successfully",
    "securityFeatures": true
  }
}

OCR

POST basePath/api/v3/document/extract-both

Este endpoint hace la extraccion de la informacion de un documento.