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/server/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/server/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/client/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

Caso a função seja executada em um navegador (ou ambiente semelhante que utilize JavaScript, como o WebView, por exemplo), não é obrigatório fornecer uma função que retorne os frames para verificação (getNextFrame), pois o próprio SDK iniciará a câmera e realizará todo o processo caso a função não seja fornecida.

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/client/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/server/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/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
onValidationRequested	Função executada quando o status do processamento é "validation". Retorna informações da requisição para que o usuário consiga fazer a validação manual da requisição	Não
onClearInterval	Função executada após a implementação da função setInterval(), retorna a variável atribuída ao setInterval() permitindo que o usuário consiga utilizar a função clearInterval() para limpar o temporizador quando desejar	Não

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

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

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

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

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

  onEnd () {
    // ...
  },

  onValidationRequested (requestInformation) {
    // ..
  },

  onClearInterval (interval) {
    // ..
  },

  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 {
  count: number
  customerRequestId: string
  domain: string
  error: object
  executionDatetime: string
  requestId: string
  requestType: string
  service: string
  status: string
  track: string

  documents: Array<{
    typification: {
      id: string
      score: number
    }

    error?: {
      message: string
    }

    ocr: {
      template: string

      labels: Array<{
        x: number
        y: number
        w: number
        h: number
        bottomRight: number[]
        topLeft: number[]

        label: string | null

        text: string | null
        ocr_score: number | null
        crop: string | null
        ocrInterpretive?: boolean | string | null
        ocrList?: Array<{
          x: number
          y: number
          w: number
          h: number
          bottomRight: number[]
          topLeft: number[]

          dataField?: string
          dataFieldValue?: boolean

          label: string | null
          ocr?: string | null
          ocr_score?: number
          cropBase64?: string | null
        }> | null

        serpro_query?: {
          serpro_data: any
          search_logs: {
            document: string
            type: string
            search_time: string
            status_code: number
            message: string
          }
        } | null

        validation: {
          type: string | null
          value: number | string | boolean
        } | null

        validationSerpro?: Record<string, number | boolean>
      }> | null
    } | null
  }>
}

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

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

interface IFaceMatchResult {
  domain: string
  track: string
  service: string
  requestId: string
  requestType: string
  customerRequestId: string
  executionDatetime: string
  error?: {
    error: string
  }
  status: string
  comparison_score: number
  similarity_score: number
  match: boolean
  fileImage1?: string
  fileImage2?: string
}

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/server/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/index.js"></script>

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