4. Recursos - Documentos

Campos sinalizados com * são de caráter obrigatório para utilizar corretamente as APIs.

IMPORTANTE:

  • Todos os exemplos de chamadas nas APIs abaixo estão apontando para as URL do ambiente de SANDBOX. Para maiores detalhes em relação as URLs dos ambientes consultar API Reference.
  • Existem URLs que estão disponíveis para o contexto SDK e também para o Backoffice. Atentar-se para isso quando houver o placeholder sdk na URL, pois o mesmo deve ser substituído de acordo com o caso de uso, podendo assumir os valores "sdk" ou "backoffice".

Fluxo recomendado para Backoffice​

  • Para rotas /backoffice/*, utilize x-api-key diretamente em cada requisição.
  • O endpoint /backoffice/v1/handshake é legado, permanece por compatibilidade e está em processo de depreciação.
  • Quando houver exemplos com Authorization: Bearer <SessionToken> nesta página, considere-os como fluxo legado para Backoffice.
  • No fluxo direto do backoffice, o sessionId operacional é retornado no payload da resposta (sucesso e erro).

4.1 Handshake​

Descrição​

A API do Fortface possui um sistema proprietário de criação de sessões. Após o usuário passar pela etapa de credenciamento, ele pode criar sessões temporárias de acesso restrito às ações previamente determinadas pelo sistema, construídas a partir do Handshake.

Antes de detalhar os campos do header do Handshake e as etapas de processamento, é importante abordar o processo de criptografia e descriptografia do device fingerprint.

A manipulação de dados vinculados a qualquer processo interno ao Fortface segue um rigoroso processo de segurança. Um dos dados mais utilizados durante todos os processos é o device fingerprint, e um contrato específico foi utilizado para encapsulá-lo de forma segura na requisição.

Agora, com o processo de criptografia e descriptografia explicado, vamos voltar a falar sobre os campos de consulta do header do Handshake, que são:

  • Content-Type: Informando a natureza de leitura do campo application/json

  • x-api-key: Chave de segurança configurada para o cliente cliente.

Abaixo segue o corpo (body) necessário para o Handshake, e o campo X-API-KEY no header se torna necessário para identificar o cliente requisitante, bem como suas devidas permissões.

Endpoint: /handshake

Method: POST

Payload:

  • galleryId*: Identificador da galeria do usuário.
  • accountName*: Identificador da conta do usuário.
  • action*: Ação a ser executada: document.
  • deviceRequestInfo*: Informações criptografadas do dispositivo que originou o evento.
  • externalTransactionId: Transação externa utilizada para agrupamento das sessões. (opcional) O identificador do usuário é o externalUserId (nos endpoints de enroll, identify, capture).

Request (Exemplo)​

context: sdk ou backoffice

sdk/handshake : Gera uma sessão valida para uma action via SDK

backoffice/handshake : Gera uma sessão valida para uma action via Backoffice

Exemplo: Uma sessão gerada sdk/handshake não será válida para o endpoint backoffice/liveness, mas sim para o sdk/liveness

curl --request POST \
  --url https://api-sandbox.fortface.ai/{context}/v1/handshake \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: string' \
  --data '{
    "galleryId": "string",
    "accountName": "string",
    "action": "document",
    "deviceRequestInfo": "string",
    "externalTransactionId": "string"
  }'

Response (Exemplo)​

  "body": {
    "sessionToken": "TOKEN DE SESSÃO PARA ACESSO AOS RECURSOS DA API",
    "sessionKey": "CHAVE DA SESSÃO UTILIZADA NO SDK",
    "sessionId": "IDENTIFICADOR DA SESSÃO GERADA PELO HANDSHAKE"
  }

Etapas de Processamento​

  1. O device fingerprint é criptografado e extraído do “deviceRequestInfoNaN” e, em seguida, é descriptografado.

  2. Nesta etapa, é realizada uma verificação do hash do device fingerprint. O hash é gerado por uma função que associa um hash a cada campo do deviceInfo. A API Fortface utiliza o mesmo sistema do SDK para gerar o hash local com base nos dados do campo deviceInfo que o “deviceRequestInfoNaN” descriptografado possui. Essa abordagem permite criar uma camada de verificação de confiabilidade e integridade estrutural dos dados em cada requisição ao Handshake.

  3. Uma sessão é criada mediante a existência de uma galeria, conforme informado no propriedade galleryId. A api-key associada à essa galeria deve ter a permissão para realizar o Handshake.

4.2 Extração de Dados do Documento e Identificação 1:1​

O Fortface permite a extração de dados do documento e do provedor de identificação através do endpoint /document, além de possibilitar a validação 1:1 da identidade do usuário.

Importante: O campo documentGroupId é um agrupador de rquisições, porém não é obrigatório.

Detalhes da Requisição​

  • Ação de Handshake: document
  • Endpoint: /document
  • Método: POST

Headers​

  • Content-Type: application/json (Define o formato da requisição)
  • Authorization: Bearer {SessionToken} (Token gerado pelo endpoint /handshake) para SDK e fluxo legado do Backoffice.
  • x-api-key: Header recomendado para chamadas diretas do Backoffice (sem handshake).

Payload​

  • imgData (obrigatório): Dados da imagem ou arquivo pdf. São criptografados pelo SDK ou fornecidos em Base64 no BackOffice.
  • externalUserId (opcional): CPF do Usuário. Deve ser informado se for necessária uma comparação com um rosto previamente cadastrado.
  • documentGroupId: (opcional): ID do grupo de documentos
  • referenceSessionId: (opcional): Identificador de sessão que será utilizada para Identificação de Rosto (Identify). Este campo é utilizado para substituir o uso de Registro de Novo Rosto (Enroll).
  • key (obrigatório): Chave de criptografia AES, protegida por um algoritmo assimétrico. (Usado no SDK)
  • data (obrigatório): Dados criptografados do usuário. (Usado no SDK)
  • returnFile (opcional): Indica se a foto/arquivo deve ser retornada na resposta. (Usado no SDK)

Exemplo de Request​

Contexto: SDK

curl --request POST \
  --url 'https://api-sandbox.fortface.ai/sdk/v1/document' \
  --header 'Authorization: Bearer (SessionToken do handshake)' \
  --header 'Content-Type: application/json' \
 --data '{
    "imgData": "String <Retorna do SDK> ou <Base64 no BackOffice>",
    "externalUserId": "String",
    "key": "String <Retorna do SDK>",
    "data": "String <Retorna do SDK>",
    "returnFile": "Boolean <Retorna do SDK>",
    "documentGroupId": "String <Agrupador de requisições>",
    "referenceSessionId": "String <Identificador de sessão de referência>"
  }'

Response (Exemplo)​

{
  "providers": {
    "typifier": {
      "status": "string",
      "documentType": "string",
      "documentSide": "string",
      "occlusion": "boolean",
      "occlusionReason": "string",
      "country": "string",
      "confidence": "number",
      "isPdf": "boolean",
      "hasCertificate": "boolean",
      "faceStatus": "string",
      "version": "string",
      "pipeline": "string",
      "analysisNote": "string"
    },
    "identify": {
      "matchLevel": {
        "value": "number"
      },
      "status": "string"
    }
  },
  "hash": "string",
  "documentGroupId": "string",
  "api": {
    "env": "string",
    "timestamp": "number",
    "version": "string"
  },
  "fileData": "string"
}

Possiveis Tipos de Documentos Classificados

NATIONAL_ID - Refere-se a documentos de identificação civis emitidos por governos nacionais para cidadãos do próprio país.
FOREIGN_ID - Documentos emitidos por um país diferente do país de origem do indivíduo, destinados a estrangeiros legalmente residentes.
PASSPORT - Documento de viagem internacional, emitido pelo país de origem do cidadão, utilizado para identificação fora do território nacional.
DRIVER_LICENSE - Documento que autoriza e identifica o condutor de veículos automotores.
MILITARY_ID - Documento emitido pelas forças armadas ou instituições militares para identificação de militares ativos, inativos ou reservistas.
STUDENT_ID - Documento que comprova o vínculo do portador com uma instituição de ensino.
PROFESSIONAL_ID - Carteiras emitidas por conselhos de classe, órgãos ou entidades reguladoras de profissões ( OAB, CRM etc)

Última atualização em por Henrique Scarabele