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.

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.

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.

Guia de Instalação

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.

CerttaDocumentDetectorConfiguration e CerttaDocumentDetector são o módulo sem interface do Document Detector. A fluxo lista é obrigatória.

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.

Ativar documentDetectorUI em caf-modules-config.json. A camada nativa mapeia fluxo para a tela de seleção de documento.

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

Personalizações da UI

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

O suporte completo a HEIC está disponível apenas no iOS.

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.

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.

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 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 se manifestam como erros da classe 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 aplicativo para segundo plano.