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)

| 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 | | customId | Identificador customizado para auditoria. | Não | | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não | | startGettingFrames | Função executada quando a obtenção de frames for iniciada. Se retornar um valor do tipo MediaStream, ele será salvo e fornecido por meio da função getVideoStream. | Não | | getNextFrame | Função que deve retornar os frames no formato File ou Blob. Será executada várias vezes e deve sempre devolver o próximo frame. | Não | | stopGettingFrames | Função executada quando a obtenção de frames for finalizada. | Não | | onStart | Função executada quando a verificação for iniciada. Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (videoStream), caso disponível. | Não | | onNextStep | Função executada sempre que a validação muda para a próxima etapa. Disponibiliza pelos parâmetros a etapa atual ('front', 'left', 'right', 'up' ou 'bottom'). | Não | | onFrontStep | Função executada quando a etapa 'front' é iniciada. | Não | | onLeftStep | Função executada quando a etapa 'left' é iniciada. | Não | | onRightStep | Função executada quando a etapa 'right' é iniciada. | Não | | onUpStep | Função executada quando a etapa 'up' é iniciada. | Não | | onBottomStep | Função executada quando a etapa 'bottom' é iniciada. | Não | | onError | Função executada quando ocorre um erro. Disponibiliza pelos parâmetros a instância do erro, a qual contém um identificador (propriedade code). | Não | | onSuccess | Função executada quando a verificação é finalizada com sucesso. Disponibiliza pelos parâmetros um objeto com os resultados, compostos pelo ID da solicitação (livenessId) e pelos frames de sucesso (successFrames). | Não | | onEnd | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |

Retorno da função livenessDetection (JavaScript)

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

| Nome da propriedade | Função | | ------------------- | ------ | | getVideoStream | Retorna a stream dos frames (MediaStream), caso ela esteja disponível. | | stopLivenessDetection | Para a verificação de prova de vida imediatamente e a finaliza completamente. | | pauseGettingFrames | Para a verificação temporariamente, a qual pode ser retomada posteriormente. | | resumeGettingFrames | Retoma a verificação, caso ela tenha sido pausada com a função pauseGettingFrames. |

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.

| Nome da propriedade | Função | É obrigatório? | | ------------------- | ------ | -------------- | | startGettingFrames | Função executada quando a obtenção de frames for iniciada. Não precisa retornar nenhum valor. | Não | | getNextFrame | Função que deve retornar os frames no formato string, ArrayBuffer, Buffer ou Buffer[]. Será executada várias vezes e deve sempre devolver o próximo frame. | Sim |

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)

| 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 | | useBillingAccounts | Booleano que controla a utilização das contas de faturamento customizadas | Não | | 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 (quando alguma operação é iniciada ou concluída, quando ocorre erro, etc.). Disponibiliza pelos parâmetros um objeto contendo as informações sobre a situação de cada tipo de processamento realizado (envio de documento, prova de vida, etc.). | 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. Disponibiliza pelos parâmetros o mesmo objeto fornecido pela função onUpdate, porém com todos os resultados preenchidos. | Não | | onEnd | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | 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 uploadIdentificationDocument retorna alguns métodos que podem ser utilizados para dar controlar as análises.

| Nome da propriedade | Função | | ------------------- | ------ | | startAll | Inicia todas as análises simultaneamente e espera dois parâmetros: o arquivo do documento (no formato Blob ou File) e, opcionalmente, as configurações para a prova de vida (caso deseje sobrescrevê-las). | | startDocumentUpload | Inicia a etapa de upload/análise do documento que será enviado e espera receber um parâmetro com o arquivo. (no formato Blob ou File). | | startLivenessDetection | Inicia a verificação de prova de vida e aceita as mesmas opções que a função livenessDetection, caso deseje sobrescrevê-las. | | startFaceComparison | Inicia a comparação da face do documento com a face detectada na prova de vida. Ela será iniciada automaticamente quando as outras análises forem concluídas, porém você pode usar essa função para fazer uma nova tentativa em caso de falha. | | getResults | Retorna os status atuais de cada análise, no formato apresentado abaixo. |

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>