> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-de-documentos.md). # Captura de documentos - SelphID ## Introducción La captura de documentos se realiza mediante el **SelphID Component**. Este componente se encarga de capturar documentos de identidad y analizar la información obtenida. Durante el proceso se realizan, entre otros, los siguientes pasos: * Gestión interna de cámaras y permisos. * Asistencia guiada durante la captura del **anverso y reverso** del documento. * Extracción de la información contenida en el documento. * Obtención de imágenes del documento y de elementos asociados: * Cara del usuario. * Firma del usuario. * Alto nivel de configuración: * Países. * Idiomas. * Tipos de documento. En la sección [Lanzamiento simplificado](/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) se describen los pasos básicos para la integración del SDK.\ En esta página se detalla la información específica necesaria para lanzar y configurar este componente. *** ## Dependencia La dependencia específica del componente es: ```kotlin implementation "com.facephi.androidsdk:selphid_component:$version" ``` *** ## Controladores disponibles | **Controlador** | **Descripción** | | ----------------- | ----------------------------------------------------- | | SelphIDController | Controlador principal de reconocimiento de documentos | *** ## Lanzamiento simplificado Una vez iniciado el SDK y creada una nueva operación, el componente puede lanzarse utilizando su controlador. Lanzamiento de la captura facial: ```kotlin val response = SDKController.launch( SelphIDController(SelphIDConfiguration(..)) ) when (response) { is SdkResult.Error -> Napier.d("SelphID: ERROR - ${response.error.name}") is SdkResult.Success -> response.data } ``` *** ## Configuración básica Para lanzar el componente es necesario crear un objeto **SelphIDConfigurationData**, que define el comportamiento del widget. En la configuración básica: * Es obligatorio definir el **país** y el **tipo de documento**. * En el campo `specificData` se debe indicar el código de país correspondiente (por ejemplo, `ES` para España). ```kotlin SelphIDConfiguration( resourcesPath = "resources_file.zip", wizardMode = true, specificData = "ES|", documentType = SelphIDDocumentType.ID_CARD, ) ``` **Tipos de documento disponibles** ``` SelphIDDocumentType.ID_CARD SelphIDDocumentType.PASSPORT SelphIDDocumentType.DRIVERS_LICENSE SelphIDDocumentType.FOREIGN_CARD SelphIDDocumentType.CREDIT_CARD SelphIDDocumentType.CUSTOM SelphIDDocumentType.VISA ``` *** ## Recepción del resultado El resultado del lanzamiento se devuelve como un objeto **SdkResult**, que puede indicar un resultado correcto o un error. ```kotlin when (response) { is SdkResult.Error -> Napier.d("ERROR - ${response.error}") is SdkResult.Success -> response.data } ``` ### Recepción de errores Los errores se devuelven como un objeto **SelphIdError**. **Listado de errores** * SPD\_ACTIVITY\_RESULT\_ERROR: El resultado de la actividad es incorrecto. * SPD\_ACTIVITY\_RESULT\_MSG\_ERROR: El resultado de la actividad recibido en el msg es incorrecto. * SPD\_APPLICATION\_CONTEXT\_ERROR: El contexto de aplicación necesario es nulo. * SPD\_BAD\_EXTRACTOR\_CONFIGURATION\_ERROR: Widget: Configuración del extractor incorrecta * SPD\_CAMERA\_PERMISSION\_DENIED: El usuario ha rechazado los permisos. * SPD\_CANCEL\_BY\_USER: El usuario ha cancelado el proceso. * SPD\_CANCEL\_LAUNCH: Se ha hecho una cancelación general del SDK. * SPD\_COMPONENT\_LICENSE\_ERROR: La licencia del componente no es correcta. * SPD\_CONTROL\_NOT\_INITIALIZATED\_ERROR: Widget: Error de inicialización * SPD\_EMPTY\_LICENSE: El String de licencia está vacío. * SPD\_EXTRACTION\_LICENSE\_ERROR: Widget: Error de licencia * SPD\_FETCH\_DATA\_ERROR: Error en la recogida del resultado. * SPD\_FLOW\_ERROR: Error en el proceso de flow. * SPD\_HARDWARE\_ERROR: Widget: Error de hardware * SPD\_INITIALIZATION\_ERROR: Error de inicialización. * SPD\_MANAGER\_NOT\_INITIALIZED: Los managers son nulos. * SPD\_MOVE\_FAIL: El usuario no se ha movido como se le ha especificado en el proceso. * SPD\_NO\_DATA\_ERROR: Los datos de entrada son nulos. * SPD\_OPERATION\_NOT\_CREATED: No hay ninguna operación en curso. * SPD\_RESOURCES\_NOT\_FOUND: No se ha encontrado el zip de recursos * SPD\_SETTINGS\_PERMISSION\_ERROR: Widget: Error de permisos * SPD\_TIMEOUT: Timeout en el proceso. * SPD\_UNEXPECTED\_CAPTURE\_ERROR: Widget: Error en la captura * SPD\_UNKNOWN\_ERROR: Error desconocido * SPD\_WIDGET\_RESULT\_DATA\_ERROR: Error en los datos de salida del widget ### Recepción del resultado correcto - *data* Cuando el resultado es correcto (`SdkResult.Success`), se obtiene un objeto **SelphIDResult**. Las imágenes se devuelven en formato **SdkImage**.\ Es posible acceder al bitmap mediante `image.bitmap`. Para convertir una imagen a Base64: ```kotlin Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP) ``` **Campos devueltos** **frontDocument / tokenFrontDocument:** La imagen frontal del documento procesada, limpiada y recortada por los bordes y su token correspondiente. **backDocument / tokenBackDocument** La imagen trasera del documento procesada, limpiada y recortada por los bordes y su token asociado. **faceImage / tokenFaceImage** La imagen del rostro que se ha encontrado en el documento, en caso de que exista y su token asociado. Válida para el proceso de MATCHING FACIAL. **documentCaptured** Esta propiedad indica el modelo de documento que se ha capturado cuando se realiza una busqueda en modo SMSearch. De esta forma la aplicación puede conocer qué modelo, de entre todos los permitidos, se ha detectado. **matchingSidesScore** Esta propiedad devuelve un cálculo de la similitud de los datos leídos entre el front y el back del documento. El cálculo se realiza comprobando la similitud entre los campos comunes leídos en ambas caras. El resultado del cálculo será un valor entre 0.0 y 1.0 para el caso de que existan campos comunes en el documento. Cuanto mayor es el valor, más similares son los datos comparados. Si el cálculo devuelve -1.0 es que el documento no contiene campos comunes o aún no se tiene información de las dos caras. **Propiedad captureProgress** Esta propiedad devuelve el estado en el que se encontraba el proceso de captura cuando el widget terminó. Estos son los posibles valores: ``` Front_Detection_None = 0 Front_Detection_Uncertain = 1 Front_Detection_Completed = 2 Front_Document_Analyzed = 3 Back_Detection_None = 4 Back_Detection_Uncertain = 5 Back_Detection_Completed = 6 Back_Document_Analyzed = 7 ``` * **0**: En la lectura del Front, el widget termino sin poder haber detectado nada. Generalmente cuando no se pone ningún documento. * **1**: En la lectura del Front, el widget termino habiendo detectado parcialmente un documento. En este caso algunos de los elementos esperados se han conseguido detectar, pero no todos los necesarios. * **2**: En la lectura del Front, el widget termino habiendo completado la detección de todos los elementos del documento. Si el widget acaba en este estado es porque el análisis de OCR no se ha podido completar con éxito. * **3**: En la lectura del Front, el widget termino habiendo analizado y extraído todo el OCR del documento. Este es el estado en el que acabaría una lectura correcta del Front de un documento. Los estados del **4** al **7** son exactamente iguales solo que se refieren al resultado del proceso cuando se analiza el back. **ocrResults** Este diccionario contiene todos los datos detectados en el documento. Las claves de cada campo están codificadas de tal forma que la propia clave contiene información de donde se ha obtenido el valor. Así, por ejemplo, la clave `Front/MRZ/DocumentNumber` indica el valor del DocumentNumber que se ha leído en el Front del documento y en la región del MRZ. Estas claves dependen del documento capturado y por tanto serán diferentes entre distintos países y modelos de documento. El diccionario también contiene claves con nombres más genéricos y que no llevan información relativa a la ubicación. Estas claves contienen el dato más completo de todos los leídos para dicho campo. Estas claves son los siguientes: * **FirstName**: El valor asociado a esta clave contiene el nombre del usuario. * **LastName**: El valor asociado a esta clave contiene los apellidos del usuario. * **DateOfBirth**: El valor asociado a esta clave contiene la fecha de nacimiento detectada en el documento. * **Gender**: El valor asociado a esta clave contiene el sexo del usuario detectado en el documento. * **Nationality**: El valor asociado a esta clave contiene la nacionalidad del usuario detectado en el documento. * **DocumentNumber**: El valor asociado a esta clave contiene el número de documento. * **DateOfExpiry**: El valor asociado a esta clave contiene la fecha de expiración del documento. * **Issuer**: El valor asociado a esta clave contiene el editor del documento. * **DateofIssue**: El valor asociado a esta clave contiene la fecha de expedición del documento. * **PlaceOfBirth**: El valor asociado a esta clave contiene el lugar de nacimiento del usuario. * **Address**: El valor asociado a esta clave contiene la dirección detectada en el documento. Adicionalmente se añaden claves del propio objeto results para hacer más fácil su búsqueda: * **DocumentCaptured**: Valor del modelo de documento que se ha capturado según el .xml de modelos. Corresponde a la propiedad documentCaptured. * **MatchingSidesScore**: Valor que indica la correspondencia entre las caras leídas del documento. Corresponde a la propiedad matchingSidesScore. **timeoutDiagnostic** Esta propiedad devuelve una cadena de texto que explica por qué se ha agotado el tiempo de espera del widget. Esta cadena puede ser utilizada en una pantalla de tiempo de espera posterior donde la aplicación principal puede dar más información al usuario sobre lo ocurrido durante la captura del documento. **countryCaptured** País del documento. **documentTypeCaptured** Tipo de documento. Se corresponde con los del apartado 5.1.10. **personalData** Conjunto reducido de datos obtenidos del usuario: * issuer * documentNumber * issueDate * expiryDate * name * surname * fullName * gender * birthDate * birthPlace * nationality * address * nfcKey * numSupport * mrz *** ## Información avanzada ### Selector de documentos - OPCIONAL **showDocumentSelector** Activación de la vista de selector de documentos. Se presentará nada más lanzar el controlador. **enabledCountries** Listado de países en ISO2 que aparecerán en el selector. Si su valor es nulo o no contiene valores válidos, se mostrarán todos los disponibles por el SDK. **enabledDocumentTypes** Listado de tipos de documentos que aparecerán en el selector de tipos de documentos. Si su valor es nulo o no contiene valores, se mostrarán todos los disponibles por el SDK. #### Configuración avanzada del componente El comportamiento del componente se define mediante **SelphIDConfigurationData**. **resourcesPath** Indica el nombre de los recursos en formato zip del componente. Ejemplo: “resources-selphid-2-0.zip“. Este nombre irá a buscar el fichero a la ruta de *assets*.
**wizardMode** Indica si el widget queda configurado para realizar la captura de ambas partes (frontal y trasera) del documento una a continuación de la otra. En este modo el widget solo se lanzaría una vez y al terminar de capturar el front, continuaría seguidamente con el back. **showResultAfterCapture** Indica si mostrar o no una pantalla con la imagen capturada del documento después del proceso de análisis. En esta pantalla se le da al usuario la posibilidad de repetir el proceso de captura si la imagen que se obtuvo del documento no fuera correcta. **showTutorial** Indica si el widget activa la pantalla de tutorial. En esta vista se explica de forma intuitiva cómo se realiza la captura. **tutorialOnly** Indica si el widget se quiere lanzar solo para mostrar el tutorial. **scanMode** Indica el modo de escaneo OCR de los documentos. Dependiendo de la elección, se escanearán y buscarán varios tipos de documentos o uno en concreto. Este modo puede ser de tres tipos: * **SelphIDScanMode.MODE\_GENERIC**: El modo genérico que permite escanear cualquier tipo de documento independiente del país o el tipo de documento. El resultado de este modo no es tan preciso como los siguientes pero permite escanear varios documentos estándar. * **SelphIDScanMode.MODE\_SEARCH**: El modo de búsqueda permitirá utilizar una whitelist y blacklist, y buscará en los documentos que cumplan dichas condiciones. Estas condiciones se indican en la variable "specificData". De este modo se permite realizar la búsqueda acotando el número de plantillas, y haciendo que la búsqueda sea mucho más afinada que en el caso genérico. * **SelphIDScanMode.MODE\_SPECIFIC**: Búsqueda de un documento específico. Estas condiciones se indican en la propiedad "specificData" que se muestra en lo sucesivo. **specificData** Esta propiedad permite definir qué documentos se escanearán durante el proceso, en caso de declarar el modo de escaneo (scanMode) a **MODE\_SEARCH** o **MODE\_SPECIFIC**. Un ejemplo de configuración que permita escanear todos los documentos de nacionalidad española sería el siguiente: ``` val selphIDConfiguration = SelphIDConfigurationData( scanMode = SelphIDScanMode.MODE_SEARCH, specificData = "ES|", // Código ISO de España (ES) ) ``` **fullscreen** Indica si la vista va a tener prioridad para mostrarse en pantalla completa, si el sistema lo permite. **tokenImageQuality** Indica la cantidad de calidad que se quiere recibir en las imágenes tokenizadas. Valor entre 0 y 1. **documentType** Los valores permitidos son los siguientes: * **SelphIDDocumentType.ID\_CARD**: El widget queda configurado para realizar la captura de documentos de identidad. * **SelphIDDocumentType.PASSPORT**: El widget queda configurado para realizar la captura de pasaportes. * **SelphIDDocumentType.DRIVERS\_LICENSE**: El widget queda configurado para realizar la captura de licencias de conducción. * **SelphIDDocumentType.FOREIGN\_CARD**: El widget queda configurado para realizar la captura de documentos extranjeros. * **SelphIDDocumentType.CUSTOM**: El widget queda configurado para realizar la captura de otro tipo de documentos que no corresponden a ninguna de las categorías anteriores. * **WidgetSelphIDDocumentType.VISA**: El widget queda configurado para realizar la captura del visado de un país. (SDK min 2.1.2) **documentSide** Los valores permitidos son los siguientes: * **SelphIDDocumentSide.FRONT**: El widget queda configurado para realizar la captura de la parte frontal del documento. * **SelphIDDocumentSide.BACK**: El widget queda configurado para realizar la captura de la parte trasera del documento. **timeout** Es un enumerado que define el timeout de la captura de un lado del documento. Tiene 3 posibles valores: * SelphIDTimeout.SHORT: 15 segundos. * SelphIDTimeout.MEDIUM: 20 segundos. * SelphIDTimeout.LONG: 25 segundos. * SelphIDTimeout.VERY\_LONG: 60 segundos. **videoFilename** Establece la ruta absoluta del nombre del archivo en el que se grabará un video del proceso de captura. La aplicación es la responsable de solicitar los permisos necesarios al teléfono en caso de que esa ruta requiera de permisos adicionales. El widget, por defecto, no realizará ningún proceso de grabación a menos que se especifique una ruta de archivo mediante este método. **DocumentModels** Esta propiedad permite, mediante una cadena en formato xml, configurar modelado de los documentos que el widget va a tratar de capturar. La definición de este modelado se encentra, por defecto, en un .xml de modelos que se encuentra en el .zip de recursos. Con esta propiedad se permite a una aplicación actualizar, en caliente, los modelados de los documentos. Nota: Esta propiedad no altera el contenido del archivo de recursos. **generateRawImages** Esta propiedad configura el widget para devolver la imagen completa de la cámara que se utilizó para capturar el documento. Estas imágenes se devuelven en las propiedades `rawFrontDocument` y `rawBackDocument` del objeto `results` respectivamente. **tokenPreviousCaptureData** Cuando la captura del documento se realiza en 2 llamadas, esta propiedad permite pasar un diccionario con la información de la captura previa. De esta manera el widget puede combinar los resultados de ambas lecturas de una manera inteligente y así devolver la información combinada de ambas capturas. También permite al widget calcular un grado de similitud de los datos de ambas caras. En el caso que la captura de ambas caras del documento se realice en una única llamada esto no es necesario ya que el widget internamente hace este proceso. **translationsContent** Esta propiedad avanzada permite, mediante una cadena en formato xml, configurar la traducción de los literales que se muestran durante el proceso. Nota: Esta propiedad no altera el contenido del archivo de recursos. **viewsContent** Esta propiedad avanzada permite, mediante una cadena en formato xml, configurar las vistas del widget. Nota: Esta propiedad no altera el contenido del archivo de recursos. **showDiagnostic** Mostrar pantallas de diagnóstico al final del proceso **showPreviousTip** Muestra una pantalla previa al lanzamiento de la captura con información sobre el proceso a realizar y un botón para el lanzamiento. **vibrationEnabled** Indica si se desea un feedback de vibración al acabar el proceso. *** ## Personalización del componente Además de la [Personalización del SDK](/sdks/sdk-mobile/android-sdk/personalizacion.md) este componente permite modificar su interfaz. ### Textos Los textos pueden personalizarse sobrescribiendo los valores en un archivo XML de strings incluido en la aplicación cliente. Ejemplos de claves disponibles: #### Diagnóstico | Name | Value | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | | `selphid_component_timeout_title` | Tiempo superado | | `selphid_component_timeout_desc` | Comprueba que el documento está dentro del recuadro y los datos son visibles. | | `selphid_component_timeout_front_desc` | Comprueba que el frente del documento está dentro del recuadro y los datos son visibles. | | `selphid_component_timeout_back_desc` | Comprueba que el dorso del documento está dentro del recuadro y los datos son visibles. | | `selphid_component_internal_error_title` | Hubo un problema técnico | | `selphid_component_internal_error_desc` | Pedimos disculpas. No se ha podido hacer la captura | #### Tip Previo | Name | Value | | ----------------------------------------- | ---------------------------------------------------------------------------------------------- | | `selphid_component_tip_message` | Enfoca tu documento dentro del recuadro. La foto se hará automáticamente. | | `selphid_component_tip_message_alt` | Enfoca tu documento dentro del recuadro. La foto se hará automáticamente. | | `selphid_component_tip_anim_id_alt` | Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tip_anim_passport_alt` | Coloca tu pasaporte en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tip_anim_driving_alt` | Coloca tu licencia de conducir en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tip_title` | Foto del documento | | `selphid_component_tip_button` | COMENZAR | | `selphid_component_tip_button_alt` | Comenzar captura de documento | | `selphid_component_tip_close_button_alt` | VOLVER | | `selphid_component_tip_info_button_alt` | Ver consejos | #### Tutorial | Name | Value | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `selphid_component_tutorial_message_1` | Busca un fondo con buen contraste. | | `selphid_component_tutorial_message_2` | Coloca el documento dentro del recuadro. | | `selphid_component_tutorial_message_3` | Evita brillos que dificulten la lectura del documento. | | `selphid_component_tutorial_1_anim_id_alt` | Coloca el documento en una superficie con un color distinto al documento. | | `selphid_component_tutorial_2_anim_id_alt` | Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tutorial_3_anim_id_alt` | Aparecen reflejos sobre el documento. | | `selphid_component_tutorial_1_anim_pass_alt` | Coloca el pasaporte en una superficie con un color distinto al documento. | | `selphid_component_tutorial_2_anim_pass_alt` | Coloca tu pasaporte en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tutorial_3_anim_pass_alt` | Aparecen reflejos sobre el documento. | | `selphid_component_tutorial_1_anim_driving_alt` | Coloca el documento en una superficie con un color distinto al documento. | | `selphid_component_tutorial_2_anim_driving_alt` | Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tutorial_3_anim_driving_alt` | Aparecen reflejos sobre el documento. | | `selphid_component_tip_health_alt` | Coloca tu tarjeta sanitaria en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tutorial_1_anim_health_alt` | Coloca la tarjeta sanitaria en una superficie con un color distinto al documento. | | `selphid_component_tutorial_2_anim_health_alt` | Coloca tu documento de identidad en horizontal, y apunta con tu teléfono en posición vertical. | | `selphid_component_tutorial_3_anim_health_alt` | Aparecen reflejos sobre el documento. | | `selphid_component_tip_custom_alt` | -- | | `selphid_component_tutorial_1_anim_custom_alt` | -- | | `selphid_component_tutorial_2_anim_custom_alt` | -- | | `selphid_component_tutorial_3_anim_custom_alt` | -- | | `selphid_component_tutorial_close_button_alt` | Volver al tutorial previo | #### Selector de Documento y País | Name | Value | | --------------------------------------------- | ----------------------------- | | `selphid_selector_title` | Realiza tu onboarding | | `selphid_selector_country_label` | ¿De qué país es tu documento? | | `selphid_selector_country_placeholder` | Selecciona un país | | `selphid_selector_country_search_label` | Elige un país | | `selphid_selector_country_search_placeholder` | Busca un país | | `selphid_selector_country_search_clear` | Limpiar búsqueda | | `selphid_selector_country_no_results` | Sin resultados | | `selphid_selector_document_label` | ¿Qué documento utilizarás? | | `selphid_selector_document_placeholder` | Selecciona un documento | | `selphid_selector_document_dialog_title` | Elige el documento | | `selphid_selector_document_dialog_cancel` | CANCELAR | | `selphid_selector_document_dialog_select` | SELECCIONAR | | `selphid_selector_continue` | Continuar | | `selphid_selector_type_id_card` | Documento de identidad | | `selphid_selector_type_passport` | Pasaporte | | `selphid_selector_type_drivers_license` | Licencia de conducir | | `selphid_selector_type_foreign_card` | Tarjeta de residencia | | `selphid_selector_type_credit_card` | Tarjeta de crédito | | `selphid_selector_type_custom` | Personalizado | | `selphid_selector_type_visa` | Visado | ### Animaciones El componente utiliza animaciones **Lottie** (`.json`) tanto en el *tip previo* como en los *tutoriales*. Si se desea modificar las animaciones de la SDK, se deberán incluir los archivos con **el mismo nombre** en la carpeta `res/raw/` ``` selphid_anim_tip_driver_h.json selphid_anim_tip_driver_m.json selphid_anim_tip_health.json selphid_anim_tip_id_h.json selphid_anim_tip_id_m.json selphid_anim_tip_mrz.json selphid_anim_tip_pass_h.json selphid_anim_tip_pass_m.json selphid_anim_tuto_driver_h_1.json selphid_anim_tuto_driver_h_2.json selphid_anim_tuto_driver_h_3.json selphid_anim_tuto_driver_m_1.json selphid_anim_tuto_driver_m_2.json selphid_anim_tuto_driver_m_3.json selphid_anim_tuto_id_h_1.json selphid_anim_tuto_id_h_2.json selphid_anim_tuto_id_h_3.json selphid_anim_tuto_id_m_1.json selphid_anim_tuto_id_m_2.json selphid_anim_tuto_id_m_3.json selphid_anim_tuto_pass_h_1.json selphid_anim_tuto_pass_h_2.json selphid_anim_tuto_pass_h_3.json selphid_anim_tuto_pass_m_1.json selphid_anim_tuto_pass_m_2.json ```