SDK Captura de Documentos Web

SDK ClearSale Web

Os SDKs de Captura de Documentos permitem a realização de capturas pelo usuário dentro de suaaplicação. Essas capturas passam por validações que identificam o tipo de documento e que avaliam aqualidade da imagem capturada, instruindo o usuário através de feedbacks visuais.

Requisitos

Versão mínima por plataforma/navegador

Tipo de Dispositivo	Chrome	Edge	Firefox	Opera	Safari	Samsung Browser	Web View
Desktop	57	16	53	❌	11	❌	N/A
iOS*	11	❌	❌	❌	11		604
Android	57	❌	53	❌	❌	❌	57 (Chrome)

Para os navegadores no iOS, a versão se refere à versão do próprio iOS.

Instalação

Para começar a usar o SDK, você precisa instalá-lo em seu projeto. Supondo que você já tenha umprojeto Node.js, você pode instalar o SDK usando npm ou yarn:

npm install @clear.sale/docs-web-sdk

yarn add @clear.sale/docs-web-sdk

JavaScript Puro (Vanilla JS)

Se você não estiver usando um gerenciador de pacotes e preferir incluir o SDK diretamente em umprojeto de JavaScript puro, siga estas etapas:

Baixar o SDK
Primeiro, baixe o pacote do SDK em https://www.npmjs.com/package/@clear.sale/sdk-docs-web
Incluir o arquivo em seu projeto
Adicione o arquivo cs-docs-sdk.js ao seu projeto. Por exemplo, coloque-o em uma pasta chamada libs dentro do seu projeto
Incluir o SDK em seu HTML
Em seu arquivo HTML/JS, importe o SDK. Certifique-se de ajustar o caminho do arquivo conforme necessário:

<html>
<head>
 <script type="module">
 import { SDKClearSale, FLOW_TYPES, ENVIRONMENTS } from 'libs/cs-docs-sdk.js';
 ...
 </script>
</head>
<body></body>
</html>

Nesse exemplo, substitua 'libs/cs-docs-sdk.js' pelo caminho correto onde você salvou o arquivo csdocs-sdk.js .

Inicialização

Abaixo, apresentamos um exemplo completo de como inicializar o SDK. Em seguida, detalharemos cadaetapa.

import { SDKClearSale, FLOW_TYPES, ENVIRONMENTS } from '@clear.sale/docs-web-sdk';
// Função de login
const login = () => {
 // Implementar lógica de login aqui.
};
// Inicializar o SDK
const SDK = SDKClearSale({
 login, // Obrigatório. Função de login.
 transactionId: 'transaction-id', // Obrigatório. Transaction que deve criada previamente
 environment: { // Opcional. Valor padrão será ENVIRONMENTS.PRD
 env: ENVIRONMENTS.HML,
 },
 identity: { // Obrigatório. Identificadores de uso.
 identifierId: 'app-identifier', // Identificador
 cpf: 'user-cpf', // CPF do usuário
 },
 colors: { // Obrigatório. Cores usadas pelo SDK.
 primary: '#ff4800', // Cor primária
 secondary: '#ff4800', // Cor secundária
 tertiary: '#e6e6e6', // Cor terciária
 title: '#283785', // Cor do título
 paragraph: '#353840', // Cor do parágrafo
 background: '#FFFFFF', // Cor do background
 },
 flowTypes: [FLOW_TYPES.CAPTURE, FLOW_TYPES.UPLOAD], // Opcional. Ambos os tipos serão usados com
 onUploadedDocumentError, // Opcional, mas se presente deve ser uma função
});
// Configuração do SDK
SDK.init()
.then(result => {
 // Resultado do SDK contendo sessionId
 console.log(`Resultado do SDK: ${result}`);
})
.catch(error => {
 // Em caso de erro na captura
 console.log(`Erro do SDK: ${error}`);
});

Login

A função login deve ser implementada para gerenciar a autenticação. O login e será chamado nainicializacao do SDK e momentos antes do token expirar, renovando-o automaticamento.

O SDK espera que a função login retorne um objeto no seguinte formato:

{ 
  "accessToken": "", 
    "expiresIn": 300
}

