> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/document-detector.md).

# Document Detector

{% hint style="warning" %}
Este guia abrange a versão 7.14.0 e superior. Para versões anteriores à 7.14.0, consulte a [documentação legada](https://docs.caf.io/caf-sdk/android/getting-started-with-the-sdk-1).
{% endhint %}

## Pré-requisitos

Antes de continuar, certifique-se de que o Certta SDK esteja instalado corretamente. Se você ainda não fez isso, consulte nosso Guia de Instalação.

{% content-ref url="/pages/c4edac6f06cfb1bc5036e5a528cfe09e4dbd5ff6" %}
[Guia de Instalação](/caf-sdk/caf-sdk-pt-br/android/installation-guide.md)
{% endcontent-ref %}

## Iniciando o Document Detector

Para iniciar o fluxo do Document Detector, chame `DocumentDetector.instance.open()` e passe um `DocumentDetectorConfiguration` objeto.

{% hint style="info" %}
Este método aceita um callback para tratar os resultados e eventos disparados durante o fluxo do Document Detector.
{% endhint %}

{% hint style="info" %}
O `DocumentDetectorConfiguration` e `CerttaDocumentDetector` classes são componentes do módulo `io.caf.sdk:document-detector` .
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val config = DocumentDetectorConfiguration(
    flow = listOf(
        DocumentDetectorStep(Document.RG_FRONT),
        DocumentDetectorStep(Document.RG_BACK)
    )
)
CerttaDocumentDetector.instance.open(config) { event ->
    when(event) {
        is DocumentDetectorEvent.Success -> {
            //tratar sucesso
        }
        is DocumentDetectorEvent.Error -> {
            //tratar erro
        }
    }
}

```

{% endtab %}

{% tab title="Java" %}

<pre class="language-java"><code class="lang-java"><strong>var config = new DocumentDetectorConfiguration(
</strong>    Arrays.asList(
        new DocumentDetectorStep(Document.RG_FRONT),
        new DocumentDetectorStep(Document.RG_BACK)
    )
);
CerttaDocumentDetector.getInstance().open(config, event -> {
    if (event instanceof DocumentDetectorEvent.Success) {
        var successEvent = (DocumentDetectorEvent.Success) event;
        // tratar sucesso
    } else if (event instanceof DocumentDetectorEvent.Error) {
        var errorEvent = (DocumentDetectorEvent.Error) event;
        // tratar erro
    }
});

</code></pre>

{% endtab %}
{% endtabs %}

### `DocumentDetectorConfiguration` Parâmetros

| Parâmetro          | Padrão                            | Descrição                                                                                                                    |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `fluxo`            | *Nenhum*                          | A lista ordenada de etapas que define quais documentos capturar (por exemplo, frente e verso). Este parâmetro é obrigatório. |
| `uploadSettings`   | `UploadSettings(false)`           | Configurações para envio das imagens do documento capturadas.                                                                |
| `showPreview`      | `true`                            | Mostra uma tela de pré-visualização do documento capturado para confirmação do usuário quando verdadeiro.                    |
| `requestTimeout`   | `60`                              | O tempo máximo permitido (em segundos) para que as solicitações de rede sejam concluídas antes do tempo limite.              |
| `showPopup`        | `false`                           | Exibe um pop-up de orientação durante o processo de captura quando verdadeiro.                                               |
| `customization`    | `DocumentDetectorCustomization()` | Um objeto que contém configurações de personalização visual e branding para a interface do detector.                         |
| `maxRetryAttempts` | `3`                               | Máximo de novas tentativas após uma tentativa de captura com falha.                                                          |

## Iniciando a interface do Document Detector

Para iniciar o fluxo do Document Detector com uma interface de usuário personalizada, chame `CerttaDocumentDetectorUi.instance.open()` e passe um `DocumentDetectorUiConfiguration` objeto.

{% hint style="info" %}
O `DocumentDetectorUiConfiguration` e `CerttaDocumentDetectorUi` classes são componentes do módulo `io.caf.sdk:document-detector-ui` .
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}

```kotlin
val config = DocumentDetectorUiConfiguration(
    documentSelectionScreen = CafDocumentDetectorDocumentSelectionScreen(
        documents = listOf(CafDocument.RGFront(), CafDocument.RGBack()),
    )
)
CerttaDocumentDetectorUi.instance.open(config) { event ->
    when(event) {
        is DocumentDetectorEvent.Success -> {
            //tratar sucesso
        }
        is DocumentDetectorEvent.Error -> {
            //tratar erro
        }
    }
}

```

{% endtab %}

{% tab title="Java" %}

```java
var config = new DocumentDetectorUiConfiguration(
    new CafDocumentDetectorDocumentSelectionScreen(
        Arrays.asList(new CafDocument.RGFront(), new CafDocument.RGBack())
    )
);
CerttaDocumentDetectorUi.getInstance().open(config, event -> {
    if (event instanceof DocumentDetectorEvent.Success) {
        var successEvent = (DocumentDetectorEvent.Success) event;
        // tratar sucesso
    } else if (event instanceof DocumentDetectorEvent.Error) {
        var errorEvent = (DocumentDetectorEvent.Error) event;
        // tratar erro
    }
});
```

{% endtab %}
{% endtabs %}

### `DocumentDetectorUiConfiguration` Parâmetros

| Parâmetro                 | Padrão                                    | Descrição                                                                                                   |
| ------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `documentSelectionScreen` | *Nenhum*                                  | Configura a tela onde os usuários selecionam o tipo de documento a ser capturado. (Obrigatório)             |
| `layoutId`                | `null`                                    | ID opcional de recurso de layout personalizado (`@LayoutRes`) usado para substituir o layout padrão do SDK. |
| `instructionsScreen`      | `CafDocumentDetectorInstructionsScreen()` | Configura a tela que exibe instruções ao usuário antes do início da digitalização.                          |
| `uploadSettings`          | `UploadSettings(false)`                   | Configurações para envio das imagens do documento capturadas.                                               |
| `showPreview`             | `true`                                    | Quando verdadeiro, exibe uma tela de pré-visualização para o usuário confirmar o documento capturado.       |
| `requestTimeout`          | `60`                                      | Tempo máximo permitido (em segundos) para que as solicitações de rede sejam concluídas.                     |
| `showPopup`               | `true`                                    | Quando verdadeiro, exibe um pop-up ou sobreposição de orientação durante o processo de captura.             |
| `maxRetryAttempts`        | `3`                                       | Número máximo de tentativas permitidas após uma tentativa de captura com falha.                             |
| `customization`           | `DocumentDetectorCustomization()`         | Define configurações de personalização visual e branding para a interface do detector.                      |

### Aprofundamento nas personalizações

Para saber mais sobre como estilizar e configurar a interface do Document Detector, explore nosso guia dedicado de personalização:

{% content-ref url="/pages/d86ce32cb5727e7b5f32c05d341e4b605fd25de2" %}
[Personalizações de UI](/caf-sdk/caf-sdk-pt-br/android/document-detector/ui-customizations.md)
{% endcontent-ref %}

## Documentos suportados

| Documento      | Descrição                                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `RG_FRENTE`    | Lado frontal do documento RG, onde a foto está localizada.                                                                     |
| `RG_VERSO`     | Lado de trás do documento RG.                                                                                                  |
| `RG_COMPLETO`  | Documento RG aberto, exibindo juntos os lados frontal e traseiro.                                                              |
| `CNH_FRENTE`   | Lado frontal do documento CNH, onde a foto está localizada.                                                                    |
| `CNH_VERSO`    | Lado de trás do documento CNH.                                                                                                 |
| `CNH_COMPLETO` | Documento CNH aberto, exibindo juntos os lados frontal e traseiro.                                                             |
| `CRLV`         | Documento CRLV.                                                                                                                |
| `RNE_FRENTE`   | Lado frontal do documento RNE ou RNM.                                                                                          |
| `RNE_VERSO`    | Lado de trás do documento RNE ou RNM.                                                                                          |
| `PASSAPORTE`   | Documento de passaporte, exibindo a foto e os dados pessoais.                                                                  |
| `CTPS_FRENTE`  | Lado frontal do documento CTPS, onde a foto está localizada.                                                                   |
| `CTPS_VERSO`   | Lado de trás do documento CTPS.                                                                                                |
| `QUALQUER`     | Permite o envio de qualquer tipo de documento, incluindo todos os listados acima ou qualquer outro documento não classificado. |

## Entendendo os eventos e resultados do Document Detector

Para tratar o resultado do fluxo do Document Detector, passe um callback para o `CerttaDocumentDetector.instance.open()` método para ouvir eventos de **sucesso** ou **erro** eventos.

### `DocumentDetectorEvent.Success`

Disparado quando o documento é capturado e processado com sucesso.

* `response: String`: Um JWT contendo os dados de resultado retornados pelo fluxo do Document Detector. Esses dados podem incluir informações relevantes para o processo, como imagens capturadas ou resultados de validação.

{% hint style="warning" %}
Garanta que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos `estáVivo` e `éCorrespondente` campos. Não realize essas validações no lado do cliente.
{% endhint %}

### `DocumentDetectorEvent.Error`

Disparado quando o processo de captura falha por qualquer motivo (por exemplo, problemas de rede, cancelamento pelo usuário, negações de permissão da câmera ou erros de configuração).

* `error: CerttaError`: Um objeto que contém informações detalhadas sobre a falha, como o código de erro específico e a mensagem. Isso permite identificar a causa exata da falha e tratá-la adequadamente.

| Evento                  | Causa típica                                                                                                                              |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `erro de inicialização` | **`configurar`** não chamado, token ou ID de usuário vazio, ou inválido **`maxRetryAttempts`**.                                           |
| `erro de permissão`     | Permissão da câmera (ou relacionada) negada.                                                                                              |
| `erro de rede`          | Problemas de conectividade ou do lado do servidor se manifestam como erros da classe de rede.                                             |
| `erro de segurança`     | As verificações de segurança falharam.                                                                                                    |
| `erro desconhecido`     | Outras falhas não mapeadas para um caso específico.                                                                                       |
| `cancelado`             | Ocorre quando o usuário abandona o fluxo antes da conclusão, como ao pressionar o botão voltar ou enviar o aplicativo para segundo plano. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-sdk/caf-sdk-pt-br/android/document-detector.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.