Document

"Document" de JAAK facilita la autenticación y extracción de datos de documentos de identificación oficiales utilizando tecnología de Reconocimiento Óptico de Caracteres (OCR). Esta funcionalidad está diseñada para mejorar los procesos de verificación de identidad, proporcionando una solución eficiente y segura para las necesidades de autenticación digital.

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

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/v4/document/extract para procesar la imagen y obtener detalles del documento.
Endpoint de Verificación: Con los detalles obtenidos, usa el endpoint /api/v3/document/verify para verificar la autenticidad del documento.

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.
Asegúrate de que la fotografía esté disponible en el dispositivo desde el cual se realizará la prueba.
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

curl --request POST \
     --url https://sandbox.api.jaak.ai/api/v3/document/verify \
     --header 'Authorization: <token-de-acceso>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     			"imageBack":"base64Image",
          "imageFront":"base64Image"
        }'

{
    "document": "imagenBase64",
    "documentType": 4,
    "eventId": "string"
}

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.

curl -X POST "https://sandbox.api.jaak.ai/api/v2/document/verify" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -H 'Longitude: -70' \
     -H 'Latitude: 100' \
     -d '{...}'

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

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

{
    "eventId": "cfcd7ad3-508d-4a69-bfab-47112260295c",
    "requestId": "cfcd7ad3-508d-4a69-bfab-47112260295c",
    "status": true,
    "evaluation": 1,
    "message": "",
    "processTime": 340
}

OCR (Deprecado)

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

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

Descripción de la Solicitud

Petición

curl --request POST \
     --url https://sandbox.api.jaak.ai/api/v4/document/extract \
     --header 'Authorization: <token-de-acceso>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     					"documentFront": "base_64_document_back",
     					"documentBack": "base_64_document_back" // documento trasero opcional
          }'

Agrega localización

curl -X POST "https://sandbox.api.jaak.ai/api/v3/document/extract-both" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -H 'Longitude: -70' \
     -H 'Latitude: 100' \
     -d '{...}'

Descripción de los parámetros

Parámetro	Descripción
documentFront	Cadena codificada en Base64 que representa la imagen del documento.
documentBack	Cadena codificada en Base64 que representa la imagen del documento.

Respuesta

{
  "eventId": "d99fe2d2-c0c3-4396-bd97-a502b4c30fa3",
  "requestId": "d99fe2d2-c0c3-4396-bd97-a502b4c30fa3",
  "status": true,
  "message": "Document: context deadline exceeded",
  "documentType": {
    "type": "INE",
    "side": "front",
    "country": "Mexico",
    "icaoCode": "MEX"
  },
  "documentData": {
    "generalData": {
      "name": "John Doe",
      "birthdate": "1990-01-01",
      "gender": "Male",
      "nationality": "Mexican",
      "documentNumber": "ID123456789"
    },
    "mechanicalReadingZone": "IDMEX1836577170",
    "specificData": [
      {
        "field": "address",
        "value": "123 Main St"
      },
      {
        "field": "city",
        "value": "Mexico City"
      }
    ]
  },
  "documentMetadata": "NOMBRE SEXO...",
  "processingTime": "40848",
  "state": {
    "message": "Document is valid",
    "isExpired": false,
    "isUnderAge": false,
    "supportedDocument": true
  }
}

Descripción de los parámetros de respuesta.

Parámetro	Descripción
eventId	Identificador único del evento que originó la respuesta.
requestId	Identificador de la solicitud asociada con este evento. Generalmente es el mismo que el eventId.
status	Indica si la operación fue exitosa (true) o si hubo un error (false).
message	Mensaje que proporciona detalles sobre el estado del procesamiento o posibles errores que ocurrieron.
documentType	Información sobre el tipo de documento procesado, incluyendo el tipo, lado, país de emisión y código ICAO.
documentData	Datos extraídos del documento mediante OCR, que incluyen datos generales, zona de lectura mecánica y datos específicos.
documentMetadata	Datos crudos del OCR procesados. Contiene la información completa extraída del documento antes de ser formateada.
processingTime	Tiempo de procesamiento del documento en milisegundos.
state	Estado del documento tras el procesamiento, que indica si está expirado, si el titular es menor de edad y si el documento es compatible con el sistema.

Ejemplos de Solicitudes

{
    "documentFront": "base_64_document_back",
    "documentBack": "base_64_document_back" // documento trasero opcional
}