Por questões de segurança, o token de autenticação da Clear Sale deve ser obtido através do servidor.Ou seja, a requisição de autenticação à Clear Sale deve ser feita a partir do servidor da aplicação.

Exemplo

const login = () => {
 // Realiza uma requisição de autenticação e retorna o token e o tempo de expiração,
 // que devem ser retornados pelo método de login.
 return fetch('https://<seu-servidor>/clear-sale-auth', {
 method: 'POST',
 headers: {
 'Content-Type': 'application/json',
 }
 })
 .then(response => response.json())
 .then(data => {
 return {
 accessToken: data.accessToken,
 expiresIn: data.expiresIn
 };
 });
};
// Instanciação do SDK
const SDK = SDKClearSale({
 login,
 ...
});

Endpoint da API de autenticação da Clear Sale

**URL**: https://<clear.sale.api.url>/authentication (obter URL com a Clear Sale)
Método: POST
Corpo da Requisição:

{
 	"Username": "seu-username", // Obter com a Clear Sale
 	"Password": "seu-password" // Obter com a Clear Sale
}

ID da Transação

O ID da transação é obrigatório e deve ser gerado previamente através da API da Clear Sale.

Identificação

Ao iniciar o SDK, devem ser informados um código identificador e o CPF do usuário.

IdentifierId : String de até 100 caracteres obrigatória que identifica todo o fluxo do usuário deforma única e é gerada pelo cliente. Serve para agilizar consultas e chamados de suporte (e pode ser utilizada como identificador interno entre produtos aqui da ClearSale).
Cpf : String de 11 caracteres (no formato CPF) obrigatória que identifica o usuário que irá realizar ofluxo, devendo seguir as regras de validade estipuladas pelo Governo.

Exemplo

// Instanciação do SDK
const SDK = SDKClearSale({
 identity: {
 identifierId: 'app-identifier',
 cpf: 'user-cpf',
 },
 ...
});

Fluxos

Ao iniciar o SDK, é possível informar quais fluxos serão habilitados através do parâmetro flowTypes . Ospossíveis valores são:

CAPTURE : Fluxo para captura de documentos utilizando uma câmera.
UPLOAD : Fluxo para upload de documentos.

Os fluxos estão expostos no objeto FLOW_TYPES , que pode ser importado do SDK e utilizado da seguinteforma:

import { FLOW_TYPES } from '@clear.sale/docs-web-sdk';
// Instanciação do SDK
const SDK = SDKClearSale({
 flowTypes: [FLOW_TYPES.CAPTURE, FLOW_TYPES.UPLOAD],
 ...
});

Cores

Ao iniciar o SDK, deve ser informado as cores atraves do parametro colors .

primary : Será aplicado como cor de fundo de botões de ação principais/ativos do SDK e outline debotões sem preenchimento
secondary : Será aplicado em ícones explicativos e carregamento, fundo de barras de feedback parausuário durante a tela de captura
tertiary : Será aplicado como cor de fundo de ícones informativos grandes
title : Será aplicado em textos que possuam o comportamento de título
paragraph : Será aplicado em textos que possuam comportamento de parágrafo e demais itens deapoio como o botão de fechamento do SDK
background : Será aplicado no background de todas as telas

Exemplo:

import { FLOW_TYPES } from '@clear.sale/docs-web-sdk';
const SDK = SDKClearSale({
 colors: {
 primary: '#ff4800',
 secondary: '#ff4800',
 tertiary: '#e6e6e6',
 title: '#283785',
 paragraph: '#353840',
 background: '#FFFFFF',
 },
 ...
});

Ambiente

Ao iniciar o SDK, você pode informar o ambiente desejado. Todas as requisições serão feitas para esteambiente, portanto, o método de login fornecido deve apontar para o mesmo.

HML: Ambiente de homologação. Todas as requisições do SDK serão feitas para o ambiente dehomologação.
PRD: Ambiente de produção. Todas as requisições do SDK serão feitas para o ambiente deprodução.

Exemplo

Os ambientes estão expostos no objeto ENVIRONMENTS , que pode ser importado do SDK e utilizado daseguinte forma:

