santoid-sdk v3.1.0

SantoiD SDK

Com esta biblioteca, você pode conectar-se ao Santo iD via código JavaScript de forma fácil e rápida, podendo integrá-lo à sua aplicação de forma mais eficiente.

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

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()

Funcionalidades disponíveis

Prova de Vida

Atualmente, o SDK conta com a funcionalidade de Prova de Vida, que possibilita a verificação do usuário atual, avaliando se uma pessoa real está realizando as atividades online por meio de uma rápida análise facial.

Utilização em JavaScript

Para utilizar a funcionalidade de Prova de Vida, é necessário importar a função para iniciar a verificação e passar alguns valores dentro do objeto de opções, como no exemplo abaixo:

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

const livenessDetectionResponse = livenessDetection({
  token: 'string',
  track: 'string',
  customId: 'string',

  getNextFrame: () => {
    // ...
  },

  // ...
})

const { getVideoStream, stopLivenessDetection, resumeGettingFrames, pauseGettingFrames } = livenessDetectionResponse

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

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

Retorno da função livenessDetection (JavaScript)

A função livenessDetection retorna alguns métodos que possibilitam um melhor controle da verificação.

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

const livenessDetectionResponse = livenessDetection({
  token: 'string',
  track: 'string',

  onStart ({ videoStream }) {
    const video = document.querySelector('video')
    video.srcObject = videoStream    
  },

  onNextStep () {
    pauseGettingFrames()

    // Simulando intervalo de sucesso
    setTimeout(() => {
      resumeGettingFrames()
    }, 1000)
  },

  // ...
})

// Funções retornadas
const { getVideoStream, stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse

Utilização em Node.js

Caso deseje executar a função da prova de vida no servidor (Node.js), é obrigatório informar ao SDK a função de obtenção de frames (getNextFrame), a qual deve retornar um valor no formato string, ArrayBuffer, Buffer ou Buffer[] contendo os dados da imagem do frame.

Fique atento ao caminho de importação da função, que muda para o caso de execução no servidor (Node.js):

Opções para a função livenessDetection (Node.js)

Para Node.js, as opções são quase as mesmas que as utilizadas em JavaScript, mudando apenas a obrigatoriedade de alguns valores. Abaixo estão listadas as propriedades que mudaram. As outras permanecem iguais às apresentadas anteriormente.

Retorno da função livenessDetection (Node.js)

Os itens retornados pela função livenessDetection para Node.js são semelhantes àos retornados pela função para JavaScript, com exceção da função getVideoStream, que não é retornada.

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

function getNextFrame (): string | ArrayBuffer | Buffer | Buffer[] {
  // ...
}

const livenessDetectionResponse = livenessDetection({
  token: 'string',
  track: 'string',
  
  getNextFrame,

  // ...
})

// Funções retornadas
const { stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse

Utilização via CDN

Caso deseje utilizar a biblioteca via CDN, importando-a diretamente em uma tag script, basta utilizar o caminho especificado no exemplo abaixo.

Ao importar a biblioteca via tag script, a função livenessDetection ficará disponível por meio da classe SantoiDSDK.

Substitua o VERSION pela versão desejada.

Nesse modo de utilização, as opções disponíveis para configuração são as mesmas da versão JavaScript.

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

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

  <script>
    function startLiveness () {
      SantoiDSDK.livenessDetection({
        track: 'string',
        token: 'string',

        // ...
      })
    }
  </script>
</body>

Teste do Fluxo Completo

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 para a comparação entre as faces detectadas 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.

Utilização em 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)

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 uploadIdentificationDocument retorna alguns métodos que podem ser utilizados para dar controlar as análises.

Formato dos resultados da função uploadIdentificationDocument

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
  }
}

Em que:

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
}

Utilização em Node.js

De forma semelhante à funcionalidade da Prova de Vida, para o Node.js o caminho da importação muda e a função getNextFrame passa a ser obrigatória e deve ser fornecida às opções para o livenessDetection.

Outro detalhe é que no Node.js todos os tipos envolvendo File ou Blob passam a utilizar valores do tipo string, ArrayBuffer, Buffer ou Buffer[].

Todos as outras opções e retornos se mantém os mesmos da versão para JavaScript.

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

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

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

    // ...
  },

  // ...
})

Utilização via CDN

De forma semelhante à funcionalidade da Prova de Vida, a funcionalidade do teste do fluxo completo também é disponibilizada globalmente por meio da classe SantoiDSDK.

Substitua o VERSION pela versão desejada.

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

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

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