> 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/captura-inteligente-de-documentos.md).

# Captura Inteligente de Documentos

Instale e inicie o Smart Capture para React Native. Saiba mais sobre opções de configuração, tratamento de eventos e tratamento de resultados.

## Visão geral

**Captura Inteligente** é uma experiência de captura de documentos reconstruída e mais inteligente. Em vez de dizer ao SDK qual tipo de documento e qual lado esperar em cada etapa, você apenas declara quais tipos de documento seu app aceita (`acceptedDocuments`) — o usuário captura e/ou envia uma foto do documento (dependendo do `validationType` que você configurar — captura pela câmera, envio pela galeria/arquivo, ou ambos), e a Captura Inteligente identifica sozinha o tipo e o lado do documento e os valida com base nessa lista. Ela também detecta sozinha se um documento tem uma única página (`FULL`) ou dois lados (`FRONT/BACK`), solicitando o segundo lado apenas quando necessário. Também inclui captura automática e pré-visualização opcionais, e usa a mesma sessão Certta que Face Liveness e Document Detector: configure suas credenciais uma vez com `useCerttaSdk().configureSDK(...)`, depois abra a interface de captura com `useCerttaSmartCapture().open(...)`.

{% content-ref url="/pages/63a792c243b12c173dac1a1c85a90070d7c817a9" %}
[Personalização de texto](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-texto.md)
{% endcontent-ref %}

{% content-ref url="/pages/046ea2610fff6f0ce96f5a5ba59e84db8daa3967" %}
[Personalização de cores](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-cores.md)
{% endcontent-ref %}

{% content-ref url="/pages/6581b421f5a4d25b5ffadee0519d0a036f8e3de3" %}
[Personalização de imagens](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-imagens.md)
{% endcontent-ref %}

## Pré-requisitos

Antes de prosseguir, certifique-se de que o Certta React Native SDK 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](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/installation-guide.md)
{% endcontent-ref %}

## Dependências

A Captura Inteligente é ativada a partir de `caf-modules-config.json` na raiz do app (o arquivo que o CocoaPods e o Gradle leem quando você instala as dependências nativas). Você não adiciona artefatos do Gradle ou CocoaPods manualmente — o plugin os obtém dessa configuração.

```json
{
  "modules": {
    "smartCapture": {
      "enabled": true,
      "autoCapture": false
    }
  }
}
```

<table><thead><tr><th>Campo</th><th width="105.05078125">Obrigatório?</th><th>Adiciona</th></tr></thead><tbody><tr><td><code>modules.smartCapture.enabled</code></td><td>Obrigatório</td><td>a ponte do Smart Capture (Android e iOS) e o hook <code>useCerttaSmartCapture</code> .</td></tr><tr><td><code>modules.smartCapture.autoCapture</code></td><td>Opcional</td><td>o provedor de captura automática LiteRT do Android. Necessário para que <code>enableAutoCapture</code> realmente faça algo no Android.</td></tr></tbody></table>

{% hint style="info" %}
A dependência de captura automática adicionará cerca de 3 MB ao tamanho do app Android — isso inclui o modelo e o mecanismo necessários para detectar documentos automaticamente de verdade.
{% endhint %}

{% hint style="warning" %}
Se `autoCapture` não estiver `true` em `caf-modules-config.json`, a Captura Inteligente volta para a captura manual apenas. Isso não é um erro lançado nem um `CerttaError` — o fluxo ainda abre e funciona — mas a Captura Inteligente registra uma mensagem no nível INFO (`"Missing auto capture dependency."`) no stream de logs do Certta (`useCerttaSdk().logs`). Se você não estiver lendo esse stream, nada parecerá obviamente errado; a captura será apenas manual o tempo todo.

A captura manual (o botão do obturador) sempre funciona, com ou sem captura automática.
{% endhint %}

{% hint style="info" %}
**A captura automática no Android requer os Serviços do Google Play no dispositivo.** O provedor opcional executa seu modelo de detecção pelos LiteRT do Play Services, então em dispositivos sem os Serviços do Google Play — ou quando eles estiverem desatualizados/indisponíveis — essa inicialização falha e a Captura Inteligente volta para a captura manual, igual a quando a dependência não foi adicionada de forma alguma. A captura manual não depende dos Serviços do Google Play.
{% endhint %}

***

## Iniciando a Captura Inteligente

Para iniciar o fluxo da Captura Inteligente, chame `open()` em `useCerttaSmartCapture()` e passe um objeto `CerttaSmartCaptureConfiguration` config. Os resultados chegam no `evento` (`success` / `error`).

{% hint style="info" %}
Certifique-se de que `configureSDK(...)` já tenha sido chamado para a sessão atual antes de chamar `open()`.
{% endhint %}

```typescript
import { useEffect } from 'react';
import { Button } from 'react-native';
import {
  useCerttaSdk,
  useCerttaSmartCapture,
  CafEnvironment,
  CerttaAcceptedDocumentType,
  type CerttaSmartCaptureConfiguration,
} from '@caf.io/react-native-sdk';

const config: CerttaSmartCaptureConfiguration = {
  acceptedDocuments: [CerttaAcceptedDocumentType.IDENTITY_CARD],
  showInstructions: true,
  enablePreview: true,
};

export function SmartCaptureScreen() {
  const { configureSDK } = useCerttaSdk();
  const { open, event } = useCerttaSmartCapture();

  useEffect(() => {
    configureSDK({
      mobileToken: '<MOBILE_TOKEN>',
      userId: '<USER_ID>',
      environment: CafEnvironment.PROD,
      securityEnabled: true,
    }).catch(console.error);
  }, [configureSDK]);

  useEffect(() => {
    if (event.success?.response) {
      // event.success.response
    }
    if (event.error) {
      // event.error.type, event.error.cause
    }
  }, [event]);

  return (
    <Button
      title="Open Smart Capture"
      onPress={() => {
        open(config).catch(console.error);
      }}
    />
  );
}
```

