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

# Document Detector

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

{% hint style="warning" %}
Este guia aborda **@caf.io/react-native-sdk 5.4.0** e acima (Certta DevX). Para o sequencial anterior `useCafSdk` fluxo, veja o [documentação legada](https://docs.caf.io/caf-sdk/react-native/getting-started-with-the-sdk).
{% endhint %}

## Pré-requisitos

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

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

Ativar `documentDetector` (e `documentDetectorUI` se você quiser a interface de usuário integrada) em `caf-modules-config.json`.

## Iniciando o Document Detector

Use `useCafDocumentDetector` e chamar `open()` com um `CerttaDocumentDetectorConfiguration` objeto. Leia os resultados do hook `evento` estado.

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

```typescript
import { useEffect } from 'react';
import {
  useCafDocumentDetector,
  CafDocument,
} from '@caf.io/react-native-sdk';

function DocumentCapture() {
  const { open, event } = useCafDocumentDetector();

  useEffect(() => {
    if (event.success) {
      // Lidar com sucesso — event.success.response é um JWT
    } else if (event.error) {
      // Tratar erro
    }
  }, [event]);

  const startCapture = async () => {
    try {
      await open({
        flow: [
          { document: CafDocument.RG_FRONT },
          { document: CafDocument.RG_BACK },
        ],
      });
    } catch {
      // Trate BRIDGE_EXCEPTION
    }
  };

  // ...
}
```

`open()` rejeita com `CerttaPlatformException` e 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 das etapas de captura. **Obrigatório.**                                 |
| `uploadSettings`              | `null`   | Configurações para envio de imagens de documentos.                                     |
| `showPreview`                 | `true`   | Exibe 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`      | Máximo de tentativas após uma captura com falha. Use `0` para desativar as tentativas. |
| `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

Use `useCafDocumentDetectorUI` e chamar `open()` com 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 %}

```typescript
import { useCafDocumentDetectorUI, CafDocument } from '@caf.io/react-native-sdk';

function DocumentCaptureUI() {
  const { open, event } = useCafDocumentDetectorUI();

  const startCapture = async () => {
    try {
      await open({
        flow: [
          { document: CafDocument.RG_FRONT },
          { document: CafDocument.RG_BACK },
        ],
        documentSelectionScreen: {
          title: 'Escolha um documento',
          description: 'Selecione o documento que você quer usar',
        },
      });
    } catch {
      // Trate BRIDGE_EXCEPTION
    }
  };

  // ...
}
```

### `CerttaDocumentDetectorUIConfiguration` parâmetros

Herda todos os campos de `CerttaDocumentDetectorConfiguration`, mais:

| 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`. |

### Mergulho profundo nas personalizações

{% content-ref url="/pages/a179e62172a5f185d5306a764577fbcf8b01d300" %}
[Personalizações da UI](/caf-sdk/caf-sdk-pt-br/react-native/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 TypeScript, use o `CafDocument` enum (`CafDocument.RG_FRONT`, `CafDocument.CNH_BACK`, `CafDocument.PASSPORT`, e assim por diante).

### 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 os 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, recusas de permissão da câmera ou erros de configuração).

* `type`: identificador de erro mapeado a partir do SDK nativo.
* `causa`: 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/react-native/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.