> 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/ios/getting-started-with-the-sdk-2.md).

# Document Detector

Instale e configure o Document Detector para iOS com Certta e CafSDK. Aprenda sobre requisitos, configuração de sessão, fluxo de captura de documentos, configuração da UI, delegates, temas e suporte.

{% hint style="warning" %}

## Este guia abrange a versão 7.0.0 e superiores. Para versões anteriores à 7.0.0, consulte a [documentação legada](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-5.md).

{% endhint %}

## Visão geral

**Detector de Documentos para iOS** orienta o usuário durante a captura e validação de documentos de identidade (RG, CNH, passaporte etc.). Com **Certta**, você o executa na mesma sessão que Face Liveness e Smart Capture: configure as credenciais uma vez e, em seguida, abra o fluxo nativo com **`CerttaDocumentDetector`**.

Este guia aborda pré-requisitos, **Certta** requisitos da sessão, **`CerttaDocumentDetectorConfiguration`** (incluindo **`CerttaDocumentDetectorUIConfiguration`**), **`abrir`** / **`loadSession`**, resultados em **`CerttaDocumentDetectorDelegate`**, cancelamento e logs em **`CerttaDelegate`**, e personalização de tema.

{% content-ref url="/pages/96e52fcd0a86b162e5d22cacfd0aa861d330667f" %}
[Guia de Instalação](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk.md)
{% endcontent-ref %}

{% content-ref url="/pages/9956ded2ebceb270a84bad1775a71b43fb57741a" %}
[Personalizando o Document Detector](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-2/customizing-document-detector.md)
{% endcontent-ref %}

***

### Mapeamento de eventos e resultados

**`CerttaDocumentDetectorDelegate`** é intencionalmente pequeno: **sucesso** e **erros bloqueadores** apenas.

| Callback                                  | Finalidade                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **`didFinish(result:)`**                  | Fim bem-sucedido do fluxo. **`resultado`** é o payload assinado / string JWT do CAF (trate como confidencial).                       |
| **`didFinishWith(_ error: CerttaError)`** | Sessão inválida, problemas de câmera/rede/segurança/inicialização e **falhas no processamento do pipeline unificado** (veja abaixo). |

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

**O que mudou para `CerttaDelegate`**

* **Cancelamento do usuário** → **`certtaDidCancel()`** em **`Certta.shared.delegate`** (não em **`CerttaDocumentDetectorDelegate`**).
* **Logs do pipeline** (níveis/mensagens) → **`certtaDidLog(level:message:)`** em **`CerttaDelegate`**.
* **`.loading` / `.loaded`** do pipeline unificado são **não** encaminhados para **`CerttaDocumentDetectorDelegate`** (use **`loadSession`** apenas para aquecimento).

**Falhas de processamento (`CafUnifiedEvent.failure`)**

* Não há **nenhum** separado **`didFail(_: CerttaDocumentDetectorFailure)`** em **`CerttaDocumentDetectorDelegate`**.
* As falhas são **registradas** pelo SDK e expostas em **`didFinishWith`** como **`CerttaError.unknownError(String)`**, onde a string inclui contexto de resultado/causa quando disponível.

**Migração de amostras antigas**

* Substitua **`didFinish(signedResponse:)`** por **`didFinish(result:)`** (mesma semântica de string).
* Implemente **`CerttaDelegate`** se você antes tratava cancelamento ou logs no delegate do Document Detector.

***

## Pré-requisitos

1. **SDK CAF** instalado — **guia de instalação** (Swift Package Manager ou CocoaPods).
2. **DocumentDetector** vinculado com **CafSDK**, conforme sua distribuição (SPM / CocoaPods / XCFramework).
3. **Info.plist** — uso da câmera (obrigatório):

```xml
<key>NSCameraUsageDescription</key>
<string>Precisamos da câmera para capturar seu documento.</string>
```

4. **Biblioteca de fotos** — adicione **`NSPhotoLibraryUsageDescription`** somente se seu produto permitir que os usuários escolham imagens da biblioteca.
5. **Sessão ativa do Certta** — chame **`Certta.shared.configure(configuration:)`** para que **token móvel** e **ID do usuário** estejam não vazios **antes** **`abrir`**. Sessão ou credenciais ausentes exibem **`CerttaError`** (normalmente **`initializationError`**) por meio de **`didFinishWith`**.

***

## Iniciar Document Detector

Use **`CerttaDocumentDetector.shared`**. Defina **`delegate`**, **ou** para que o **`UIViewController`** a **`CerttaDocumentDetectorDelegate`** apresentador — ordem de resolução: **`delegate ?? (presenter as? CerttaDocumentDetectorDelegate)`**.

#### Configuração mínima (inicializador no estilo legado)

