Documentos de Académico
Documentos de Profesional
Documentos de Cultura
TOC Autocaptura
Manual de integración
Descripción de funcionalidades y modo de uso de la tecnología de captura
automática de documentos
─
Responsables: Juan Pablo Muñoz
Javier Rodríguez
Pablo Rodríguez
Contacto: devs@toc.cl
CONFIDENCIAL Página 2 de 18
Funcionamiento
TOC Autocaptura obtiene imágenes de documentos de identidad por medio de un proceso en el
que el usuario posiciona la cámara del dispositivo frente al documento en cuestión. El
procedimiento transcurre de la siguiente manera:
1. En la aplicación cliente, el usuario debe seleccionar el tipo de documento que desea
fotografiar (cédula chilena antigua, cédula chilena nueva, pasaporte, etc).
2. Desde el backend de la aplicación se debe enviar una solicitud al Session Manager para
obtener un id de sesión.
3. La aplicación cliente debe invocar el SDK de TOC (con el id de sesión previamente
obtenido), que a su vez levanta la cámara del dispositivo. Es necesario indicar la cara del
documento que se fotografiará.
4. En la pantalla del dispositivo se despliega la imagen de la cámara con un overlay blanco
que indica dónde debe situarse el documento.
5. Al ubicar el documento en la posición indicada, comenzará el proceso de detección en
base a un análisis de los cuadros captados por la cámara. El overlay cambiará de color
blanco a azul una vez se haya detectado la presencia de un documento en el cuadro, y
tomará un color verde cuando la fotografía obtenida esté correctamente enfocada y sea
nítida.
6. Si se trata de un documento de dos caras, se debe repetir el proceso con el reverso de la
cédula.
7. Una vez completada la detección se obtiene un capture_token que identifica de manera
única a la captura realizada. Este token puede ser utilizado para consumir la API de
verificación facial de TOC.
CONFIDENCIAL Página 3 de 18
Sistema de sesiones
El componente de auto captura funciona en base a sesiones. Cada sesión tiene una duración de
15 minutos máximo, y de cada sesión se obtendrá a lo más una captura frontal y una trasera, y
opcionalmente, una transacción de Liveness exitosa.
En primer lugar, se debe obtener un identificador de sesión. Para esto la aplicación, desde el lado
del servidor, debe enviar un POST request a la API de adquisición de id de sesión, en el siguiente
endpoint:
https://sandbox-api.7oc.cl/session-manager/v1/session-id
1
Para mayor información, referirse al manual de integración de TOC Liveness.
CONFIDENCIAL Página 4 de 18
con valor ‘true’. En request multipart/form-data el valor debe ser un string; si el
request es application/json, debe enviarse como booleano.
5) mode: (Opcional1) Complejidad del Liveness Detection que se desea implementar.
Formato de la respuesta
Si el proceso es exitoso, la respuesta será un objeto JSON con dos parámetros:
● session_id: String con el id de sesión creado.
● status: Un código de estado para la transacción de solicitud de id de sesión. Si la
generación de session_id es exitosa, el estado será 200.
Si algo falla durante el proceso, solo se obtendrá el parámetro status, con el código
correspondiente al problema que se produjo. Los posibles valores para el campo status están
definidos en la T abla de estados del Session Manager.
Ejemplos de consumo
Consumo en Node.js del Session Manager:
const request = require("request");
Consumo en PHP del Session Manager:
<?php
$apiKey = 'API_KEY';
$url = 'https://sandbox-api.7oc.cl/session-manager/v1/session-id';
$post = array('apiKey'=>$apiKey , 'autocapture'=>'true');
$curl = curl_init();
CONFIDENCIAL Página 5 de 18
CONFIDENCIAL Página 6 de 18
Librerías
Sólo se requiere agregar la librería JS de Autocaptura. Ejemplo:
<script
src="https://sandbox-web-plugins.s3.amazonaws.com/autocapture/autocapture.js"></scr
ipt>
Implementación
La implementación se hace sobre un componente vacío (un div por ejemplo). Existen dos
inicializadores, utilizando Javascript puro (recomendado) y JQuery.
JAVASCRIPT
TOCautocapture(container, options)
2
h
ttps://webrtc.org/
CONFIDENCIAL Página 7 de 18
JQUERY
.autocapture(options)
Ambas invocaciones son idénticas. La función de jQuery se aplica sobre un componente div
vacío. Los parámetros que reciben son:
● container: (sólo en JS puro) componente div vacío en la página, donde se cargará el
plugin. Puede ser una string que contenga la ID del div, o puede ser el contenedor
obtenido mediante las funciones document.getElementById o
document.querySelector.
● options: JSON que recibe opciones para configurar el plugin.
○ locale: Determina el idioma a utilizar (“es” por defecto).
○ session_id: El ID para poder invocar la sesión de captura automática.
○ document_type: String que indica el tipo de documento al cual se le va a hacer la
captura automática (ver Apéndice A).
○ document_side: String que indica el lado del documento a capturar. Las opciones
son “front” y “back”.
○ callback: Función a ejecutar una vez realizada la captura del documento. La
función recibe dos parámetros:
■ captured_token: String que contiene el token de la transacción, y
funciona como imagen para la utilización de la API Facial.
■ image: String que posee la imagen en base64 capturada.
Por defecto genera un a lert que muestra el token de la transacción.
○ failure: Función a ejecutar en caso que la captura no se haya podido realizar,
permitiendo seguir un flujo de error. Recibe un parámetro error que es una string
con el código de error que se ha entregado. Por defecto genera un
alert(“FAILURE”).
○ retry_on_timeout: (opcional) booleano que cuando es true, muestra las
instrucciones de ayuda en vez de terminar el flujo de autocaptura. Por defecto es
false.
○ no_instructions: (opcional) booleano que cuando es true, oculta las
instrucciones mostradas en la parte inferior de la interfaz. Por defecto es false.
○ alt_server: (Se debe setear para el paso a producción) Setea el endpoint del
servidor al cual el plugin se comunica. Si no se define, se utilizará por defecto el
servidor sandbox de TOC.
○ url_lbac: (Se debe setear para el paso a producción) Setea el endpoint del
servidor al cual el plugin entrega los resultados una vez obtenida la captura. Si no
se define, se utilizará por defecto el servidor sandbox de TOC.
Para el ambiente productivo, se deben setear con los siguientes valores:
"alt_server": "https://prod-capture.tocws.com"
CONFIDENCIAL Página 8 de 18
"url_lbac": "https://prod-api.7oc.cl/auto-capture/data/v2"
○ http: (Opcional) Booleano. Si es true, ignora la comprobación de dominio seguro.
USAR SÓLO EN AMBIENTES DE DESARROLLO.
Ejemplo de implementación con Javascript puro:
TOCautocapture('container', {
locale: "es",
session_id: "SESSION ID HERE",
document_type: "CHL2",
document_side: "front",
callback: function(captured_token, image){ alert(token); },
failure: function(error){ alert(error); }
}
);
Ejemplo de implementación con jQuery:
$('#container').autocapture({
locale: "es",
session_id: "SESSION ID HERE",
document_type: "CHL2",
document_side: "front",
callback: function(captured_token, image){ alert(token); },
failure: function(error){ alert(error); }
}
);
Locales (idiomas)
Los archivos de locale son archivos JSON con traducciones de las frases en la interfaz.
Actualmente hay dos locales implementados:
● “es”: español.
● “en”: inglés.
Compatibilidad
● PC/Android: Todos los navegadores compatibles con WebRTC.
● Mac: Navegadores compatibles con WebRTC. Se recomienda el uso de Safari 11.
CONFIDENCIAL Página 9 de 18
● iPhone: Safari 11 en adelante es obligatorio. No existe otro navegador compatible con
WebRTC.
Consideraciones
● Para mejor visualización, es recomendado que el contenedor del plugin ocupe >50% del
ancho de la pantalla en resoluciones menores a 1200px, y menos del 50% del ancho de la
pantalla en resoluciones mayores.
● En dispositivos móviles la captura solo se puede realizar de forma horizontal. Idealmente
el contenedor debe ocupar el mayor espacio posible de la pantalla (sobre 80% del ancho).
La interfaz siempre estará en landscape, incluso en portrait (interfaz se mostrará de lado).
● Dado que el plugin hace uso de componentes de video, asegurar que en la página donde
se ejecuta el plugin no hay cámaras en funcionamiento.
● Es requerido implementar el plugin en dominios seguros (https) de modo de asegurar la
mayor compatibilidad con dispositivos, y el mejor funcionamiento del plugin y la cámara.
El plugin no funcionará en ambientes de producción a menos que esté en dominio seguro,
mostrando un mensaje en pantalla y necesitando recargar la página para poder continuar.
● Si se desea hacer más de una captura automática en la misma página, es recomendado
vaciar el componente utilizado (container.innerHTML = “” o .empty()) antes de
volver a cargar la segunda invocación.
CONFIDENCIAL Página 10 de 18
Una vez las credenciales sean ingresadas en el build.gradle, es necesario importar el
repositorio de Maven. Esto se hace en el build.gradle del módulo donde se quiere utilizar la
librería. Para importar la librería solo se necesita agregar la siguiente línea al build.gradle del
módulo:
implementation 'cl.toc.AutoCapture:sdk:1.10.14'
Si las credenciales ingresadas en el paso anterior no son correctas, el proyecto no podrá obtener
esta librería y el proceso de autocaptura no funcionará.
Implementación
Una vez la librería esté integrada al proyecto, solo se requiere llamar a la actividad que maneja el
componente de Autocaptura. Esto se hace al enviar un intent a la clase CaptureActivity y
enviando como parte del intent las variables session_id, document_side y document_type.
Para el ambiente productivo, se deben agregar y asignar variables url_wsac y url_lbac con
los siguientes valores:
"url_wsac ": "https://prod-capture.tocws.com"
Si no se especifican estas variables, el servicio utilizará por defecto el ambiente Sandbox de TOC.
También es posible activar un botón para prender y apagar el flash del dispositivo, esto se logra
con el parámetro:
“show_flash_button”: True
Dónde ‘True’ es un Boolean.
Código de ejemplo:
Intent intent = new Intent(Disclaimer.this, CaptureActivity.class);
intent.putExtra("session_id", "YOUR_SESSION_ID");
intent.putExtra("document_side", "THE_DOCUMENT_SIDE");
intent.putExtra("document_type", "THE_DOCUMENT_TYPE");
startActivityForResult(intent, "YOUR_INTENT_CODE");
CONFIDENCIAL Página 11 de 18
Es preciso llamar a la actividad con un startActivityForResult, ya que una vez terminado el
proceso de Auto captura, la actividad entregará el token y la imagen en base64 con el Flag
“URL_SAFE”, asociadas al proceso. Para adquirir este token y la imagen, basta con obtenerlo
desde el intent como se muestra a continuación:
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if(requestCode == "YOUR_INTENT_CODE" && resultCode == 200) {
String toc_token = data.getStringExtra("capture_token");
String image = data.getStringExtra(“image”);
}
}
Se debe tener en cuenta que la librería de Auto captura utiliza permisos de cámara, los cuales
deben ser solicitados al usuario en la aplicación. El siguiente código permite solicitar estos
permisos de forma programática:
if (ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) !=
PackageManager.PERMISSION_GRANTED) {
ActivityCompat.requestPermissions(this, new
String[]{Manifest.permission.CAMERA}, 1);
}
Se requiere corroborar que los permisos fueron exitosamente aceptados antes de iniciar el
proceso de Auto captura.
Compatibilidad
La librería TOC Auto captura ha sido probada satisfactoriamente en sistemas Android 5.0 y
superiores, y funciona en dispositivos cuya cámara cuenta con autofoco.
C. Cliente iOS
Para aplicaciones iOS, el SDK de auto captura se ofrece como un iOS framework. A continuación
se describen los pasos para integrar la herramienta en una aplicación:
CONFIDENCIAL Página 12 de 18
Configuración
En el archivo I
nfo.plist del proyecto de la aplicación agregar:
CONFIDENCIAL Página 13 de 18
Key Type Value
Implementación
Para utilizar auto captura iOS primero se debe importar el framework a la clase que lo utilizará:
Objective C:
#import "AutoCapture.framework/Headers/AutoCapture-Swift.h"
Swift:
import AutoCapture
Luego se debe agregar el delegado c
aptureDelegate:
Objective C:
@interface ViewController : UIViewController<captureDelegate>
Swift:
class ViewController: UIViewController, captureDelegate{...}
A continuación se solicitará implementar la función f
inished:
CONFIDENCIAL Página 14 de 18
Objective C, agregar al .
h
- (void) finishedWithStatus:(NSInteger *) status captured_token:(NSString *) token;
Objective C, agregar al .
m
- (void) finishedWithStatus:(NSInteger *) status captured_token:(NSString *) token{
NSLog(@"autocapture finished with status: %d token: %@", status, token);
}
Swift:
func f inished(status: Int, captured_token: String){
print("autocapture finishes with status: \(status) and token:
\(captured_token)")
}
Por último, se hace la llamada al proceso de Autocaptura:
Objective C
captureInterface *acvc = [[captureInterface alloc] init];
[acvc setDelegateWithDel:self];
[acvc setSessionIdWithSid:@"session_id"];
Swift:
let autocapture = captureInterface()
autocapture.setDelegate(del: self)
autocapture.setSessionId(sid: "session_id")
CONFIDENCIAL Página 15 de 18
CONFIDENCIAL Página 16 de 18
CONFIDENCIAL Página 17 de 18
CONFIDENCIAL Página 18 de 18