{
  "eventId": "d99fe2d2-c0c3-4396-bd97-a502b4c30fa3",
  "requestId": "d99fe2d2-c0c3-4396-bd97-a502b4c30fa3",
  "status": true,
  "message": "Document: context deadline exceeded",
  "documentType": {
    "type": "INE",
    "side": "front",
    "country": "Mexico",
    "icaoCode": "MEX"
  },
  "documentData": {
    "generalData": {
      "name": "John Doe",
      "birthdate": "1990-01-01",
      "gender": "Male",
      "nationality": "Mexican",
      "documentNumber": "ID123456789"
    },
    "mechanicalReadingZone": "IDMEX1836577170",
    "specificData": [
      {
        "field": "address",
        "value": "123 Main St"
      },
      {
        "field": "city",
        "value": "Mexico City"
      }
    ]
  },
  "documentMetadata": "NOMBRE SEXO...",
  "processingTime": "40848",
  "state": {
    "message": "Document is valid",
    "isExpired": false,
    "isUnderAge": false,
    "supportedDocument": true
  }
}

OCR V4 (Nuevo)

POST basePath/api/v4/document/extract

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

Descripción de la Solicitud

Petición

curl --request POST \
     --url https://sandbox.api.jaak.ai/api/v4/document/extract \
     --header 'Authorization: <token-de-acceso>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     					"imageFront": "<documento_frontal_en_b64>",
     					"imageBack": "<documento_posterior_en_b64>" // documento trasero opcional
          }'

Descripción de los parámetros

Parámetro	Descripción
imageFront	Cadena codificada en Base64 que representa la imagen del documento frontal.
imageBack	Cadena codificada en Base64 que representa la imagen del documento trasera.

Agrega localización

curl -X POST "https://sandbox.api.jaak.ai/api/v4/document/extract" \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H 'Authorization: Bearer <api_key>' \
     -H 'Longitude: -70' \
     -H 'Latitude: 100' \
     -d '{...}'

Respuesta

{
  "eventId": <valor_string_eventId>,
  "requestId": <valor_string_requestId>,
  "status": <valor_string_status>,
  "content": {
    "data": {
      "personal": {
        "firstName": <valor_string_firstName>,
        "secondName": <valor_string_secondName>,
        "surname": <valor_string_surname>,
        "motherSurname": <valor_string_motherSurname>,
        "fullName": <valor_string_fullName>,
        "sex": <valor_string_sex>,
        "dateOfBirth": <valor_string_dateOfBirth>,
        "face": <valor_string_face>,
        "placeOfBirth": <valor_string_placeOfBirth>,
        "nationality": <valor_string_nationality>,
        "maritalStatus": <valor_string_maritalStatus>,
        "extra": {
          "ocr": <valor_string_ocr>,
          "registerYear": <valor_string_registerYear>,
          "rfc": <valor_string_rfc>
        }
      },
      "address": {
        "fullAddress": <valor_string_fullAddress>,
        "postalCode": <valor_string_postalCode>,
        "extra": {
          "street": <valor_string_street>,
          "externalNumber": <valor_string_externalNumber>,
          "internalNumber": <valor_string_internalNumber>,
          "neighborhood": <valor_string_neighborhood>,
          "city": <valor_string_city>,
          "state": <valor_string_state>
        }
      },
      "document": {
        "type": <valor_string_type>,
        "side": <valor_string_side>,
        "country": {
          "name": <valor_string_country_name>,
          "isoAlpha3Code": <valor_string_isoAlpha3Code>,
          "isoAlpha2Code": <valor_string_isoAlpha2Code>,
          "icaoCode": <valor_string_icaoCode>
        },
        "number": <valor_string_number>,
        "personalIdNumber": <valor_string_personalIdNumber>,
        "additionalNumber": <valor_string_additionalNumber>,
        "dateOfIssue": <valor_string_dateOfIssue>,
        "expiration": {
          "date": <valor_string_expiration_date>,
          "isPermanent": <valor_boolean_isPermanent>
        },
        "issuingAuthority": <valor_string_issuingAuthority>,
        "extra": {}
      }
    }
  },
  "processingTime": <valor_string_processingTime>,
  "state": {
    "message": <valor_string_message>,
    "documentCompleteSides": <valor_boolean_documentCompleteSides>
  }
}

