Métodos do SDK

Esta seção fornece documentação detalhada para cada método do SDK. Role para baixo para saber mais sobre como usar cada método, incluindo seus parâmetros, exemplos de uso e observações importantes.

• initialize
• capture
• close
• dispose
• isSupported
• getIsInitialized
• loadAiModel

initialize

O initialize o método é usado para inicializar o SDK. Este método configura variáveis internas e baixa os recursos necessários para o SDK funcionar.

Importante

• O processo de inicialização pode levar alguns segundos. Recomenda-se chamar esta função o mais cedo possível no seu fluxo para garantir uma experiência de usuário fluida.

Tratando erros de inicialização

Erros que podem ocorrer durante a initialize() método:

Nome do erro	Descrição
CafSdkInitError	Ocorreu um erro durante a inicialização do SDK.
CafSdkUnauthorizedError	Acesso não autorizado ao SDK. Verifique se o token fornecido é válido e não expirou.

Exemplo

try {
  await sdk.initialize();
  console.log("SDK inicializado com sucesso!");
} catch (error) {
  switch (error.name) {
    case "CafSdkInitError":
      console.error("Erro de inicialização do SDK:", error.message);
      break;
    case "CafSdkUnauthorizedError":
      console.error("Erro de acesso não autorizado:", error.message);
      break;
    default:
      console.error("Erro inesperado de inicialização:", error.name, error.message);
  }
}

Voltar ao topo

capture

O capture o método é usado para carregar o SDK na tela e realizar a captura do documento. Ele inicializa o fluxo de vídeo (solicitando permissões, se necessário) e o carrega no contêiner.

Para mais informações sobre os parâmetros de entrada e os resultados de saída, consulte as listas abaixo:

Entrada

O capture método recebe um parâmetro:

const captureResult = await documentDetector.capture(options);

Este parâmetro é um objeto que contém as opções de captura. A tabela a seguir lista as opções de captura disponíveis:

Parâmetro	Tipo	Obrigatório?	Valor padrão
expectedDocument Tipo e lado do documento que se espera que o SDK detecte. Se o valor for "any" então qualquer tipo de documento será aceito.	"rg_front" | "rg_back" | "rg_full" | "cnh_front" | "cnh_back" | "cnh_full" | "crlv" | "rne_front" | "rne_back" | "passport" | "ctps_front" | "ctps_back" | "any"	Sim.	-
mode O modo de captura. Pode ser "automatic", "manual" ou "upload". Se a opção enableFramingAnalyzer foi definida manualmente como false, o modo de captura será forçado para manual independentemente do valor passado neste parâmetro.	"automatic" | "manual" | "upload"	Sim.	-
automaticCaptureMaxDuration A duração máxima em segundos para a captura automática. Se a duração for excedida, a captura manual será acionada.	number	Não.	60
uploadFileType O tipo de arquivo a ser enviado. O valor pode ser "IMAGE", "PDF" ou undefined. Se o valor for undefined, tanto imagens quanto arquivos PDF poderão ser enviados.	"IMAGE" | "PDF" | undefined	Não.	Ambos "IMAGE" e "PDF".
personID O ID da pessoa (usado para fins de rastreamento).	string	Não.	undefined
forceEndWhenInvalid Determina se a captura deve ser encerrada à força quando for inválida.	boolean	Não.	false

Saída

O capture() método retorna um string JWT assinada (signedResponse) do backend. Esse JWT codifica todos os metadados da captura e pode ser verificado no lado do servidor. Para acessar os detalhes da captura no lado do cliente, decodifique o payload do JWT.

const signedResponse = await documentDetector.capture(options);

Campos do payload do JWT

O payload do JWT decodificado contém os seguintes campos:

Campo	Tipo	Descrição
captures	Array<object>	Lista dos lados do documento capturados. Contém uma entrada para capturas de lado único ou de documento completo.
captures[0].scannedLabel	string	O rótulo do modelo de documento detectado, combinando tipo e lado. Valores possíveis: "rg_front", "rg_back", "rg_full", "rg_new_front", "rg_new_back", "rg_new_full", "cnh_front", "cnh_back", "cnh_full", "new_cnh_front", "new_cnh_back", "new_cnh_full", "crlv", "new_crlv", "rne_front", "rne_back", "rnm_front", "rnm_back", "passport_full", "ctps_front", "ctps_back", "cin_front", "cin_back", "cin_full", "generic".
captures[0].imageUrl	string	URL pré-assinada para a imagem capturada armazenada no S3. Essa URL é temporária e expira após algumas horas.
documentType	string	O tipo de documento detectado em letras maiúsculas. Valores possíveis: "CNH", "NEW_CNH", "RG", "RG_NOVO", "CRLV", "NEW_CRLV", "RNE", "RNM", "PASSPORT", "CTPS", "CIN", "OUTROS".
trackingId	string	O identificador de rastreamento da sessão de captura. Pode estar vazio, se não se aplicar.
iat	number	Carimbo de data e hora "issued at" do JWT (época Unix em segundos). Indica quando o token foi gerado.

Exemplo de payload do JWT

(por exemplo, frente da CNH):

