> 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/subida-de-ficheros-y-gestion-de-qr.md).

# Envio de arquivos e gerenciamento de QR - Capture

## Introdução <a href="#id-1-introduccion" id="id-1-introduccion"></a>

A captura de documentos e a leitura e geração de QR codes são realizadas com o ***CaptureComponent***.

Este componente permite enviar documentos tirando uma foto com a câmera do dispositivo ou selecionando uma imagem da galeria.

***

## Dependência <a href="#id-2-dependencia" id="id-2-dependencia"></a>

A dependência específica do componente é:

```
implementation "com.facephi.androidsdk:capture_component:$version"
```

***

## Controladores disponíveis <a href="#id-3-controladores-disponibles" id="id-3-controladores-disponibles"></a>

| **Controlador**        | **Descrição**                          |
| ---------------------- | -------------------------------------- |
| FileUploaderController | Controlador para captura de documentos |
| QrReaderController     | Controlador para captura de QR codes   |
| QrGeneratorController  | Controlador para geração de QR codes   |

***

## Lançamento simplificado <a href="#id-4-lanzamiento-simplificado" id="id-4-lanzamiento-simplificado"></a>

Depois que o SDK for inicializado e uma nova operação for criada, será possível iniciar o componente. Qualquer um dos controladores poderá ser usado para executar sua funcionalidade.

Inicialização da captura de documentos:

