> 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

{% 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** guia o usuário pela 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 depois abra o fluxo nativo com **`CerttaDocumentDetector`**.

Este guia aborda os pré-requisitos, **Certta** requisitos de 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 bloqueantes** apenas.

| Retorno de chamada                        | Finalidade                                                                                                                           |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **`didFinish(result:)`**                  | Conclusão bem-sucedida do fluxo. **`result`** é a string da carga útil assinada / JWT da CAF (trate como sensível).                  |
| **`didFinishWith(_ error: CerttaError)`** | Sessão inválida, problemas de câmera/rede/segurança/inicialização e **falhas de 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 foi movido 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 **registre** encaminhadas 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 apresentadas em **`didFinishWith`** como **`CerttaError.unknownError(String)`**, onde a string inclui o contexto do resultado/causa quando disponível.

**Migração de exemplos antigos**

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

***

## Pré-requisitos

1. **SDK da 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 o seu produto permitir que os usuários escolham imagens da biblioteca.
5. **Sessão Certta ativa** — chame **`Certta.shared.configure(configuration:)`** para que **token móvel** e **ID do usuário** não estejam vazios **antes de** **`abrir`**. Sessão ou credenciais ausentes geram **`CerttaError`** (normalmente **`initializationError`**) via **`didFinishWith`**.

***

## Iniciar o Detector de Documentos

Use **`CerttaDocumentDetector.shared`**. Defina **`delegate`**, **ou** faça o controlador de apresentação adotar o **`UIViewController`** para **`CerttaDocumentDetectorDelegate`** — 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 demais parâmetros usam os padrões em **`init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:)`**.

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

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

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

Use **`CerttaDocumentDetectorConfiguration.init(flow:ui:enableMultiLanguage:)`**. **`fluxo`** permanece em **`CerttaDocumentDetectorConfiguration`**. Texto, estilo de captura (**`captureScreen`**), upload, timeouts, preview, popup, tentativas e **`[CafDDCustomization]`** ficam em **`CerttaDocumentDetectorUIConfiguration`**, alinhado com o **`DocumentDetectorUiConfiguration`**. Internamente, eles mapeiam para **`CafDocumentDetectorLayout`**, relacionados à captura **`CafInstructionsConfiguration`**, e **`CafSelectDocumentConfig`**.

```swift
let ui = CerttaDocumentDetectorUIConfiguration()
ui.documentSelectionScreen.title = "Escolha o tipo de documento"
ui.instructionsScreen.title = "Digitalize 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 da UI.
* **`layoutResourceName`** — opcional; reservado para futuros hooks nativos de layout, **não utilizado** pela UI padrão (intenção semelhante ao Android **`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 pacote de UI existente com **`CerttaDocumentDetectorUIConfiguration.init(layout:instructions:documentTypeSelection:)`**.

### `loadSession`

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

***

#### `CerttaDocumentDetectorConfiguration` parâmetros

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

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

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

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

**`init(from:)`** e os inits da 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`** | **`true` / `0`** no mapeamento interno |

Para **controle total** (proxy, string de expiração, atraso da etapa, lista de passaportes, ajustes de captura manual), use **`CafSDKProvider.Builder`** por **`CafDocumentDetectorConfig`** — veja 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 os 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 da 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   // erro desconhecido; inclui contexto do pipeline unificado .failure
        case .networkError(let message): break
        }
    }
}
```

**`CerttaError`** expõe **`message`** e está em conformidade com **`LocalizedError`** (**`errorDescription`**).

* **`didFinish(result:)`** — Não **registre** 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() {
        // O usuário encerrou 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 cancelamento ou linhas de log. Os métodos do protocolo têm implementações vazias padrão.

***

### Permissões e UX

* Solicite **acesso à câmera** o quanto antes, quando possível; caso contrário, espere **`permissionError`** via **`didFinishWith`**.
* Use textos claros em **`instructionsScreen`** / seleção para que os usuários saibam como alinhar o documento.
* No **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(_:)`**\
&#x20;(sem efeito se não houver sessão — chame **`configure`** primeiro). O Document Detector consome a mesma paleta global que os 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 tema 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 **registre** usar o hub da Certta para o Document Detector, integre com **`CafSDKProvider.Builder`** e um conjunto completo **`CafDocumentDetectorConfig`** para proxy, expiração da URL, atrasos, lista de passaportes e captura manual — veja **referência de configuração**.

***

### Notas de versão

Veja **Registro de alterações** / **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 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/ios/getting-started-with-the-sdk-2.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.