Descripción de los parámetros de respuesta.

Parámetro	Descripción	Tipo de Dato
`eventId`	Identificador único del evento.	`string`
`requestId`	Identificador único de la solicitud.	`string`
`status`	Estado de la operación (`SUCCESS`, `FAILURE`).	`string`
`content`	Contenedor de los datos principales.	`object`
`content.data`	Datos detallados de la respuesta.	`object`
`content.data.personal`	Información personal del individuo.	`object`
`content.data.personal.firstName`	Primer nombre.	`string`
`content.data.personal.secondName`	Segundo nombre.	`string`
`content.data.personal.surname`	Apellido paterno.	`string`
`content.data.personal.motherSurname`	Apellido materno.	`string`
`content.data.personal.fullName`	Nombre completo.	`string`
`content.data.personal.sex`	Sexo (`H` para hombre, `M` para mujer).	`string`
`content.data.personal.dateOfBirth`	Fecha de nacimiento (`DD/MM/YYYY`).	`string`
`content.data.personal.face`	Imagen del rostro (si aplica).	`string`
`content.data.personal.placeOfBirth`	Lugar de nacimiento.	`string`
`content.data.personal.nationality`	Nacionalidad.	`string`
`content.data.personal.maritalStatus`	Estado civil.	`string`
`content.data.personal.extra`	Información adicional.	`object`
`content.data.personal.extra.ocr`	Código OCR del documento.	`string`
`content.data.personal.extra.registerYear`	Año de registro del documento.	`string`
`content.data.personal.extra.rfc`	Registro Federal de Contribuyentes (RFC).	`string`
`content.data.address`	Dirección del individuo.	`object`
`content.data.address.fullAddress`	Dirección completa.	`string`
`content.data.address.postalCode`	Código postal.	`string`
`content.data.address.extra`	Información adicional de la dirección.	`object`
`content.data.address.extra.street`	Calle.	`string`
`content.data.address.extra.externalNumber`	Número exterior.	`string`
`content.data.address.extra.internalNumber`	Número interior.	`string`
`content.data.address.extra.neighborhood`	Colonia o barrio.	`string`
`content.data.address.extra.city`	Ciudad.	`string`
`content.data.address.extra.state`	Estado.	`string`
`content.data.document`	Información del documento de identificación.	`object`
`content.data.document.type`	Tipo de documento (`TYPE_VOTER_ID`, etc.).	`string`
`content.data.document.side`	Lado del documento (`FRONT`, `BACK`).	`string`
`content.data.document.country`	Información del país de emisión.	`object`
`content.data.document.country.name`	Nombre del país.	`string`
`content.data.document.country.isoAlpha3Code`	Código ISO Alpha-3 del país.	`string`
`content.data.document.country.isoAlpha2Code`	Código ISO Alpha-2 del país.	`string`
`content.data.document.country.icaoCode`	Código ICAO del país.	`string`
`content.data.document.number`	Número de documento.	`string`
`content.data.document.personalIdNumber`	Número de identificación personal.	`string`
`content.data.document.additionalNumber`	Número adicional.	`string`
`content.data.document.dateOfIssue`	Fecha de emisión del documento.	`string`
`content.data.document.expiration`	Información sobre la expiración.	`object`
`content.data.document.expiration.date`	Fecha de expiración.	`string`
`content.data.document.expiration.isPermanent`	Indica si el documento es permanente.	`boolean`
`content.data.document.issuingAuthority`	Autoridad emisora del documento.	`string`
`content.data.document.extra`	Información adicional del documento.	`object`
`processingTime`	Tiempo de procesamiento en milisegundos.	`string`
`state`	Estado de la respuesta.	`object`
`state.message`	Mensaje de estado.	`string`
`state.documentCompleteSides`	Indica si el documento tiene ambos lados.	`boolean`

Ejemplos de Solicitudes