{% hint style="warning" %}
`open()` retorna uma Promise que é rejeitada se a ponte nativa não conseguir processar a chamada (módulo não ativado, JSON inválido). Falhas em tempo de execução durante o fluxo (permissão, rede, cancelamento) chegam em `event.error`, e não como rejeição de Promise. Trate ambos.
{% endhint %}

### `CerttaSmartCaptureConfiguration` parâmetros

Todos os parâmetros, exceto `acceptedDocuments` , têm valores padrão; substitua apenas o que precisar.

| Parâmetro            | Tipo                           | Padrão               | Descrição                                                                                                                                                                                  |
| -------------------- | ------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `acceptedDocuments`  | `CerttaAcceptedDocumentType[]` | Nenhum               | Tipos de documento permitidos para captura ou envio. Obrigatório — a Captura Inteligente falha em `open()` se estiver vazio.                                                               |
| `showInstructions`   | `boolean`                      | `true`               | Mostra telas de instruções antes de qualquer captura/envio.                                                                                                                                |
| `enablePreview`      | `boolean`                      | `true`               | Mostra uma prévia da imagem capturada para confirmação do usuário antes do envio.                                                                                                          |
| `enableAutoCapture`  | `boolean`                      | `true`               | Solicita captura automática quando os critérios de alinhamento forem atendidos. No Android, requer `modules.smartCapture.autoCapture: true`; volta para captura manual se estiver ausente. |
| `skipSuccessScreen`  | `boolean`                      | `false`              | Pula a tela de sucesso exibida após uma captura/envio bem-sucedido.                                                                                                                        |
| `validationType`     | `CerttaValidationType`         | `CAPTURE_AND_UPLOAD` | Quais fluxos são permitidos: `CAPTURE`, `UPLOAD`, ou `CAPTURE_AND_UPLOAD`.                                                                                                                 |
| `allowedUploadTypes` | `CerttaFileAcceptedType[]`     | todos os valores     | Formatos de arquivo aceitos da galeria/arquivos (`JPEG`, `PNG`, `PDF`, `HEIF`, `HEIC`). Um array vazio é tratado como todos os tipos.                                                      |

#### `CerttaAcceptedDocumentType`

| Valor                     | Tipos de documento locais aceitos |
| ------------------------- | --------------------------------- |
| `DRIVER_LICENSE`          | CNH                               |
| `IDENTITY_CARD`           | RG, CIN                           |
| `RESIDENCE_IDENTITY_CARD` | RNM, RNE                          |
| `EMPLOYMENT_CARD`         | CTPS                              |
| `VEHICLE_LICENSE`         | CRLV                              |
| `PASSPORT`                | Passaporte                        |
| `ANY`                     | Qualquer tipo de documento        |

***

### Comportamento e limites

* **Os documentos aceitos são obrigatórios.** `acceptedDocuments` deve conter pelo menos um valor. Um array vazio encerra o fluxo antes de a câmera ou o provedor de captura iniciar.
* **Um fluxo por vez.** Apenas um fluxo da Captura Inteligente pode ser executado por processo. Iniciar um segundo enquanto o primeiro estiver ativo falha com uma mensagem informando que uma sessão de captura já está em andamento.
* **Tamanho do arquivo de envio.** Arquivos maiores que **10 MB** são rejeitados. Esse limite não é configurável.
* **Quantidade de arquivos de envio.** O caminho de upload aceita um arquivo contendo o documento inteiro ou dois arquivos para frente e verso.

### **Entendendo os eventos e resultados da Captura Inteligente**

O hook escuta `SmartCaptureEvent.Success` e `SmartCaptureEvent.Error` e os expõe como `event.success` e `event.error`.

#### Sucesso — `CerttaSuccess`

`response` é um JWT/string assinado que contém os resultados da validação no servidor e os metadados do documento. A documentação da integração com seu backend ou com a Certta define como validar, decodificar e armazená-lo.

```json
{ response?: string }
```

#### Erro — `CerttaError`

```json
{ type: CerttaErrorType; cause: string }
```

| Tipo                  | Significado                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------ |
| `InitializationError` | Sessão não configurada ou configuração inválida (por exemplo, `acceptedDocuments`).        |
| `PermissionError`     | Permissão de runtime ausente (por exemplo, câmera).                                        |
| `SecurityError`       | A validação de segurança falhou (quando `securityEnabled` está ativo na sessão da Certta). |
| `NetworkError`        | Falha de rede/requisição.                                                                  |
| `UnknownError`        | Falha inesperada/não mapeada.                                                              |
| `Cancelled`           | O usuário fechou o fluxo.                                                                  |

### Subpáginas

{% content-ref url="/pages/63a792c243b12c173dac1a1c85a90070d7c817a9" %}
[Personalização de texto](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-texto.md)
{% endcontent-ref %}

{% content-ref url="/pages/046ea2610fff6f0ce96f5a5ba59e84db8daa3967" %}
[Personalização de cores](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-cores.md)
{% endcontent-ref %}

{% content-ref url="/pages/6581b421f5a4d25b5ffadee0519d0a036f8e3de3" %}
[Personalização de imagens](https://docs.caf.io/caf-sdk/caf-sdk-pt-br/react-native/captura-inteligente-de-documentos/personalizacao-de-imagens.md)
{% endcontent-ref %}


---

# 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/captura-inteligente-de-documentos.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.
