santoid-sdk 5.3.0 → 5.4.0

package/README.md

@@ -54,11 +54,11 @@ startSDK()
 ## Envio de arquivos
 Um ponto importante são os tipos dos arquivos que são suportados pelo SDK.
 
-Para a execução em ambientes que utilizam JavaScript padrão, como os navegadores ou WebView, os tipos de arquivos suportados são **File** ou **Blob**.
+Para execução em navegadores e ambientes semelhantes, os tipos de arquivos suportados são **File** ou **Blob**.
 
 Para ambientes Node.js, os tipos dos arquivos devem ser **string, ArrayBuffer, Buffer ou Buffer[]**.
 
-## Utilização da biblioteca via CDN / Tags \<script\>
+## Utilização da biblioteca via CDN
 Caso deseje utilizar a biblioteca via CDN, importando-a diretamente em uma tag **script**, basta utilizar o caminho especificado no exemplo abaixo, substituindo o **VERSION** pela versão desejada.
 
 Ao importar a biblioteca via tag script, todas as funções do SDK ficarão disponíveis por meio da classe **SantoiDSDK**.
@@ -145,6 +145,7 @@ const typificationResponse = await typification({
 })
 
 typificationResponse.startCamera()
+typificationResponse.captureImage()
 
 // Ou
 
@@ -160,15 +161,29 @@ typificationResponse.sendFile(fileVariable)
 | customId            | Identificador customizado para auditoria. | Não |
 | startTheCameraImmediately | Booleano que determina se a câmera será acionada assim que a função for executada ou se será acionada manualmente depois. Por padrão, a câmera será acionada automaticamente. | Não |
 | onStart             | Função executada quando a verificação for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStart       | Função executada quando a câmera for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStop        | Função executada quando a câmera for interrompida. | 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.). <br><br>Disponibiliza pelos parâmetros um objeto contendo as informações sobre a situação do processamento (qual o status atual, se está carregando, se existe erro, etc.) | 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 |
 | onError             | Função executada quando ocorre um erro. <br><br>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. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados, compostos pelo ID da solicitação (**livenessId**) e pelos frames de sucesso (**successFrames**). | Não |
+| onSuccess           | Função executada quando a verificação é finalizada com sucesso. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados. | Não |
 | onEnd               | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
 
+#### Retorno da função typification (JavaScript)
+| Nome da propriedade | Função |
+| ------------------- | ------ |
+| startCamera         | Função para iniciar a câmera manualmente. <br><br>É possível informar nos parâmetros a direção de câmera desejada (**facingMode**), seguindo um modelo semelhante ao das funções de controle de câmera do próprio JavaScript (No mobile, por exemplo, facingMode == 'user' para usar a câmera da frente e facingMode == 'environment' para usar a câmera de trás). <br><br>Por padrão o facingMode é 'user'. |
+| stopCamera          | Função para desligar a câmera manualmente. |
+| captureImage        | Função para capturar a imagem que será utilizada para consumo com a câmera. |
+| getVideoStream      | Função para obter a stream de vídeo da câmera, se ela estiver disponível. |
+| sendFile            | Função para enviar arquivos manualmente, iniciando também o processamento. |
+
 #### Utilização em Node.js
 A utilização da função de Tipificação em Node.js é idêntica à utilização em JavaScript normal para browsers e ambientes semelhantes, com a exceção das funções e propriedades relacionadas à câmera, que não estão disponíveis nesta versão.
 
+#### Formato dos resultados
+Os resultados podem ser obtidos por meio da função de callback **onSuccess** por meio dos parâmetros. Sua estrutura é baseada na interface **ITypificationResult**, a qual pode ser consultada mais abaixo na seção de **Tipos comuns**.
+
 ### OCR
 Por meio do SDK também é possível utilizar a funcionalidade de **OCR** diretamente, que permite extrair as informações dos campos de um documento.
 
@@ -214,6 +229,7 @@ const ocrResponse = await ocr({
 })
 
 ocrResponse.startCamera()
+ocrResponse.captureImage()
 
 // Ou
 
