> 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/flutter/document-detector.md).

# Document Detector

Instale e inicie o Document Detector para Flutter. Aprenda sobre opções de configuração, configuração da interface, caminhos de personalização, fluxos de eventos e tratamento de resultados.

{% hint style="warning" %}
Este guia aborda **caf\_sdk 2.4.0** e superiores (Certta DevX). Para a versão anterior `CafSdk` fluxo sequencial, consulte a [documentação legada](https://docs.caf.io/caf-sdk/flutter/getting-started-with-the-sdk).
{% endhint %}

## Pré-requisitos

Antes de prosseguir, 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/d82530ac6e7f99d44e236a0f308e73c6cf5d0223" %}
[Guia de Instalação](/caf-sdk/caf-sdk-pt-br/flutter/installation-guide.md)
{% endcontent-ref %}

Ativar `documentDetector` (e `documentDetectorUI` se você quiser a UI integrada) em `caf-modules-config.json`.

Assine o `eventStream` **antes de** chamar `open()`.

## Iniciando o Document Detector

Para iniciar o fluxo do Document Detector, chame `certta.documentDetector.open()` e passe um `CerttaDocumentDetectorConfiguration` objeto.

{% hint style="info" %}
`CerttaDocumentDetectorConfiguration` e `CerttaDocumentDetector` são o módulo sem interface do Document Detector. A `fluxo` lista é obrigatória.
{% endhint %}

```dart
import 'package:flutter/services.dart';
import 'package:caf_sdk/certta_sdk.dart';

final certta = CerttaSdk();

certta.documentDetector.eventStream.listen((event) {
  if (event.success != null) {
    // Trate o sucesso — event.success!.response é um JWT
  } else if (event.error != null) {
    // Trate o erro
  }
});

try {
  await certta.documentDetector.open(
    CerttaDocumentDetectorConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
    ),
  );
} on PlatformException catch (e) {
  // Trate o BRIDGE_EXCEPTION
}
```

`open()` lança um `PlatformException` com o código `BRIDGE_EXCEPTION` quando o mapeador nativo rejeita a configuração.

### `CerttaDocumentDetectorConfiguration` parâmetros

| Parâmetro                     | Padrão   | Descrição                                                                                    |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `fluxo`                       | *Nenhum* | Lista ordenada de etapas de captura. **Obrigatório.**                                        |
| `uploadSettings`              | `null`   | Configurações para envio de imagens do documento.                                            |
| `showPreview`                 | `true`   | Mostra uma tela de pré-visualização para confirmação do usuário quando `true`.               |
| `requestTimeout`              | `60`     | Tempo máximo (em segundos) para solicitações de rede.                                        |
| `showPopup`                   | `false`  | Exibe um pop-up de orientação durante a captura quando `true`.                               |
| `maxRetryAttempts`            | `3`      | Número máximo de tentativas após uma captura com falha. Use `-1` para tentativas ilimitadas. |
| `messageCustomization`        | `null`   | Mensagens de captura no fluxo.                                                               |
| `previewCustomization`        | `null`   | Texto da tela de pré-visualização.                                                           |
| `uploadCustomization`         | `null`   | Texto da caixa de diálogo de envio.                                                          |
| `uploadMessagesCustomization` | `null`   | Mensagens exibidas enquanto o documento é enviado e processado.                              |
| `retryCustomization`          | `null`   | Texto da tela de nova tentativa.                                                             |

## Iniciando a interface do Document Detector

Para iniciar o Document Detector com o módulo de interface personalizada, chame `certta.documentDetectorUi.open()` e passe um `CerttaDocumentDetectorUiConfiguration`.

{% hint style="info" %}
Ativar `documentDetectorUI` em `caf-modules-config.json`. A camada nativa mapeia `fluxo` para a tela de seleção de documento.
{% endhint %}

```dart
import 'package:flutter/services.dart';

try {
  await certta.documentDetectorUi.open(
    CerttaDocumentDetectorUiConfiguration(
      flow: [
        CafDocumentDetectorFlow(document: CafDocument.rgFront),
        CafDocumentDetectorFlow(document: CafDocument.rgBack),
      ],
      documentSelectionScreen:
          const CafDocumentDetectorUIDocumentSelectionScreenConfiguration(
        title: 'Escolha um documento',
        description: 'Selecione o documento que você quer usar',
      ),
    ),
  );
} on PlatformException catch (e) {
  // Trate o BRIDGE_EXCEPTION
}

certta.documentDetectorUi.eventStream.listen((event) {
  if (event.success != null) {
    // Trate o sucesso
  } else if (event.error != null) {
    // Trate o erro
  }
});
```

### `CerttaDocumentDetectorUiConfiguration` parâmetros

Herda todos os campos de `CerttaDocumentDetectorConfiguration`, além de:

| Parâmetro                 | Padrão | Descrição                                                                  |
| ------------------------- | ------ | -------------------------------------------------------------------------- |
| `instructionScreen`       | `null` | Instruções exibidas antes da câmera ou da galeria de arquivos.             |
| `documentSelectionScreen` | `null` | Título e descrição do seletor de documentos. Os documentos vêm de `fluxo`. |

### Aprofundamento nas personalizações

{% content-ref url="/pages/f975bd7beb8a081d4224fb58ae4011db4978678b" %}
[Personalizações da UI](/caf-sdk/caf-sdk-pt-br/flutter/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. |

Em Dart, use o `CafDocument` enum (`CafDocument.rgFront`, `CafDocument.cnhBack`, `CafDocument.passport`, e assim por diante). Os valores acima são os identificadores serializados.

### Formatos de arquivo suportados (`CafFileFormat`)

Usado por `CafDocumentDetectorUploadSettings.fileFormats`.

| Tipo   | Valor             |
| ------ | ----------------- |
| `PNG`  | `image/png`       |
| `JPG`  | `image/jpg`       |
| `JPEG` | `image/jpeg`      |
| `PDF`  | `application/pdf` |
| `HEIF` | `image/heif`      |
| `HEIC` | `image/heic`      |

{% hint style="info" %}
O suporte completo a HEIC está disponível apenas no iOS.
{% endhint %}

## Entendendo eventos e resultados do Document Detector

### `success` (`CerttaSuccess`)

Disparado quando o documento é capturado e processado com sucesso.

* `response`: um JWT com os dados de resultado do fluxo do Document Detector.

{% 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 %}

### `error` (`CerttaError`)

Disparado quando a captura falha (problemas de rede, cancelamento do usuário, negações de permissão da câmera ou erros de configuração).

* `type`: identificador de erro mapeado a partir do SDK nativo.
* `cause`: contexto adicional, quando presente.

| Evento                  | Causa típica                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Erro de inicialização` | **`configurar`** não chamado, token vazio 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 aparecem como erros 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 app 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.