Pular para o conteúdo principal

Captura de documentos

Este guia foi elaborado para ajudá-lo a implementar o SDK Web de forma rápida e fácil. São disponibilizados conceitos básicos, exemplos de implementação dos SDKs e também de como interagir com as APIs REST dos motores.

Através deste guia, é possivel:

  • Implementar a abertura da câmera e a captura de imagens;
  • Manipular os dados de retorno;
  • Utilizar o retorno do SDK com as APIs do motor.

Antes de começar, certifique-se que seguiu o passo-a-passo para instalação e importação do SDK neste guia.

RECURSOS DISPONÍVEIS​

O SDK Web oferece um componente para captura de documento contendo um frame de captura que auxilia o usuário a posicionar o documento de forma correta para a foto. Após posicionar corretamente, o usuário deve clicar em um botão para capturar a foto do documento.

A captura dos seguintes tipos de documentos está disponível:

  • CNH: Captura da CNH aberta;
  • CNH frente: Captura da frente da CNH;
  • CNH verso: Captura do verso da CNH;
  • CPF: Captura do documento de CPF;
  • RG frente: Captura da frente do RG;
  • RG verso: Captura do verso do RG;
  • Novo RG frente: Captura a frente do novo tipo de RG;
  • Novo RG verso: Captura o verso do novo tipo de RG;
  • Outros: Captura documento genérico. Para este tipo de captura você deve informar o título do documento que será mostrado na captura para o usuário usando a propriedade optional.LABEL_DOCUMENT_TYPE_OTHERS.
Atenção

Os frames Novo RG frente e Novo RG verso não funcionam com Tipificação e OCR

Captura Manual

IMPLEMENTAÇÃO​