import { ENVIRONMENTS } from '@clear.sale/docs-web-sdk';
// Instanciação do SDK
const SDK = SDKClearSale({
 environment: {
 env: ENVIRONMENTS.HML,
 },
 ...
});

onUploadedDocumentError

A função onUploadedDocumentError pode ser implementada para você lidar com erros/falhas no envio dedocumentos pelo fluxo de upload .

O SDK chama essa função, se presente, passando o base64 do pdf que originou o erro, o erro e uma função. Essa função permite a finalização do SDK .

let retries = 0;
const onUploadedDocumentError = (pdfBase64, error, closeSdk) => {
 if (retries >= 3) {
 closeSdk();
 }

 retries++;
};
// Instanciação do SDK
const SDK = SDKClearSale({
 onUploadedDocumentError,
 ...
});

Método preLoad

O método preLoad pode ser chamado a qualquer momento antes da inicialização do SDK. Ele realiza aautenticação e prepara os dados do SDK, incluindo o download antecipado do modelo de machine learning. Isso reduz o tempo de carregamento percebido pelo usuário durante a inicialização do SDK.

Idealmente, esse método deve ser chamado o mais cedo possível a partir do momento em que se prevê que o usuário passará pelo fluxo de captura ou upload do documento.

Uso do Método preLoad

// Instanciação do SDK
const SDK = SDKClearSale({ ... });
// Em algum momento da aplicação em que se possa prever o uso do SDK,
// chamar o método preLoad usando a instância criada anteriormente.
SDK.preLoad({
 onLoaded: auth => console.log(`Pré-carregamento concluído com sucesso. ${auth}`)
});

onLoaded: : Função de callback que é chamada quando o pré-carregamento é concluído comsucesso. Recebe um objeto auth contendo dados de autenticação.

Formato do objeto auth:

{
  accessToken: '',
  expiresIn: 300
}

Erros

O SDK possui 2 tipos distintos de erros: os fatais e os não fatais.
Erros fatais são erros que causam a finalização do SDK e então a execução da declaração catch dapromise do método init .
Erros não fatais são erros que o próprio SDK lida internamente, e ocasionam a navegação para a tela deerro do SDK .

Os erros emitios pelo SDK são:

Code	Fatal
AUTHENTICATION_ERROR	❌
AUTHORIZATION_ERROR	❌
INTERNAL_PARSING_ERROR	❌
INTERNAL_MONITORING_ERROR	❌
INTERNAL_VIDEO_STREAM_ERROR	❌
INTERNAL_LOGIN_ERROR	❌
SERVER_ERROR	❌
VALIDATION_LOGIN_METHOD_INVALID	✅
VALIDATION_TRANSACTION_ID_INVALID	✅
VALIDATION_CPF_INVALID	✅
VALIDATION_IDENTIFIER_ID_INVALID	✅
VALIDATION_FLOWS_INVALID	✅
VALIDATION_ON_UPLOADED_DOCUMENT_INVALID	✅
VALIDATION_BROWSER_NOT_SUPPORTED	✅
VALIDATION_FILE_INVALID	❌
VALIDATION_FILE_UNSUPPORTED	❌
VALIDATION_INTERNET_CONNECTION_OFFLINE	❌
UNKNOWN	✅

Observação: os erros VALIDATION_FILE_INVALID e VALIDATION_FILE_UNSUPPORTED não são fatais, porém aocorrência deles chama a função (caso presente) onUploadedDocumentError que é passada na instanciação do SDK.

Licença

Todos os direitos são reservados, sendo concedida a permissão para usar o software da maneira comoestá, não sendo permitido qualquer modificação ou cópia para qualquer fim. O Software é licenciado com suas atuais configurações “tal como está” e sem garantia de qualquer espécie, nem expressa e nem implícita, incluindo mas não se limitando, garantias de comercialização, adequação para fins particulares e não violação de direitos patenteados. Em nenhuma hipótese os titulares dos Direitos Autorais podem ser responsabilizados por danos, perdas, causas de ação, quer seja por contrato ou ato ilícito, ou outra ação tortuosa advinda do uso do Software ou outras ações relacionadas com este Software sem prévia autorização escrita do detentor dos direitos autorais.