@@ -229,15 +245,29 @@ ocrResponse.sendFile(fileVariable)
 | customId            | Identificador customizado para auditoria. | Não |
 | startTheCameraImmediately | Booleano que determina se a câmera será acionada assim que a função for executada ou se será acionada manualmente depois. Por padrão, a câmera será acionada automaticamente. | Não |
 | onStart             | Função executada quando a verificação for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStart       | Função executada quando a câmera for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStop        | Função executada quando a câmera for interrompida. | 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.). <br><br>Disponibiliza pelos parâmetros um objeto contendo as informações sobre a situação do processamento (qual o status atual, se está carregando, se existe erro, etc.) | 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 |
 | onError             | Função executada quando ocorre um erro. <br><br>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. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados, compostos pelo ID da solicitação (**livenessId**) e pelos frames de sucesso (**successFrames**). | Não |
+| onSuccess           | Função executada quando a verificação é finalizada com sucesso. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados. | Não |
 | onEnd               | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
 
+#### Retorno da função ocr (JavaScript)
+| Nome da propriedade | Função |
+| ------------------- | ------ |
+| startCamera         | Função para iniciar a câmera manualmente. <br><br>É possível informar nos parâmetros a direção de câmera desejada (**facingMode**), seguindo um modelo semelhante ao das funções de controle de câmera do próprio JavaScript (No mobile, por exemplo, facingMode == 'user' para usar a câmera da frente e facingMode == 'environment' para usar a câmera de trás). <br><br>Por padrão o facingMode é 'user'. |
+| stopCamera          | Função para desligar a câmera manualmente. |
+| captureImage        | Função para capturar a imagem que será utilizada para consumo com a câmera. |
+| getVideoStream      | Função para obter a stream de vídeo da câmera, se ela estiver disponível. |
+| sendFile            | Função para enviar arquivos manualmente, iniciando também o processamento. |
+
 #### Utilização em Node.js
 A utilização da função de OCR em Node.js é idêntica à utilização em JavaScript normal para browsers e ambientes semelhantes, com a exceção das funções e propriedades relacionadas à câmera, que não estão disponíveis nesta versão.
 
+#### Formato dos resultados
+Os resultados podem ser obtidos por meio da função de callback **onSuccess** por meio dos parâmetros. Sua estrutura é baseada na interface **IOcrResult**, a qual pode ser consultada mais abaixo na seção de **Tipos comuns**.
+
 ### Face Match
 Por meio do SDK também é possível utilizar a funcionalidade de **Face Match**, que permite comparar duas faces e verificar se são iguais. É possível enviar uma imagem que contenha dois rostos para comparação, ou enviar duas imagens, com um rosto em cada uma.
 
@@ -291,12 +321,12 @@ const faceMatchResponse = await faceMatch({
   // ...
 })
 
-ocrResponse.startCamera()
+faceMatchResponse.startCamera()
 faceMatchResponse.captureFirstImage()
 
 // Ou
 
