> 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/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/componentes-modulos/captura-de-documentos.md). # Captura de documentos - SelphID ## Introdução A captura de documentos é realizada por meio do **Componente SelphID**. Este componente é responsável por capturar documentos de identidade e analisar as informações obtidas. Durante o processo, realizam-se, entre outros, os seguintes passos: * Gestão interna de câmeras e permissões. * Assistência guiada durante a captura do **frente e verso** do documento. * Extração das informações contidas no documento. * Obtenção de imagens do documento e de elementos associados: * Rosto do usuário. * Assinatura do usuário. * Alto nível de configuração: * Países. * Idiomas. * Tipos de documento. Na seção [Lançamento simplificado](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/inicializacion/lanzamiento-simplificado.md) descrevem-se os passos básicos para a Integração do SDK.\ Nesta página detalha-se a informação específica necessária para iniciar e configurar este componente. *** ## Dependência A dependência específica do componente é: ```kotlin implementation "com.facephi.androidsdk:selphid_component:$version" ``` *** ## Controladores disponíveis | **Controlador** | **Descrição** | | ----------------- | ----------------------------------------------------- | | SelphIDController | Controlador principal de reconhecimento de documentos | *** ## Lançamento simplificado Uma vez iniciado o SDK e criada uma nova operação, o componente pode ser iniciado usando seu controlador. Lançamento da 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 } ``` *** ## Configuração básica Para iniciar o componente é necessário criar um objeto **SelphIDConfigurationData**, que define o comportamento do Widget. Na configuração básica: * É obrigatório definir o **país** e o **tipo de documento**. * No campo `specificData` deve-se indicar o código de país correspondente (por exemplo, `ES` para a Espanha). ```kotlin SelphIDConfiguration( resourcesPath = "resources_file.zip", wizardMode = true, specificData = "ES|", documentType = SelphIDDocumentType.ID_CARD, ) ``` **Tipos de documento disponíveis** ``` SelphIDDocumentType.ID_CARD SelphIDDocumentType.PASSPORT SelphIDDocumentType.DRIVERS_LICENSE SelphIDDocumentType.FOREIGN_CARD SelphIDDocumentType.CREDIT_CARD SelphIDDocumentType.CUSTOM SelphIDDocumentType.VISA ``` *** ## Recebimento do resultado O resultado da inicialização é retornado como um objeto **SdkResult**, que pode indicar um resultado correto ou um erro. ```kotlin when (response) { is SdkResult.Error -> Napier.d("ERROR - ${response.error}") is SdkResult.Success -> response.data } ``` ### Recebimento de erros Os erros são retornados como um objeto **SelphIdError**. **Lista de erros** * SPD\_ACTIVITY\_RESULT\_ERROR: O resultado da atividade está incorreto. * SPD\_ACTIVITY\_RESULT\_MSG\_ERROR: O resultado da atividade recebido no msg está incorreto. * SPD\_APPLICATION\_CONTEXT\_ERROR: O contexto de aplicação necessário é nulo. * SPD\_BAD\_EXTRACTOR\_CONFIGURATION\_ERROR: Widget: Configuração do extrator incorreta * SPD\_CAMERA\_PERMISSION\_DENIED: O usuário recusou as permissões. * SPD\_CANCEL\_BY\_USER: O usuário cancelou o processo. * SPD\_CANCEL\_LAUNCH: Foi feita uma cancelação geral do SDK. * SPD\_COMPONENT\_LICENSE\_ERROR: A licença do componente não está correta. * SPD\_CONTROL\_NOT\_INITIALIZATED\_ERROR: Widget: Erro de inicialização * SPD\_EMPTY\_LICENSE: O String de Licença está vazio. * SPD\_EXTRACTION\_LICENSE\_ERROR: Widget: Erro de licença * SPD\_FETCH\_DATA\_ERROR: Erro na coleta do resultado. * SPD\_FLOW\_ERROR: Erro no processo de flow. * SPD\_HARDWARE\_ERROR: Widget: Erro de hardware * SPD\_INITIALIZATION\_ERROR: Erro de inicialização. * SPD\_MANAGER\_NOT\_INITIALIZED: Os managers estão nulos. * SPD\_MOVE\_FAIL: O usuário não se moveu conforme especificado no processo. * SPD\_NO\_DATA\_ERROR: Os dados de entrada estão nulos. * SPD\_OPERATION\_NOT\_CREATED: Não há nenhuma operação em andamento. * SPD\_RESOURCES\_NOT\_FOUND: Não foi encontrado o zip de recursos * SPD\_SETTINGS\_PERMISSION\_ERROR: Widget: Erro de permissões * SPD\_TIMEOUT: Timeout no processo. * SPD\_UNEXPECTED\_CAPTURE\_ERROR: Widget: Erro na captura * SPD\_UNKNOWN\_ERROR: Erro desconhecido * SPD\_WIDGET\_RESULT\_DATA\_ERROR: Erro nos dados de saída do Widget ### Recebimento do resultado correto - *data* Quando o resultado é correto (`SdkResult.Success`), obtém-se um objeto **SelphIDResult**. As imagens são retornadas no formato **SdkImage**.\ É possível acessar o bitmap por meio de `image.bitmap`. Para converter uma imagem para Base64: ```kotlin Base64.encodeToString(this.toByteArray(), Base64.NO_WRAP) ``` **Campos retornados** **frontDocument / tokenFrontDocument:** A imagem frontal do documento processada, limpa e recortada pelas bordas e seu token correspondente. **backDocument / tokenBackDocument** A imagem traseira do documento processada, limpa e recortada pelas bordas e seu token associado. **faceImage / tokenFaceImage** A imagem do rosto que foi encontrada no documento, caso exista, e seu token associado. Válida para o processo de Matching facial. **documentCaptured** Esta propriedade indica o modelo de documento que foi capturado quando se realiza uma busca em modo SMSearch. Dessa forma, a aplicação pode saber qual modelo, entre todos os permitidos, foi detectado. **matchingSidesScore** Esta propriedade retorna um cálculo da similaridade dos dados lidos entre a frente e o verso do documento. O cálculo é realizado verificando a similaridade entre os campos comuns lidos em ორივas as faces. O resultado do cálculo será um valor entre 0,0 e 1,0 caso existam campos comuns no documento. Quanto maior for o valor, mais similares são os dados comparados. Se o cálculo retornar -1,0, é porque o documento não contém campos comuns ou ainda não há informação das duas faces. **Propiedad captureProgress** Esta propriedade retorna o estado em que o processo de captura se encontrava quando o Widget terminou. Estes são os possíveis 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**: Na leitura da frente, o Widget terminou sem conseguir detectar nada. Geralmente quando nenhum documento é colocado. * **1**: Na leitura da frente, o Widget terminou tendo detectado parcialmente um documento. Nesse caso, alguns dos elementos esperados conseguiram ser detectados, mas não todos os necessários. * **2**: Na leitura da frente, o Widget terminou tendo completado a detecção de todos os elementos do documento. Se o Widget termina nesse estado é porque a análise de OCR não pôde ser concluída com sucesso. * **3**: Na leitura da frente, o Widget terminou tendo analisado e extraído todo o OCR do documento. Esse é o estado em que terminaria uma leitura correta da frente de um documento. Os estados do **4** ao **7** são exatamente iguais, apenas se referem ao resultado do processo quando o verso é analisado. **ocrResults** Este dicionário contém todos os dados detectados no documento. As chaves de cada campo estão codificadas de tal forma que a própria chave contém informação de onde o valor foi obtido. Assim, por exemplo, a chave `Front/MRZ/DocumentNumber` indica o valor do DocumentNumber que foi lido na frente do documento e na região do MRZ. Essas chaves dependem do documento capturado e, portanto, serão diferentes entre distintos países e modelos de documento. O dicionário também contém chaves com nomes mais genéricos e que não levam informação relativa à localização. Essas chaves contêm o dado mais completo de todos os lidos para esse campo. Essas chaves são as seguintes: * **FirstName**: O valor associado a esta chave contém o nome do usuário. * **LastName**: O valor associado a esta chave contém os sobrenomes do usuário. * **DateOfBirth**: O valor associado a esta chave contém a data de nascimento detectada no documento. * **Gender**: O valor associado a esta chave contém o sexo do usuário detectado no documento. * **Nationality**: O valor associado a esta chave contém a nacionalidade do usuário detectado no documento. * **DocumentNumber**: O valor associado a esta chave contém o número do documento. * **DateOfExpiry**: O valor associado a esta chave contém a data de expiração do documento. * **Issuer**: O valor associado a esta chave contém o emissor do documento. * **DateofIssue**: O valor associado a esta chave contém a data de emissão do documento. * **PlaceOfBirth**: O valor associado a esta chave contém o local de nascimento do usuário. * **Address**: O valor associado a esta chave contém o endereço detectado no documento. Adicionalmente, são adicionadas chaves do próprio objeto results para facilitar sua busca: * **DocumentCaptured**: Valor do modelo de documento que foi capturado conforme o .xml de modelos. Corresponde à propriedade documentCaptured. * **MatchingSidesScore**: Valor que indica a correspondência entre as faces lidas do documento. Corresponde à propriedade matchingSidesScore. **timeoutDiagnostic** Esta propriedade retorna uma string que explica por que o tempo de espera do Widget se esgotou. Essa string pode ser usada em uma tela posterior de tempo de espera, onde o aplicativo principal pode fornecer mais informações ao usuário sobre o que aconteceu durante a captura do documento. **countryCaptured** País do documento. **documentTypeCaptured** Tipo de documento. Corresponde aos do item 5.1.10. **personalData** Conjunto reduzido de dados obtidos do usuário: * issuer * documentNumber * issueDate * expiryDate * name * surname * fullName * gender * birthDate * birthPlace * nationality * address * nfcKey * numSupport * mrz *** ## Informações avançadas ### Seletor de documentos - OPCIONAL **showDocumentSelector** Ativação da tela de seletor de documentos. Ela será exibida assim que o controlador for iniciado. **enabledCountries** Lista de países em ISO2 que aparecerão no seletor. Se o valor for nulo ou não contiver valores válidos, serão exibidos todos os disponíveis no SDK. **enabledDocumentTypes** Lista de tipos de documentos que aparecerão no seletor de tipos de documentos. Se o valor for nulo ou não contiver valores, serão exibidos todos os disponíveis no SDK. #### Configuração avançada do componente O comportamento do componente é definido por **SelphIDConfigurationData**. **resourcesPath** Indica o nome dos recursos em formato zip do componente. Exemplo: “resources-selphid-2-0.zip“. Esse nome irá buscar o arquivo no caminho de *assets*.
**wizardMode** Indica se o Widget fica configurado para realizar a captura de ambas as partes (frontal e traseira) do documento uma após a outra. Nesse modo, o Widget só seria iniciado uma vez e, ao terminar de capturar a frente, continuaria em seguida com o verso. **showResultAfterCapture** Indica se exibir ou não uma tela com a imagem capturada do documento após o processo de análise. Nessa tela, dá-se ao usuário a possibilidade de repetir o processo de captura se a imagem obtida do documento não estiver correta. **showTutorial** Indica se o Widget ativa a tela de tutorial. Nessa visualização, é explicado de forma intuitiva como a captura é realizada. **tutorialOnly** Indica se o Widget deve ser iniciado apenas para exibir o tutorial. **scanMode** Indica o modo de escaneamento OCR dos documentos. Dependendo da escolha, serão escaneados e buscados vários tipos de documentos ou um em específico. Esse modo pode ser de três tipos: * **SelphIDScanMode.MODE\_GENERIC**: O modo genérico que permite escanear qualquer tipo de documento independente do país ou do tipo de documento. O resultado desse modo não é tão preciso quanto os seguintes, mas permite escanear vários documentos padrão. * **SelphIDScanMode.MODE\_SEARCH**: O modo de busca permitirá utilizar uma whitelist e uma blacklist e buscará nos documentos que atendam a essas condições. Essas condições são indicadas na variável "specificData". Desse modo, é possível realizar a busca restringindo o número de modelos e tornando a busca muito mais precisa do que no caso genérico. * **SelphIDScanMode.MODE\_SPECIFIC**: Busca de um documento específico. Essas condições são indicadas na propriedade "specificData" mostrada a seguir. **specificData** Esta propriedade permite definir quais documentos serão escaneados durante o processo, caso o modo de escaneamento (scanMode) seja definido como **MODE\_SEARCH** ou **MODE\_SPECIFIC**. Um exemplo de configuração que permita escanear todos os documentos de nacionalidade espanhola seria o seguinte: ``` val selphIDConfiguration = SelphIDConfigurationData( scanMode = SelphIDScanMode.MODE_SEARCH, specificData = "ES|", // Código ISO de España (ES) ) ``` **fullscreen** Indica se a visualização terá prioridade para ser exibida em tela cheia, se o sistema permitir. **tokenImageQuality** Indica a quantidade de qualidade que se deseja receber nas imagens tokenizadas. Valor entre 0 e 1. **documentType** Os valores permitidos são os seguintes: * **SelphIDDocumentType.ID\_CARD**: O Widget fica configurado para realizar a captura de documentos de identidade. * **SelphIDDocumentType.PASSPORT**: O Widget fica configurado para realizar a captura de passaportes. * **SelphIDDocumentType.DRIVERS\_LICENSE**: O Widget fica configurado para realizar a captura de carteiras de motorista. * **SelphIDDocumentType.FOREIGN\_CARD**: O Widget fica configurado para realizar a captura de documentos estrangeiros. * **SelphIDDocumentType.CUSTOM**: O Widget fica configurado para realizar a captura de outro tipo de documentos que não correspondem a nenhuma das categorias anteriores. * **WidgetSelphIDDocumentType.VISA**: O Widget fica configurado para realizar a captura do visto de um país. (SDK min 2.1.2) **documentSide** Os valores permitidos são os seguintes: * **SelphIDDocumentSide.FRONT**: O Widget fica configurado para realizar a captura da parte frontal do documento. * **SelphIDDocumentSide.BACK**: O Widget fica configurado para realizar a captura da parte traseira do documento. **Timeout** É um enumerado que define o Timeout da captura de um lado do documento. Tem 3 valores possíveis: * SelphIDTimeout.SHORT: 15 segundos. * SelphIDTimeout.MEDIUM: 20 segundos. * SelphIDTimeout.LONG: 25 segundos. * SelphIDTimeout.VERY\_LONG: 60 segundos. **videoFilename** Estabelece o caminho absoluto do nome do arquivo no qual será gravado um vídeo do processo de captura. O aplicativo é responsável por solicitar as permissões necessárias ao dispositivo caso esse caminho exija permissões adicionais. O Widget, por padrão, não realizará nenhum processo de gravação a menos que um caminho de arquivo seja especificado por meio deste método. **DocumentModels** Esta propriedade permite, por meio de uma string em formato xml, configurar a modelagem dos documentos que o Widget tentará capturar. A definição dessa modelagem encontra-se, por padrão, em um .xml de modelos localizado no .zip de recursos. Com essa propriedade, uma aplicação pode atualizar, em tempo real, as modelagens dos documentos. Nota: Esta propriedade não altera o conteúdo do arquivo de recursos. **generateRawImages** Esta propriedade configura o Widget para retornar a imagem completa da câmera que foi usada para capturar o documento. Essas imagens são retornadas nas propriedades `rawFrontDocument` e `rawBackDocument` do objeto `results` respectivamente. **tokenPreviousCaptureData** Quando a captura do documento é realizada em 2 chamadas, esta propriedade permite passar um dicionário com as informações da captura anterior. Dessa maneira, o Widget pode combinar os resultados de ambas as leituras de forma inteligente e, assim, retornar as informações combinadas de ambas as capturas. Também permite ao Widget calcular um grau de similaridade dos dados de ambos os lados. No caso de a captura de ambas as faces do documento ser realizada em uma única chamada, isso não é necessário, pois o Widget internamente faz esse processo. **translationsContent** Esta propriedade avançada permite, por meio de uma string em formato xml, configurar a tradução dos literais exibidos durante o processo. Nota: Esta propriedade não altera o conteúdo do arquivo de recursos. **viewsContent** Essa propriedade avançada permite, por meio de uma string em formato xml, configurar as visualizações do Widget. Nota: Esta propriedade não altera o conteúdo do arquivo de recursos. **showDiagnostic** Mostrar telas de diagnóstico ao final do processo **showPreviousTip** Mostra uma tela antes do início da captura com informações sobre o processo a ser realizado e um botão para iniciá-lo. **vibrationEnabled** Indica se se deseja um feedback de vibração ao final do processo. *** ## Personalização do componente Além da [Personalização do SDK](/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md) este componente permite modificar sua interface. ### Textos Os textos podem ser personalizados sobrescrevendo os valores em um arquivo XML de strings incluído no aplicativo cliente. Exemplos de chaves disponíveis: #### Diagnóstico | Name | Valor | | ---------------------------------------- | ------------------------------------------------------------------------------------ | | `selphid_component_timeout_title` | Tempo esgotado | | `selphid_component_timeout_desc` | Verifique se o documento está dentro da moldura e os dados estão visíveis. | | `selphid_component_timeout_front_desc` | Verifique se a frente do documento está dentro da moldura e os dados estão visíveis. | | `selphid_component_timeout_back_desc` | Verifique se o verso do documento está dentro da moldura e os dados estão visíveis. | | `selphid_component_internal_error_title` | Houve um problema técnico | | `selphid_component_internal_error_desc` | Pedimos desculpas. Não foi possível fazer a captura | #### Dica prévia | Name | Valor | | ----------------------------------------- | ----------------------------------------------------------------------------------- | | `selphid_component_tip_message` | Enquadre seu documento dentro da moldura. A foto será tirada automaticamente. | | `selphid_component_tip_message_alt` | Enquadre seu documento dentro da moldura. A foto será tirada automaticamente. | | `selphid_component_tip_anim_id_alt` | Coloque seu documento de identidade na horizontal e aponte seu celular na vertical. | | `selphid_component_tip_anim_passport_alt` | Coloque seu Passaporte na horizontal e aponte seu celular na vertical. | | `selphid_component_tip_anim_driving_alt` | Coloque sua Licença de conduzir na horizontal e aponte seu celular na vertical. | | `selphid_component_tip_title` | Foto do documento | | `selphid_component_tip_button` | COMEÇAR | | `selphid_component_tip_button_alt` | Iniciar captura de documento | | `selphid_component_tip_close_button_alt` | VOLTAR | | `selphid_component_tip_info_button_alt` | Ver dicas | #### Tutorial | Name | Valor | | ----------------------------------------------- | ------------------------------------------------------------------------------------- | | `selphid_component_tutorial_message_1` | Busque um fundo com bom contraste. | | `selphid_component_tutorial_message_2` | Coloque o documento dentro da moldura. | | `selphid_component_tutorial_message_3` | Evite brilhos que dificultem a leitura do documento. | | `selphid_component_tutorial_1_anim_id_alt` | Coloque o documento sobre uma superfície com uma cor diferente da do documento. | | `selphid_component_tutorial_2_anim_id_alt` | Coloque seu documento de identidade na horizontal e aponte seu celular na vertical. | | `selphid_component_tutorial_3_anim_id_alt` | Aparecem reflexos sobre o documento. | | `selphid_component_tutorial_1_anim_pass_alt` | Coloque o Passaporte sobre uma superfície com uma cor diferente da do documento. | | `selphid_component_tutorial_2_anim_pass_alt` | Coloque seu Passaporte na horizontal e aponte seu celular na vertical. | | `selphid_component_tutorial_3_anim_pass_alt` | Aparecem reflexos sobre o documento. | | `selphid_component_tutorial_1_anim_driving_alt` | Coloque o documento sobre uma superfície com uma cor diferente da do documento. | | `selphid_component_tutorial_2_anim_driving_alt` | Coloque seu documento de identidade na horizontal e aponte seu celular na vertical. | | `selphid_component_tutorial_3_anim_driving_alt` | Aparecem reflexos sobre o documento. | | `selphid_component_tip_health_alt` | Coloque seu cartão de saúde na horizontal e aponte seu celular na vertical. | | `selphid_component_tutorial_1_anim_health_alt` | Coloque o cartão de saúde sobre uma superfície com uma cor diferente da do documento. | | `selphid_component_tutorial_2_anim_health_alt` | Coloque seu documento de identidade na horizontal e aponte seu celular na vertical. | | `selphid_component_tutorial_3_anim_health_alt` | Aparecem reflexos sobre o 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` | Voltar ao tutorial anterior | #### Seletor de Documento e País | Name | Valor | | --------------------------------------------- | ------------------------------ | | `selphid_selector_title` | Realize seu Onboarding | | `selphid_selector_country_label` | De que país é o seu documento? | | `selphid_selector_country_placeholder` | Selecione um país | | `selphid_selector_country_search_label` | Escolha um país | | `selphid_selector_country_search_placeholder` | Busque um país | | `selphid_selector_country_search_clear` | Limpar busca | | `selphid_selector_country_no_results` | Sem resultados | | `selphid_selector_document_label` | Qual documento você usará? | | `selphid_selector_document_placeholder` | Selecione um documento | | `selphid_selector_document_dialog_title` | Escolha o documento | | `selphid_selector_document_dialog_cancel` | CANCELAR | | `selphid_selector_document_dialog_select` | SELECIONAR | | `selphid_selector_continue` | Continuar | | `selphid_selector_type_id_card` | Documento de identidade | | `selphid_selector_type_passport` | Passaporte | | `selphid_selector_type_drivers_license` | Licença de conduzir | | `selphid_selector_type_foreign_card` | Cartão de residência | | `selphid_selector_type_credit_card` | Cartão de crédito | | `selphid_selector_type_custom` | Personalizado | | `selphid_selector_type_visa` | Visto | ### Animações O componente utiliza animações **Lottie** (`.json`) tanto na *dica prévia* quanto nos *tutoriais*. Se desejar modificar as animações do SDK, deverão ser incluídos os arquivos com **o mesmo nome** na pasta `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 ```