Apenas **`fluxo`** é necessário para uma sessão real. Os outros parâmetros usam os padrões em **`init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:captureType:)`**. A captura é manual por padrão; para ativar a captura automática, veja [`DocumentDetectorCaptureType`](/caf-sdk/caf-sdk-pt-br/ios/getting-started-with-the-sdk-2/customizing-document-detector.md#documentdetectorcapturetype).

```swift
CerttaDocumentDetector.shared.open(
    from: self,
    configuration: CerttaDocumentDetectorConfiguration(
        flow: [
            CafDocumentDetectorStep(stepType: .rgFront),
            CafDocumentDetectorStep(stepType: .rgBack)
        ],
        maxRetryAttempts: 3
    )
)
```

Evite publicar **`CerttaDocumentDetectorConfiguration(flow: [])`** com um fluxo vazio.

### Recomendado: **`CerttaDocumentDetectorUIConfiguration`**

Use **`CerttaDocumentDetectorConfiguration.init(flow:ui:enableMultiLanguage:captureType:)`**. **`fluxo`** permanece em **`CerttaDocumentDetectorConfiguration`**. Copiar, estilo de captura (**`captureScreen`**), upload, timeouts, preview, popup, tentativas e **`[CafDDCustomization]`** vivem em **`CerttaDocumentDetectorUIConfiguration`**, alinhados com o **`DocumentDetectorUiConfiguration`**. Internamente, isso mapeia para **`CafDocumentDetectorLayout`**, relacionados à captura **`CafInstructionsConfiguration`**, e **`CafSelectDocumentConfig`**.

```swift
let ui = CerttaDocumentDetectorUIConfiguration()
ui.documentSelectionScreen.title = "Escolha o tipo de documento"
ui.instructionsScreen.title = "Escaneie seu documento"
ui.instructionsScreen.message = "Alinhe o cartão dentro da moldura"
ui.maxRetryAttempts = 3

CerttaDocumentDetector.shared.open(
    from: self,
    configuration: CerttaDocumentDetectorConfiguration(
        flow: [
            CafDocumentDetectorStep(stepType: .rgFront),
            CafDocumentDetectorStep(stepType: .rgBack)
        ],
        ui: ui
    )
)
```

* **`ui: CerttaDocumentDetectorUIConfiguration()`** — padrões do SDK para todos os campos de UI.
* **`layoutResourceName`** — opcional; reservado para futuros hooks de layout nativo, **não utilizado** pela UI padrão (intenção semelhante ao **`layoutId`**).

O inicializador legado **`init(flow:layout:uploadSettings:instructionsConfig:…)`** continua disponível se você montar **`CafDocumentDetectorLayout`**, **`CafInstructionsConfiguration`**, e **`CafSelectDocumentConfig`** você mesmo.

Você também pode integrar um bundle de UI existente com **`CerttaDocumentDetectorUIConfiguration.init(layout:instructions:documentTypeSelection:)`**.

### `loadSession`

Chame **`CerttaDocumentDetector.shared.loadSession(from:configuration:)`** antes **`abrir`** com o **mesmo** **`CerttaDocumentDetectorConfiguration`** para aquecer caches e recursos. **`.loading` / `.loaded`** são **não** entregues para **`CerttaDocumentDetectorDelegate`**.

***

#### `CerttaDocumentDetectorConfiguration` parâmetros

| Inicializador                                               | Quando                                                                            |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **`init(flow:ui:enableMultiLanguage:)`**                    | **Recomendado** — estruturado **`CerttaDocumentDetectorUIConfiguration`**.        |
| **`init(flow:layout:uploadSettings:instructionsConfig:…)`** | Raw **`Caf*`** tipos sem a struct de UI unificada.                                |
| **`init(from: CafDocumentDetectorConfig)`**                 | Você já tem uma **`CafDocumentDetectorConfig`** completa (por exemplo, migração). |

No **caminho de UI** , timeouts, upload, preview, popup, tentativas e personalizações vêm de **`CerttaDocumentDetectorUIConfiguration`**. No **caminho legado** , sobrescreva os padrões por campo no longo **`init`**.

| Campo                                   | Notas                                                                                                                                              |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`fluxo`**                             | **`[CafDocumentDetectorStep]`** — necessário para uma sessão real.                                                                                 |
| **`o layout`**                          | Somente legado. Caminho de UI: construído a partir de **`captureScreen`** → **`CafDocumentDetectorLayout`**.                                       |
| **`uploadSettings`**                    | Padrões legados vs caminho de UI (**`CerttaDocumentDetectorUIConfiguration.uploadSettings`**, upload padrão **desativado** / alinhado ao Android). |
| **`instructionsConfig`**                | Legado. Caminho de UI: de **`instructionsScreen`**.                                                                                                |
| **`requestTimeout`**                    | Legado: **`TimeInterval`**. Caminho de UI: **`Int`** segundos em **`CerttaDocumentDetectorUIConfiguration`**, padrão **60**.                       |
| **`showPreCapturePopup` / `showPopup`** | Caminho de UI: **`showPopup`**, padrão **verdadeiro**.                                                                                             |
| **`showPreview`**                       | padrão do caminho de UI **verdadeiro** (alinhado ao Android); padrão legado **falso** no init longo.                                               |
| **`ddCustomizations`**                  | Caminho de UI: **`customization.ddCustomizations`**.                                                                                               |
| **`enableMultiLanguage`**               | Padrão **verdadeiro**; pode ser definido em **`init(flow:ui:enableMultiLanguage:)`**.                                                              |
| **`selectDocumentConfig`**              | Caminho de UI: derivado de **`documentSelectionScreen`** quando títulos/subtítulos/mapas personalizados são definidos.                             |
| **`maxRetryAttempts`**                  | Caminho de UI: **`CerttaDocumentDetectorUIConfiguration.maxRetryAttempts`**, padrão **2**.                                                         |

#### Mapeamento do hub e padrões fixos

**`init(from:)`** e os inits de UI/legado ainda mapeiam para **`CafDocumentDetectorConfig`** por **fixos** valores para campos que o tipo Certta não expõe:

| Campo                                            | Comportamento do hub                                                                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **`proxySettings`**                              | **`nil`** (não definido via Certta)                                                                                                   |
| **`getUrlExpireTime`**                           | **`nil`**                                                                                                                             |
| **`currentStepDoneDelay`**                       | **1** (segundos)                                                                                                                      |
| **`allowedPassportCountryList`**                 | **`nil`**                                                                                                                             |
| **`manualCaptureEnabled` / `manualCaptureTime`** | Inits de UI/legado: **`verdadeiro`** / **`0`** (`.manual`) ou **`10`** (`.automatic`). **`init(from:)`** mantém os valores de origem. |

Para **full** controle (proxy, string de expiração, atraso entre etapas, lista de passaportes, ajuste de captura manual), use **`CafSDKProvider.Builder`** por **`CafDocumentDetectorConfig`** — veja o **a referência de configuração**.

### 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 eventos e resultados do Document Detector

***

### Eventos e resultados

#### `CerttaDocumentDetectorDelegate`

```swift
extension MyViewController: CerttaDocumentDetectorDelegate {

    func didFinish(result: String) {
        // Sucesso — payload assinado do Document Detector; valide no seu backend conforme a documentação do CAF.
    }

    func didFinishWith(_ error: CerttaError) {
        switch error {
        case .initializationError(let message): break
        case .permissionError(let message): break
        case .securityError(let message): break
        case .unknownError(let message): break   // inclui contexto do pipeline unificado .failure
        case .networkError(let message): break
        }
    }
}
```

**`CerttaError`** expõe **`mensagem`** e conforma-se a **`LocalizedError`** (**`errorDescription`**).

* **`didFinish(result:)`** — Não **não** registre o token completo em produção.
* **`didFinishWith`** — Sessão inválida, permissões, rede, segurança, inicialização e **falhas de processamento** (como **`unknownError`**).

#### `CerttaDelegate` (cancelamento e logs)

```swift
extension MyViewController: CerttaDelegate {

    func certtaDidCancel() {
        // Usuário fechou o fluxo — Document Detector, Face Liveness ou Smart Capture
    }

    func certtaDidLog(level: String, message: String) {
        // Diagnósticos opcionais
    }
}
```

Defina **`Certta.shared.delegate`** quando você precisar de linhas de cancelamento ou log. Os métodos do protocolo têm implementações vazias padrão.

***

### Permissões e UX

* Solicite **a câmera** o quanto antes, se possível; caso contrário, espere **`permissionError`** via **`didFinishWith`**.
* Use texto claro em **`instructionsScreen`** / seleção para que os usuários saibam como alinhar o documento.
* Em **cancelamento**, trate **`certtaDidCancel()`** com navegação previsível (voltar ou tentar novamente).

***

### Cores e tema

Passe **`CafColorConfiguration`** quando você chamar **`Certta.shared.configure(configuration:)`**, ou atualize a sessão ativa com **`Certta.shared.setColorConfiguration(_:)",`** (sem efeito se não houver sessão — chame **`configurar`** primeiro). O Document Detector consome a mesma paleta global que outros módulos Certta.

Para **claro vs escuro** paletas, resolva strings hex de **`UITraitCollection.current.userInterfaceStyle`** (ou o tema do seu app) antes de construir **`CafColorConfiguration`**.

Exemplo (uma única paleta amigável ao modo escuro usando os verdes padrão do SDK — ajuste para o seu app):

```swift
Certta.shared.setColorConfiguration(
    CafColorConfiguration(
        primaryColor: "#34D690",
        secondaryColor: "#012D1F",
        contentColor: "#CDCDCD",
        backgroundColor: "#000000",
        mediumColor: "#D1D1D1",
        dialogBackgroundColor: "#1C1C1E",
        dialogBorderColor: "#E5E5E7"
    )
)
```

***

### Legado **`CafSDKProvider`**

Se você fizer **não** uso do hub da Certta para Document Detector, integre com **`CafSDKProvider.Builder`** e um completo **`CafDocumentDetectorConfig`** para proxy, expiração de URL, atrasos, lista de passaportes e captura manual — veja **a referência de configuração**.

***

### Notas de versão

Veja **Changelog** / **GitHub Releases** para versões, mudanças incompatíveis e mínimo **Xcode** / **iOS**.

***

### Suporte

Use seu **CAF / Certta** canal de suporte, **FAQ**, e **repositório** para problemas e atualizações.


---

# 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/ios/getting-started-with-the-sdk-2.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.