-ocrResponse.sendFiles(fileVariable1, fileVariable2)
+faceMatchResponse.sendFiles(fileVariable1, fileVariable2)
 ```
 
 #### Opções para a função faceMatch (JavaScript)
@@ -308,15 +338,30 @@ ocrResponse.sendFiles(fileVariable1, fileVariable2)
 | customId            | Identificador customizado para auditoria. | Não |
 | startTheCameraImmediately | Booleano que determina se a câmera será acionada assim que a função for executada ou se será acionada manualmente depois. Por padrão, a câmera será acionada automaticamente. | Não |
 | onStart             | Função executada quando a verificação for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStart       | Função executada quando a câmera for iniciada. <br><br>Disponibiliza pelos parâmetros um objeto contendo a stream da transmissão (**videoStream**), caso disponível. | Não |
+| onCameraStop        | Função executada quando a câmera for interrompida. | 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.). <br><br>Disponibiliza pelos parâmetros um objeto contendo as informações sobre a situação do processamento (qual o status atual, se está carregando, se existe erro, etc.) | 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 |
 | onError             | Função executada quando ocorre um erro. <br><br>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. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados, compostos pelo ID da solicitação (**livenessId**) e pelos frames de sucesso (**successFrames**). | Não |
+| onSuccess           | Função executada quando a verificação é finalizada com sucesso. <br><br>Disponibiliza pelos parâmetros um objeto com os resultados. | Não |
 | onEnd               | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
 
+#### Retorno da função faceMatch (JavaScript)
+| Nome da propriedade | Função |
+| ------------------- | ------ |
+| startCamera         | Função para iniciar a câmera manualmente. <br><br>É possível informar nos parâmetros a direção de câmera desejada (**facingMode**), seguindo um modelo semelhante ao das funções de controle de câmera do próprio JavaScript (No mobile, por exemplo, facingMode == 'user' para usar a câmera da frente e facingMode == 'environment' para usar a câmera de trás). <br><br>Por padrão o facingMode é 'user'. |
+| stopCamera          | Função para desligar a câmera manualmente. |
+| captureFirstImage   | Função para capturar a primeira imagem que será utilizada para o Face Match. <br><br> Por padrão, iniciará o processamento após a captura, porém caso deseje utilizar duas imagens você pode evitar isso utilizando a opção **startProcessing**. |
+| captureSecondImage  | Função para capturar a segunda imagem que será utilizada para o Face Match. <br><br> Por padrão, iniciará o processamento após a captura, porém caso deseje impedir isso você pode utilizar a opção **startProcessing**. |
+| getVideoStream      | Função para obter a stream de vídeo da câmera, se ela estiver disponível. |
+| sendFiles           | Função para enviar arquivos manualmente, iniciando também o processamento. Como o Face Match suporta até 2 arquivos, você pode escolher entre enviar apenas 1 arquivo com dois rostos para análise ou 2 arquivos com 1 rosto em cada. |
+
 #### Utilização em Node.js
 A utilização da função de Face Match em Node.js é idêntica à utilização em JavaScript normal para browsers e ambientes semelhantes, com a exceção das funções e propriedades relacionadas à câmera, que não estão disponíveis nesta versão.
 
+#### Formato dos resultados
+Os resultados podem ser obtidos por meio da função de callback **onSuccess** por meio dos parâmetros. Sua estrutura é baseada na interface **IFaceMatchResult**, a qual pode ser consultada mais abaixo na seção de **Tipos comuns**.
+
 ### Prova de Vida
 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.
 
@@ -366,7 +411,7 @@ As propriedades disponíveis para utilização no objeto de opções estão list
 | onEnd               | Função executada quando a verificação é finalizada, seja com erro ou com sucesso. | Não |
 
 <br>
-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.
+Caso a função seja executada em um navegador (ou ambiente semelhante), 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.
@@ -574,7 +619,53 @@ Em que:
 ```typescript
 type TResultStatuses = 'success' | 'error' | null
 