{
  "captures": [
    {
      "scannedLabel": "new_cnh_front",
      "imageUrl": "https://example-url/image.jpg?signature..."
    }
  ],
  "documentType": "NEW_CNH",
  "trackingId": "",
  "iat": 1781646936
}

O signedResponse O JWT deve ser enviado ao seu backend para validação no lado do servidor. A decodificação no lado do cliente é destinada apenas para fins de exibição ou registro — não dependa disso para decisões de segurança.

Tratando erros de captura

Nome do erro	Descrição
CafSdkCaptureError	Ocorreu um erro durante o processo de captura.
CafSdkCanceledError	Execução do SDK cancelada pelo usuário.
CafInvalidOptionsError	As opções de captura do SDK são inválidas. Revise as opções fornecidas ao SDK.
CafSdkBlockedError	A captura do SDK foi bloqueada.
CafUnsupportedError	A captura do SDK não é compatível com o tipo de documento específico.
CafCameraPermissionError	Erro ao obter permissão da câmera.
CafCameraPermissionDeniedError	Permissão da câmera negada pelo usuário.
CafCameraUnsupportedError	A câmera não é compatível com o navegador/dispositivo.

Exemplo

try {
  // Carrega o SDK na tela e realiza a captura do documento.
  // Retorna uma string JWT contendo a resposta assinada com os metadados da captura.
  const signedResponse = await documentDetector.capture({
    expectedDocument: "cnh_front",
    mode: "automatic",
    automaticCaptureMaxDuration: 30,
    personID: "my-person-id",
  });
  
  // Decodifica o JWT para extrair os detalhes da captura
  const result = decodeJwt(signedResponse);

} catch (error) {
  switch (error.name) {
    case "CafSdkCaptureError":
      console.error("Erro de captura do SDK:", error.message);
      break;
    case "CafSdkCanceledError":
      console.error("Captura cancelada pelo usuário:", error.message);
      break;
    case "CafInvalidOptionsError":
      console.error("Erro de opções:", error.message);
      break;
    case "CafSdkBlockedError":
      console.error("Erro de bloqueio do SDK:", error.message);
      break;
    case "CafUnsupportedError":
      console.error("Erro de incompatibilidade:", error.message);
      break;
    case "CafCameraPermissionError":
      console.error("Erro geral de permissão da câmera:", error.message);
      break;
    case "CafCameraPermissionDeniedError":
      console.error("Erro de permissão da câmera negada:", error.message);
      break;
    case "CafCameraUnsupportedError":
      console.error("Erro de câmera não compatível:", error.message);
      break;
    default:
      console.error("Erro inesperado de captura:", error.name, error.message);
  }
}

Voltar ao topo

close

O close o método é usado para remover o SDK da tela, removendo seus elementos visuais do DOM.

Tratando erros de fechamento

Nome do erro	Descrição
CafSdkCloseError	Ocorreu um erro ao fechar o SDK.

Exemplo

try {
  await sdk.close();
} catch (error) {
  switch (error.name) {
    case "CafSdkCloseError":
      console.error("Erro ao fechar o SDK:", error.message);
      break;
    default:
      console.error("Erro inesperado ao fechar:", error.name, error.message);
  }
}

Voltar ao topo

dispose

O dispose o método é usado para desinicializar o SDK. Ele interrompe o fluxo de vídeo e limpa as variáveis internas do SDK.

Tratando erros de desinstalação

Nome do erro	Descrição
CafSdkDisposeError	Ocorreu um erro ao descartar o SDK.

Exemplo

try {
  await sdk.dispose();
} catch (error) {
  switch (error.name) {
    case "CafSdkDisposeError":
      console.error("Erro ao descartar o SDK:", error.message);
      break;
    default:
      console.error("Erro inesperado ao descartar:", error.name, error.message);
  }
}

Voltar ao topo

isSupported

O isSupported o método verifica se o navegador é compatível com o SDK.

Exemplo

const isSupported: boolean = sdk.isSupported();

Voltar ao topo

getIsInitialized

O getIsInitialized o método verifica se o SDK está inicializado.

Exemplo

const isInitialized: boolean = sdk.getIsInitialized();

Voltar ao topo

loadAiModel

Se a opção enableFramingAnalyzer foi definida manualmente como false, este método não terá efeito quando for chamado.

O loadAiModel método é opcional, mas pode melhorar significativamente o desempenho de carregamento do SDK. Para obter os melhores resultados, recomendamos invocá-lo o mais cedo possível no seu fluxo de trabalho, idealmente antes de chegar à tela de carregamento do SDK. No entanto, se isso não for viável ou não estiver alinhado com os requisitos específicos da sua integração, o initialize método lidará automaticamente com todas as tarefas de inicialização necessárias para garantir que o SDK opere corretamente.

Tratando erros de carregamento do modelo de IA

Nome do erro	Descrição
CafLoadAIModelError	Ocorreu um erro ao carregar o modelo de IA.

Exemplo

try {
  await documentDetector.loadAiModel();
} catch (error) {
  switch (error.name) {
    case "CafLoadAIModelError":
      console.error("Erro ao carregar o modelo de IA do SDK:", error.message);
      break;
    default:
      console.error("Erro inesperado ao carregar o modelo de IA:", error.name, error.message);
  }
}

Voltar ao topo