Seguindo este passo-a-passo, você tem todo o potencial do SDK embarcado em sua aplicação Web.

  1. INICIALIZAR O SDK​

    Como primeiro passo, você deve efetuar 3 passos simples em seu projeto:

    Instancie um novo Builder:

    const unicoCameraBuilder = new UnicoCheckBuilder();

    Especifique o caminho dos arquivos adicionais (caso adicionados em seu projeto):

    unicoCameraBuilder.setResourceDirectory("/resources");

  2. CONFIGURAR TAMANHO DO FRAME​

    Como primeiro passo, é recomendado que você configure o tamanho do frame dentro de sua aplicação, a fim de otimizar a área de captura dentro de seu WebApp. Confira abaixo como fazer esta configuração para Web Desktop ou Mobile.

    Dica

    Muitas vezes o funcionamento do frame pode ser afetado por alguns design-systems que possuam algum tipo de grid-system como, por exemplo, bootstrap ou material-ui. Para minimizar este risco, certifique-se de posicionar o frame (id="box-camera") em algum lugar do código que não herde regras indesejadas de css.

    Nas versões Web Desktop, é possível restringir o tamanho do frame para que o mesmo não utilize toda a dimensão de seu WebApp. Para isto, basta envolver o frame (id="box-camera") em outra tag html, como no exemplo abaixo:

    <div class="container">
      <div id="box-camera"></div>
    </div>

    Idealmente, você deve tentar manter uma proporção adequada entre altura e largura, o que irá facilitar o enquadramento da face do usuário. A seguir um exemplo:

    .container {
      width: 800px;
      height: 600px;
      position: relative;
    }

    Seguindo o exemplo acima, o frame respeita o tamanho do elemento "pai", neste caso representado pelo container. Desta forma, você tem a flexibilidade para implementar o frame da forma mais conveniente para sua aplicação (como em um modal, por exemplo).

    Testando diversos tamanhos de tela

    Testes alterando o tamanho da tela através do modo desenvolvedor de seu browser não funcionam. É recomendado que este tipo de teste seja feito alterando o tamanho da janela de seu browser.

  3. CONFIGURAR FUNÇÕES DE CALLBACK​

    Um dos objetos que é necessário passar como parâmetro ao método responsável por renderizar o frame de captura é o de callback. Este objeto deve conter funções de callback para casos de sucesso e erro, como exemplificados abaixo.

      const callback = {
        on: {
          success: (obj) => {
            console.log(obj.base64);
            console.log(obj.encrypted);
          },
          error: (error) => {
            console.error(error)
            //confira na aba "Referências" sobre os erros possíveis
          },
        }
      };

    Este objeto é obrigatório e caso não seja corretamente implementado (contemplando todos os eventos de success ou error gera uma exceção, que caso não tratada, é exibida no console do usuário).

    Alerta

    O atributo Encrypted é destinado estritamente ao envio da imagem através das APIs da Unico. Não se deve abrir e serializar esse atributo, pois suas características podem ser alteradas sem aviso prévio. Seu uso deve ser exclusivo nas interações com as APIs para garantir a integridade e segurança dos dados. A Unico não se responsabiliza por quaisquer danos decorrentes dessa prática, uma vez que as modificações podem ocorrer de maneira imprevista.

    Para mais detalhes sobre os códigos de erro retornados pelo SDK, consulte este guia.

  4. CONFIGURAR LAYOUT DO FRAME​

    Esta é uma etapa opcional, porém muito recomendada.

    Para efetuar a customização do frame de captura por meio do Theme Builder basta gerar uma instância da classe UnicoThemeBuilder e invocar os métodos que customizam cada uma das propriedades do frame de captura, como exemplificados a seguir:

    const unicoTheme = new UnicoThemeBuilder()
    .setColorSilhouetteSuccess("#0384fc")
    .setColorSilhouetteError("#D50000")
    .setColorSilhouetteNeutral("#fcfcfc")
    .setBackgroundColor("#dff1f5")
    .setColorText("#0384fc")
    .setBackgroundColorComponents("#0384fc")
    .setColorTextComponents("#dff1f5")
    .setBackgroundColorButtons("#0384fc")
    .setColorTextButtons("#dff1f5")
    .setBackgroundColorBoxMessage("#fff")
    .setColorTextBoxMessage("#000")
    .setHtmlPopupLoading(`<div style="position: absolute; top: 45%; right: 50%; transform:
    translate(50%, -50%); z-index: 10; text-align: center;">Carregando...</div>`)
    .build();

    Após a geração do objeto de tema, conforme exemplificado acima, ele deve ser passado como parâmetro para o método setTheme do builder unicoCameraBuilder

    unicoCameraBuilder.setTheme(unicoTheme);

  5. CONFIGURAR MODO DE CAPTURA E INICIAR CÂMERA​

    Para iniciar a câmera com as configurações feitas até aqui, é preciso criar uma instância do builder através do método build().

    const unicoCamera = unicoCameraBuilder.build();

    A preparação da câmera é efetuada a partir do método prepareDocumentCamera(), disponibilizado a partir do builder. Este método recebe 2 parâmetros:

    • O arquivo JSON com suas credenciais (gerado através deste guia);
    • Tipo de documento a ser capturado, sendo eles:
      • DocumentCameraTypes.CNH: Frame para captura de CNH.
      • DocumentCameraTypes.CNH_FRENTE: Frame para captura da frente da CNH.
      • DocumentCameraTypes.CNH_VERSO: Frame para captura do verso da CNH.
      • DocumentCameraTypes.CPF: Frame para captura CPF.
      • DocumentCameraTypes.OTHERS("descrição"): Frame somente com o retângulo onde pode ser usado para outros tipos de documentos. Neste tipo, há um parâmetro com a descrição do documento. (Ex. contrato)
      • DocumentCameraTypes.RG_FRENTE: Frame para captura da frente do RG.
      • DocumentCameraTypes.RG_VERSO: Frame para captura da parte traseira do RG.
      • DocumentCameraTypes.RG_FRENTE_NOVO: Frame para captura da frente do novo RG.
      • DocumentCameraTypes.RG_VERSO_NOVO: Frame para captura da parte traseira do novo RG.

    Este método gera uma promise que ao ser resolvida, devolve um objeto que é utilizado para efetivamente abrir a câmera através do método open, que recebe como parâmetro as funções de callback configuradas neste passo.

    Vale lembrar

    Para otimizar a abertura da câmera é possível separar as chamadas dos métodos prepareSelfieCamera() e open(). Veja um exemplo nesta POC feita em React com TypeScript.

    Abaixo um exemplo utilizando a captura de CNH:

    Usando a classe UnicoConfig:

      const config = new UnicoConfig()
        .setProjectNumber("<YOUR_PROJECT_NUMBER>")
        .setProjectId("<YOUR_PROJECT_ID>")
        .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
        .setHostname("<YOUR_HOSTNAME>")
        .setHostInfo("<YOUR_HOST_INFO>")
        .setHostKey("<YOUR_HOST_KEY>");

      unicoCamera.prepareDocumentCamera(
        config, 
        DocumentCameraTypes.CNH
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // confira na aba "Referências" sobre os erros possíveis
      });

    Usando o arquivo json:

      unicoCamera.prepareDocumentCamera(
        "/services.json", 
        DocumentCameraTypes.CNH
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // confira na aba "Referências" sobre os erros possíveis
      });

  6. CHAMAR AS APIS​

    A captura das imagens é apenas a primeira parte da jornada. Após capturar a imagem, é necessário enviar o Encrypted gerado para as APIs, selecionando um dos fluxos disponíveis detalhados em Fluxos.

    Atenção

    Por motivos de segurança, o intervalo entre a geração do Encrypted e o envio via um dos fluxos disponíveis deve ser de até no máximo 10 minutos. Envios feitos além deste período serão rejeitados automaticamente pela API.

Dúvidas?​

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.