-interface ITypificationResult {
+type TPositions = 'front' | 'right' | 'left' | 'up' | 'bottom'
+
+interface ILivenessResults {
+  livenessId: string
+  successFrames: Record<TPositions, Blob>
+}
+```
+
+Os tipos **ITypificationResult** e **IFaceMatchResult** podem ser conferidos na seção de **Tipos comuns**, disponível mais a frente na documentação.
+
+#### 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.
+
+```ts
+import { uploadIdentificationDocument } from 'santoid-sdk/server/liveness'
+
+const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
+  token: 'string',
+  track: 'string',
+
+  livenessDetectionOptions: {
+    getNextFrame () {
+      // ...
+    },
+
+    // ...
+  },
+
+  // ...
+})
+```
+
+## Tipos comuns
+Esta seção destina-se a disponibilizar os tipos dos resultados de algumas funções. Algumas funcionalidades possuem resultados com estruturas parecidas internamente.
+
+A tipificação, por exemplo, pode ser configurada para iniciar também o OCR dos campos e, consequentemente, conter resultados de OCR em seu interior.
+
+Por essa razão, para simplificar o entendimento, serão disponibilizados a seguir as interfaces dos resultados dessas funcionalidades de forma simplificada.
+
+### Estrutura base
+```ts
+interface IBaseAsyncResult {
   count: number
   customerRequestId: string
   domain: string
@@ -585,80 +676,115 @@ interface ITypificationResult {
   service: string
   status: string
   track: string
+}
+```
 
-  documents: Array<{
-    typification: {
-      id: string
-      score: number
-    }
+### Resultados da Tipificação
+```ts
+// Resultados completos da tipificação
+interface ITypificationResult extends IBaseAsyncResult {
+  documents: ITypificationDocumentResult[]
+}
+
+// Resultados para um documento individual
+interface ITypificationDocumentResult {
+  typification: {
+    id: string
+    score: number
+  }
+
+  error?: {
+    message: string
+  }
 
-    error?: {
+  ocr?: {
+    template: string
+
+    labels: ICropResult[] | null
+  } | boolean
+}
+```
+
+### Resultados do OCR
+```ts
+// Resultados completos do OCR
+interface IOcrResult extends IBaseAsyncResult {
+  template: string
+
+  documents: IOcrDocumentResult[]
+}
+
+// Resultados para um documento individual
+interface IOcrDocumentResult {
+  error?: {
+    message: string
+  }
+
+  ocr: {
+    template: string
+
+    labels: ICropResult[] | null
+  } | boolean
+}
+
+// Resultados para um único campo
+interface ICropResult {
+  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: IOcrListResult[] | null
+
+  serpro_query?: {
+    serpro_data: any
+    search_logs: {
+      document: string
+      type: string
+      search_time: string
+      status_code: number
       message: string
     }
+  } | null
 
-    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
-  }>
-}
+  validation: {
+    type: string | null
+    value: number | string | boolean
+  } | null
 
-export type TPositions = 'front' | 'right' | 'left' | 'up' | 'bottom'
+  validationSerpro?: Record<string, number | boolean>
+}
 
-interface ILivenessResults {
-  livenessId: string
-  successFrames: Record<TPositions, Blob>
+// Resultados para os campos internos de um campo com OCR em lista configurado
+interface IOcrListResult {
+  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
 }
+```
 
+### Resultados do Face Match
+```ts
 interface IFaceMatchResult {
   domain: string
   track: string
@@ -677,31 +803,4 @@ interface IFaceMatchResult {
   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.
-
-```ts
-import { uploadIdentificationDocument } from 'santoid-sdk/server/liveness'
-
-const uploadIdentificationDocumentResponse = uploadIdentificationDocument({
-  token: 'string',
-  track: 'string',
-
-  livenessDetectionOptions: {
-    getNextFrame () {
-      // ...
-    },
-
-    // ...
-  },
-
-  // ...
-})
-```
+```

package/api/ApiFaceMatchService.d.ts

@@ -9,9 +9,6 @@ interface IFaceMatchStatusGetResponse extends Awaited<ReturnType<InstanceType<ty
     fileImage1?: string;
     fileImage2?: string;
 }
-export interface IError {
-    error: string;
-}
 export interface IFaceMatchResult {
     domain: string;
     track: string;
@@ -20,7 +17,9 @@ export interface IFaceMatchResult {
     requestType: string;
     customerRequestId: string;
     executionDatetime: string;
-    error?: IError;
+    error?: {
+        error: string;
+    };
     status: string;
     comparison_score: number;
     similarity_score: number;

package/api/ApiOcrService.d.ts

@@ -57,5 +57,6 @@ export interface IOcrDocumentResult {
     } | boolean;
 }
 export interface IOcrResult extends IBaseAsyncResult {
+    template: string;
     documents: IOcrDocumentResult[];
 }

package/api/ApiTypificationService.d.ts

@@ -13,7 +13,7 @@ export interface ITypificationDocumentResult {
     error?: {
         message: string;
     };
-    ocr: {
+    ocr?: {
         template: string;
         labels: ICropResult[] | null;
     } | boolean;