Teste do Fluxo Completo

A funcionalidade de Teste do Fluxo Completo pode ser utilizada por meio do SDK do Santo iD, atualmente disponível para JavaScript/Node.js.

Instalação

Para instalar o SDK utilizando o NPM, utilize o seguinte comando:

npm install santoid-sdk

Para instalar utilizando o Yarn, utilize este outro comando:

yarn add santoid-sdk

Autenticação do SDK

Atualmente, o SDK suporta a autenticação via contas de serviço do Santo iD. Para realizar a autenticação, crie uma conta de serviço do Santo iD na página de Contas de Serviço da plataforma.

Com a conta criada, armazene as credenciais obtidas em um arquivo no seu projeto com o nome que desejar. Após isso, será necessário passar as credenciais para o SDK com a função de inicialização.

É recomendado que a inicialização do SDK seja realizada no back-end do seu projeto, pois, ao colocar o arquivo de credenciais em um front-end, há um risco de as credenciais serem expostas aos usuários.

No seu projeto, você pode colocar o arquivo de credenciais em um determinado local e expor uma variável de ambiente SANTOID_SDK_CREDENTIALS informando o local do arquivo.

Dessa forma, após certificar-se de que o usuário tem autorização de acordo com as regras de negócio de sua aplicação, inicialize o SDK da forma abaixo:

import { initialize } from 'santoid-sdk/node/auth'

async function startSDK() {
  const token = await initialize()
  // ...
}

// Certifique-se de que o usuário está autenticado antes
startSDK()

Você também pode passar as credenciais em formato de objeto ou transformadas em base64 por meio da propriedade credentials do objeto de opções de inicialização.

import { initialize } from 'santoid-sdk/node/auth'

async function startSDK () {
  const token = await initialize({
    credentials: '...', // Conta de serviço em base64 ou o objeto da conta de serviço
  })

  // ...
}

// Certifique-se de que o usuário está autenticado antes
startSDK()

Descrição da funcionalidade

Com a funcionalidade do teste do fluxo completo do Santo iD, é possível iniciar a análise de prova de vida juntamente com a análise de um documento de identificação enviado, realizando também a comparação da face encontrada na prova de vida com a do documento ao final do processo.

Ao chamar a função uploadIdentificationDocument, ela retorna um determinado conjunto de métodos, os quais possibilitam as análises.

Com o método retornado startAll é possível iniciar todas as análises simultaneamente, porém também é possível iniciar uma de cada vez com os métodos startDocumentUpload, startLivenessDetection e startFaceComparison.

Entretanto, o método startFaceComparison será chamado automaticamente quando as outras análises forem concluídas, sendo mais útil apenas para reiniciar a comparação em caso de erro. Caso o método seja acionado quando as faces ainda não estiverem disponíveis para análise, a função onError será chamada com uma instância de erro como parâmetro, caso tenha sido fornecida.

Exemplos

JavaScript

As propriedades disponíveis para utilização no objeto de opções estão listadas na tabela abaixo:

Opções para a função uploadIdentificationDocument (JavaScript)

Nome da propriedade	Função	É obrigatório?
token	Token de acesso obtido por meio da autenticação.	Sim
track	Identificador do processo que será utilizado.	Sim
livenessDetectionOptions	Opções para a verificação de prova de vida.	Não
onUpdate	Função executada toda vez que ocorre uma atualização no status geral.	Não
onError	Função executada quando ocorre erro em alguma das operações.	Não
onSuccess	Função executada quando as verificações são finalizadas com sucesso.	Não
onEnd	Função executada quando a verificação é finalizada, com ou sem erro.	Não

import { uploadIdentificationDocument } from 'santoid-sdk/liveness'

const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
  token: 'string',
  track: 'string',

  onUpdate(results) {
    // ...
  },

  onError(error) {
    // ...
  },

  onSuccess(results) {
    // ...
  },

  onEnd() {
    // ...
  },

  livenessDetectionOptions: {
    getNextFrame() {
      // ...
    },

    onSuccess() {
      // ...
    },

    // ...
  },
})

const {
  startAll,
  startDocumentUpload,
  startLivenessDetection,
  startFaceComparison,
  getResults
} = uploadIdentificationDocumentResponse

Retorno da função uploadIdentificationDocument (JavaScript)

A função retorna alguns métodos que podem ser utilizados para controlar as análises:

Nome da propriedade	Função
startAll	Inicia todas as análises simultaneamente.
startDocumentUpload	Inicia a etapa de upload/análise do documento.
startLivenessDetection	Inicia a verificação de prova de vida.
startFaceComparison	Inicia a comparação entre a face do documento e da prova de vida.
getResults	Retorna os status atuais de cada análise.

Formato dos resultados

interface IUploadIdentificationDocumentResults {
  uploadedDocument: Blob | File | null
  typification: {
    status: TResultStatuses
    results: ITypificationResult | null
    loading: boolean
    error: SDKError | null
  }
  liveness: {
    status: TResultStatuses
    results: ILivenessResults<Blob | File | null | undefined> | null
    loading: boolean
    error: SDKError | null
  }
  faceMatch: {
    status: TResultStatuses
    results: IFaceMatchResult | null
    loading: boolean
    error: SDKError | null
  }
}

type TResultStatuses = 'success' | 'error' | null

interface ITypificationResult {
  n_documents: number
  predictOCR: Array<{
    typification: {
      document_type: string
      ocr_success: boolean
      typification_score: number
    }
    ocr_error?: boolean | null
    ocr_message?: {
      template: string
      labels: any
    } | null
    ocr_extraction: {
      template: string
      labels: Array<{
        x: number
        y: number
        w: number
        h: number
        bottomRight: number[]
        topLeft: number[]
        dataField?: string
        dataFieldValue?: boolean
        ocr?: string | null
        ocr_score?: number
        cropBase64?: string | null
        serpro_query?: {
          serpro_data: any
          search_logs: {
            document: string
            type: string
            search_time: string
            status_code: number
            message: string
          }
        }
        validation?: Record<string, number | boolean>
      }> | null
    } | boolean
  }>
}

export type TPositions = 'front' | 'right' | 'left' | 'up' | 'bottom'

interface ILivenessResults {
  livenessId: string
  successFrames: Record<TPositions, Blob>
}

interface IFaceMatchResult {
  comparison_score: number
  similarity_score: number
  match: boolean
}

Node.js

No Node.js o caminho da importação muda e a função getNextFrame é obrigatória.

import { uploadIdentificationDocument } from 'santoid-sdk/node/liveness'

const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
  token: 'string',
  track: 'string',

  livenessDetectionOptions: {
    getNextFrame() {
      // ...
    },
    // ...
  },
  // ...
})

CDN

Disponível globalmente por meio da classe SantoiDSDK.

<body>
  <button onclick="startUploadIdentificationDocument()">Iniciar</button>

  <script src="https://cdn.jsdelivr.net/npm/santoid-sdk@VERSION/browser/liveness/index.js"></script>

  <script>
    function startUploadIdentificationDocument () {
      const { startAll } = SantoiDSDK.uploadIdentificationDocument({
        // ...
      })
    }
  </script>
</body>