```kotlin
val response = SDKController.launch(
    FileUploaderController(FileUploaderConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

Inicialização da captura de QR code:

```kotlin
val response = SDKController.launch(
    QrReaderController(QrCaptureConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

Inicialização da geração de QR code:

```kotlin
val response = SDKController.launch(
    QrGeneratorController(QrGeneratorConfiguration(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}
```

***

## Configuração básica <a href="#id-5-configuracion-basica" id="id-5-configuracion-basica"></a>

Para os controladores de captura de documentos e de QR code, é possível gerar a configuração com os parâmetros padrão. Para gerar o QR code, será necessário informar o texto que será utilizado:

```
QrGeneratorConfiguration(source = "QR text")
```

***

## Recebimento do resultado <a href="#id-6-recepcion-del-resultado" id="id-6-recepcion-del-resultado"></a>

A inicialização retornará as informações no formato SdkResult, permitindo diferenciar uma inicialização bem-sucedida de uma malsucedida:

```kotlin
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error}")
    is SdkResult.Success -> response.data
}
```

### Recebimento de erros <a href="#id-61-recepcion-de-errores" id="id-61-recepcion-de-errores"></a>

Os erros serão retornados como um objeto 'CaptureError'.

Lista de erros:

* `ACTIVITY_RESULT_MSG_ERROR` (`CAP_855`): O resultado retornado pela atividade é inválido ou não contém as informações necessárias para continuar.
* `APPLICATION_CONTEXT_ERROR` (`CAP_856`): O contexto da aplicação necessário é nulo ou inválido, impedindo a inicialização correta do módulo de captura.
* `CAMERA_ERROR` (`CAP_853`): Ocorreu um erro interno relacionado à câmera do dispositivo (falha ao abrir, inicializar ou capturar).
* `CAMERA_PERMISSION_DENIED` (`CAP_852`): O usuário negou as permissões necessárias para acessar a câmera.
* `CANCEL_BY_USER` (`CAP_000`): O usuário cancelou manualmente o processo de captura.
* `CANCEL_LAUNCH` (`CAP_007`): O processo foi cancelado de forma geral pelo SDK ou por uma ação externa.
* `COMPONENT_LICENSE_ERROR` (`CAP_002`): A licença do componente é inválida, expirou ou não corresponde à configuração necessária.
* `EMPTY_LICENSE` (`CAP_003`): A string da licença está vazia ou não foi fornecida.
* `FETCH_DATA_ERROR` (`CAP_858`): Ocorreu um erro ao obter ou processar os dados necessários para executar o fluxo. *(Inclui informações adicionais no campo `error`.)*
* `FLOW_ERROR` (`CAP_863`): Ocorreu um erro interno durante a execução do fluxo de captura. *(Inclui informações adicionais no campo `error`.)*
* `INITIALIZATION_ERROR` (`CAP_004`): Erro ao inicializar os componentes necessários do SDK. *(Inclui informações detalhadas no campo `error`.)*
* `FILE_UPLOADER_CAPTURE_ERROR` (`CAP_850`): Erro durante o processo de upload dos arquivos gerados na captura.
* `INTERNAL_ERROR` (`CAP_861`): Erro interno inesperado durante a execução. *(Inclui informações adicionais no campo `error`.)*
* `IMAGE_TOO_LARGE` (`CAP_862`): A imagem selecionada na galeria excede o tamanho máximo configurado em `maxGalleryImageSizeKb`.
* `MANAGER_NOT_INITIALIZED` (`CAP_857`): Os managers necessários para executar o processo não foram inicializados corretamente.
* `NO_DATA_ERROR` (`CAP_005`): Os dados de entrada necessários são nulos, inexistentes ou insuficientes para continuar o processo.
* `OPERATION_NOT_CREATED` (`CAP_006`): Não foi possível criar ou recuperar uma operação ativa necessária para continuar. *(Inclui informações detalhadas no campo `error`.)*
* `QR_CAPTURE_ERROR` (`CAP_851`): Erro durante a captura ou leitura do código QR.
* `QR_GENERATION_ERROR` (`CAP_854`): Erro ao gerar o código QR solicitado.
* `TIMEOUT` (`CAP_001`): O tempo máximo permitido foi atingido em uma das etapas do processo.
* `FLOW_VIDEO_RECORDING_ERROR` (`CAP_859`): Erro durante a Gravação de Vídeo dentro do fluxo estabelecido.
* `FLOW_TRACKING_ERROR` (`CAP_860`): Erro ao realizar o Tracking necessário para concluir o fluxo de captura.

### Recebimento do resultado correto - *data* <a href="#id-62-recepcion-del-resultado-correcto-data" id="id-62-recepcion-del-resultado-correcto-data"></a>

#### **Recebimento do resultado da captura de documentos**

Na parte de SdkResult.Success - *data*, teremos a classe *FileUploaderResult*.

Os campos retornados no resultado são os seguintes:

***capturedDocumentList***

Lista de arquivos capturados. Podem ser imagens ou PDFs. Os campos retornados de cada um são:

* mimeType: `String`
* timestampMillis: `Long`
* content: `FileContent`. Conteúdo do documento. Será diferente se for uma imagem ou um documento PDF. Para diferenciá-los:

```kotlin
capturedDocumentList.forEach { documentData ->
                            when (val content = documentData.content) {
                                is FileContent.UploaderImage -> {
                                    // Uploader: New image found
                                    // content.image
                                }

                                is FileContent.UploaderDocument -> {
                                    // Uploader: New document found
                                    // content.bytes
                                }
                            }
                        }
```

Campos de cada tipo de conteúdo:

* `FileContent.UploaderImage`:
  * `image`: `SdkImage`. Imagem capturada.
  * `rotationDegrees`: `Int`. Rotação da imagem em graus.
  * `source`: `FileUploaderSource`. Origem da imagem. Valores possíveis: `CAMERA`, `GALLERY`.
* `FileContent.UploaderDocument`:
  * `frontPageImage`: `SdkImage?`. Imagem da primeira página do PDF (pode ser nula).
  * `bytes`: `ByteArray`. Conteúdo do PDF.

#### **Recebimento do resultado da captura de QR**

Na parte de SdkResult.Success - *data*, teremos a classe *QrResult*.

Os campos retornados no resultado são os seguintes:

***qrText***

Texto obtido do QR

#### **Recebimento do resultado da geração do QR**

Na parte de SdkResult.Success - *data*, teremos um `SdkImage` com o QR criado.

***

## Informações avançadas <a href="#id-7-informacion-avanzada" id="id-7-informacion-avanzada"></a>

Esta seção detalha as informações do componente.

### Configuração avançada do componente <a href="#id-71-configuracion-avanzada-del-componente" id="id-71-configuracion-avanzada-del-componente"></a>

#### **Configuração da captura de documentos**

Para iniciar o componente atual, será necessário criar um objeto *FileUploaderConfigurationData* que será a configuração do controlador do componente.

A seguir, estão detalhados todos os campos que fazem parte desta classe.

* `vibrationEnabled`: `Boolean`. Indica a ativação da vibração quando o widget for concluído com sucesso. O padrão é `true`.
* `extractionTimeout`: `Long`. Define o tempo máximo durante o qual a captura pode ser realizada, em milissegundos. O padrão é `60000`.
* `showDiagnostic`: `Boolean`. Exibe telas de diagnóstico ao final do processo. O padrão é `true`.
* `showPreviousTip`: `Boolean`. Exibe uma tela antes de iniciar a captura, com informações sobre o processo a ser realizado e um botão para iniciá-la. O padrão é `true`.
* `maxScannedDocs`: `Int`. Número máximo de documentos que podem ser capturados. O padrão é `2`.
* `allowGallery`: `Boolean`. Habilita o acesso à galeria para obter imagens ou PDFs. O padrão é `true`.
* `onlyGalleryMode`: `Boolean`. Se estiver ativo, o fluxo será aberto diretamente no modo galeria e não exibirá a captura pela câmera. O padrão é `true`.
* `maxGalleryImageSizeKb`: `Int`. Tamanho máximo permitido para imagens selecionadas na galeria, em KB. O padrão é `2048`; se for excedido, será retornado `CAP_IMAGE_TOO_LARGE`.

#### **Configuração da captura de QR**

Para iniciar o componente atual, será necessário criar um objeto *QrCaptureConfigurationData* que será a configuração do controlador do componente.

A seguir, estão detalhados todos os campos que fazem parte desta classe.

* `vibrationEnabled`: `Boolean`. Indica a ativação da vibração quando o widget for concluído com sucesso. O padrão é `true`.
* `extractionTimeout`: `Long`. Define o tempo máximo durante o qual a captura pode ser realizada, em milissegundos. O padrão é `60000`.
* `showDiagnostic`: `Boolean`. Exibe telas de diagnóstico ao final do processo. O padrão é `true`.
* `showPreviousTip`: `Boolean`. Exibe uma tela antes de iniciar a captura, com informações sobre o processo a ser realizado e um botão para iniciá-la. O padrão é `true`.
* `showTutorial`: `Boolean`. Indica se o componente ativa a tela de tutorial. Nessa tela, é explicado de forma intuitiva como fazer a captura. Por padrão `true`.
* `cameraPreferred`: `Camera`. Câmera usada para a captura. Valores possíveis: `FRONT`, `BACK`. Por padrão `BACK`.
* `cameraShape`: `CameraShape`. Permite escolher o formato da máscara da câmera. Valores possíveis: `SQUARE`, `CIRCULAR`, `RECTANGLE_TALL`. Por padrão `SQUARE`.
* `showStroke`: `Boolean`. Exibe a borda da máscara da câmera. Por padrão `false`.
* `transparentBackground`: `Boolean`. Indica se o fundo da tela de captura é transparente. Por padrão `false`.

#### **Configuração da geração de QR**

Para iniciar o componente atual, é necessário criar um objeto *QrGeneratorConfiguration* que será a configuração do controlador do componente.

A seguir, estão detalhados todos os campos que fazem parte desta classe.

* `source`: `String`. Texto usado para gerar o QR. Obrigatório.
* `width`: `Int`. Largura, em pixels, da imagem gerada. Por padrão `200`.
* `height`: `Int`. Altura, em pixels, da imagem gerada. Por padrão `200`.

***

## Personalização do componente <a href="#id-8-personalizacion-del-componente" id="id-8-personalizacion-del-componente"></a>

Além das alterações que podem ser feitas no nível do SDK (explicadas no documento de ([Personalização do SDK](https://docs.facephi.com/docs.facephi-pt-br/sdks/sdk-mobile/android-sdk/personalizacion.md)), este componente específico permite modificar sua interface.

### Textos <a href="#id-81-textos" id="id-81-textos"></a>

Para modificar os textos do SDK, é necessário incluir o seguinte arquivo XML no aplicativo do cliente e alterar o valor de cada *String* pelo desejado.

```
<resources>
    <!-- Previous Tip -->
    <string name="capture_component_qr_tip_title">Escaneie o código QR</string>
    <string name="capture_component_qr_tip_message">&lt;b&gt; Aponte &lt;/b&gt; o código QR &lt;b&gt; para dentro do quadro &lt;/b&gt;</string>
    <string name="capture_component_qr_tip_button">Começar</string>
    <string name="capture_component_qr_tip_anim_desc">Animação de um celular tirando uma foto de um código QR. Na tela do celular, aparece um quadro. Quando o código QR se encaixa no quadro, o aplicativo tira uma foto.</string>
    <string name="capture_component_qr_tutorial_1_anim_desc">Um código QR é exibido sobre um fundo branco. As bordas do código QR não são claramente distinguíveis. Por meio de uma animação, o fundo muda de cor.</string>
    <string name="capture_component_qr_tutorial_2_anim_desc">Um celular tira uma foto de um Código QR. O Código QR aparece na horizontal, e o celular, na vertical. Na tela do celular aparece um quadro. Quando o Código QR se encaixa no quadro, o aplicativo tira uma foto.</string>
    <!-- Tutorial -->
    <string name="capture_component_qr_tutorial_1">Certifique-se de que o Código QR tenha &lt;b&gt; luz suficiente &lt;/b&gt; e que &lt;b&gt; não haja reflexos &lt;/b&gt; ou brilhos sobre o código.</string>
    <string name="capture_component_qr_tutorial_2">Encaixe as bordas do Código QR dentro do quadro.</string>
    <!-- Process -->
    <string name="capture_component_qr_camera_message">Mantenha o QR no centro</string>
    <string name="capture_component_button_message">Capturar</string>
    <!-- Diagnostic -->
    <string name="capture_component_timeout_title">Tempo esgotado</string>
    <string name="capture_component_timeout_desc">Pedimos desculpas. Não foi possível fazer a captura</string>
    <string name="capture_component_internal_error_title">Ocorreu um problema técnico</string>
    <string name="capture_component_internal_error_desc">Pedimos desculpas. Não foi possível fazer a captura</string>

    <!-- WIDGET -->
    <!-- Previous Tip -->
    <string name="capture_widget_tip_title">Escanear documentos</string>
    <string name="capture_widget_tip_message">Tire uma foto do documento ou envie uma imagem.&lt;br&gt;&lt;br&gt; Você pode escanear vários documentos antes de finalizar.</string>
    <string name="capture_widget_tip_message_alt">Tire uma foto do documento ou envie uma imagem. Você pode escanear vários documentos antes de finalizar.</string>
    <string name="capture_widget_tip_button">Começar</string>
    <string name="capture_widget_tip_button_alt">Começar a captura de documentos</string>
    <string name="capture_widget_tip_close_button_alt">Voltar</string>
    <string name="capture_widget_tip_info_button_alt">Ver dicas</string>
    <string name="capture_widget_tip_anim_desc">Animação de um celular tirando uma foto de um documento. Na tela do celular aparece um quadro. Quando o documento se encaixa no quadro, o aplicativo tira uma foto.</string>
    <!-- Camera -->
    <string name="capture_widget_document_camera_button_gallery">Galeria</string>
    <string name="capture_widget_document_camera_button_capture">Capturar</string>
    <string name="capture_widget_document_camera_button_cancel">Cancelar captura</string>
    <string name="capture_widget_document_camera_button_finish">Finalizar</string>
    <!-- Gallery -->
    <string name="capture_widget_gallery_images">Imagens</string>
    <string name="capture_widget_gallery_pdf">Selecionar PDF</string>
    <string name="capture_widget_gallery_cancel">Cancelar</string>
    <!-- Confirmação -->
    <string name="capture_widget_image_captured">Imagem capturada</string>
    <string name="capture_widget_confirmation_message">Todos os dados estão legíveis e nítidos?</string>
    <string name="capture_widget_confirmation_retry">NÃO, QUERO TIRAR AS FOTOS NOVAMENTE</string>
    <string name="capture_widget_confirmation_continue">Sim, finalizar</string>
    <string name="capture_widget_confirmation_delete">Apagar foto</string>
    <string name="capture_widget_confirmation_image_unavailable">Pré-visualização indisponível</string>
    <string name="capture_widget_confirmation_no_images">Não há capturas disponíveis</string>
    <string name="capture_widget_confirmation_delete_dialog_title">Deseja excluir este documento?</string>
    <string name="capture_widget_confirmation_delete_dialog_message">Ao excluir este documento, você não poderá recuperá-lo. Será necessário tirar uma nova foto.</string>
    <string name="capture_widget_confirmation_delete_dialog_cancel">CANCELAR</string>
    <string name="capture_widget_confirmation_delete_dialog_confirm">EXCLUIR DOCUMENTO</string>
    <!-- Diagnostic -->
    <string name="capture_widget_timeout_title">Tempo esgotado</string>
    <string name="capture_widget_timeout_desc">Pedimos desculpas. Não foi possível fazer a captura</string>
    <string name="capture_widget_internal_error_title">Ocorreu um problema técnico</string>
    <string name="capture_widget_internal_error_desc">Pedimos desculpas. Não foi possível fazer a captura</string>

</resources>

```

### Animações <a href="#id-82-animaciones" id="id-82-animaciones"></a>

Se desejar modificar as animações (lottie) do SDK, será necessário incluir as animações com o mesmo nome na pasta res/raw/ do aplicativo.

```
qr_anim_tip_1.json
qr_anim_tip_2.json
capture_anim_tip.json
```