{
    "documentFront": "base_64_document_back",
    "documentBack": "base_64_document_back" // documento trasero opcional
}

      {
  "eventId": "9ef67e72-0895-4fcb-a5dd-eba8c9088f9f",
  "requestId": "9ef67e72-0895-4fcb-a5dd-eba8c9088f9f",
  "status": "SUCCESS",
  "content": {
    "data": {
      "personal": {
        "firstName": "JESUS",
        "secondName": "FRANCISCO",
        "surname": "SERRANO",
        "motherSurname": "CAMPOS",
        "fullName": "JESUS FRANCISCO SERRANO CAMPOS",
        "sex": "H",
        "dateOfBirth": "09/05/1996",
        "face": "",
        "placeOfBirth": "",
        "nationality": "MEXICAN",
        "maritalStatus": "",
        "extra": {
          "ocr": "2270097833499",
          "registerYear": "2014 01",
          "rfc": "SECJ960509SF9"
        }
      },
      "address": {
        "fullAddress": "C GUILLERMO PRIETO 328 C\nCOL CENTRO 38900\nSALVATIERRA, GTO.",
        "postalCode": "38900",
        "extra": {
          "street": "C GUILLERMO PRIETO",
          "externalNumber": "328 C",
          "internalNumber": "Not provided",
          "neighborhood": "COL CENTRO",
          "city": "SALVATIERRA,",
          "state": "GTO."
        }
      },
      "document": {
        "type": "TYPE_VOTER_ID",
        "side": "FRONT",
        "country": {
          "name": "MEXICO",
          "isoAlpha3Code": "MEX",
          "isoAlpha2Code": "MX",
          "icaoCode": "ID"
        },
        "number": "169834708",
        "personalIdNumber": "SECJ960509HGTRMS00",
        "additionalNumber": "SRCMJS96050911H700",
        "dateOfIssue": "01/01/2018",
        "expiration": {
          "date": "31/12/2028",
          "isPermanent": false
        },
        "issuingAuthority": "",
        "extra": {}
      }
    }
  },
  "processingTime": "3887",
  "state": {
    "message": "",
    "documentCompleteSides": true
  }
}

Integraciones

Ejemplo HTML y JS

Utilizando el Servicio de Documentos

Paso 1: Configura la Interfaz Web

Implementa el HTML y JavaScript como se proporciona para crear una interfaz de usuario simple para capturar imágenes de documentos directamente desde la cámara del dispositivo o el sistema de archivos.

Paso 2: Captura y Convierte el Documento

Los usuarios seleccionan o capturan una imagen del documento utilizando la entrada de archivo. Luego, la imagen se convierte en una cadena base64 utilizando JavaScript, facilitando la transmisión de datos de imagen a través de solicitudes de red.

Paso 3: Envía la Imagen para Procesamiento OCR

La cadena codificada en base64 se envía al endpoint /api/v2/document/extract utilizando una solicitud POST fetch. Asegúrate de manejar la solicitud en el servidor para extraer datos textuales de la imagen y posiblemente verificarla contra formatos conocidos.

Paso 4: Analiza la Respuesta

El servidor procesa la imagen y devuelve los resultados de OCR, que pueden incluir datos de texto extraídos del documento y cualquier otro metadato relevante. Estos resultados luego se muestran o registran para acciones adicionales.

Paso 5: Procesamiento Adicional

Dependiendo de las necesidades de la aplicación, los pasos adicionales podrían incluir la verificación de la autenticidad del documento, almacenar los resultados o integrarlos en flujos de trabajo de procesamiento de datos más grandes.

Para obtener documentación detallada de los endpoints de API y funcionalidades adicionales, consulta la Documentación de API.

document.getElementById('uploadButton').addEventListener('click', function() {
    const fileInput = document.getElementById('documentInput');
    if (fileInput.files.length > 0) {
        const file = fileInput.files[0];
        const reader = new FileReader();

        reader.onload = () => {
            const base64String = reader.result;
            console.log('Base64 String of Image:', base64String);

            // Optionally, send this base64String to the server
            fetch('https://sandbox.api.jaak.ai/api/v2/document/extract', {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json'
                    'Authorization': 'Bearer <your_token>'
                },
                body: JSON.stringify({ document: base64String })
            })
            .then(response => response.json())
            .then(data => {
                console.log('OCR Results:', data);
                
              const documentType = data.documentType;
              
              //You can use Verify Document API here!
            })
            .catch(error => {
                console.error('Error sending image to server:', error);
            });
        };

        reader.readAsDataURL(file);
    } else {
        console.log('Please select a file to upload.');
    }
});

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Document Capture and OCR</title>
</head>
<body>
<input type="file" id="documentInput" accept="image/*" capture="environment">
<button id="uploadButton">Upload and Analyze</button>
<script src="app.js"></script>
</body>
</html>