2. Começando

Pré-requisitos para utilizar a API

• Conhecimento básico de programação e uso de APIs REST.
• Um ambiente de desenvolvimento configurado para fazer requisições HTTP.

2.1 Permissionamento por API-KEY

Para garantir a segurança, qualidade e controle das transações realizadas no ambiente do FortFace, o permissionamento é baseado na API-KEY. Trata-se de um chave (UUID) enviado no header das requisições.

Essa API-KEY terá as permissões liberadas de acordo com as condições comerciais contratadas.

Permissões

Contexto	API	HTTP Methods	Version	Handshake Action
SDK	handshake	POST	V1	N/A
SDK	enroll	POST	V1	enroll
SDK	identify	POST	V1	identify
SDK	search	POST	V1	search
SDK	liveness	POST	V1	liveness
SDK	capture	POST	V1	capture
Backoffice	handshake	POST	V1	N/A
Backoffice	enroll	POST, PUT, DELETE	V1	enroll, update-enroll, delete-enroll
Backoffice	identify	POST	V1	identify
Backoffice	search	POST	V1	search
Backoffice	liveness	POST	V1	liveness
Backoffice	capture	POST	V1	capture
Backoffice	photo	GET	V1	N/A
Backoffice	log session	GET	V1	N/A

Fluxo preferencial para Backoffice: autenticação direta por x-api-key em cada chamada.

O endpoint /backoffice/v1/handshake permanece disponível apenas por compatibilidade e está em processo de depreciação.

2.2 Configurações da Galeria

Armazenamento de Imagens

O fortface oferece a possibilidade de o cliente organizar as fotos armazenadas de maneira flexível, de acordo com o contexto de negócio. Para isso pode utilizar uma ou mais gelerias em suas operações, para que as mesmas estejam armazenadas em diferentes contextos.

Atualmente a criação e configuração de galerias não está disponível para o cliente, assim como as permissões por API-KEY, são criadas e configuradas mediante as condições comerciais contratadas.

Uma configuração importante que deve ser levada em consideração é quanto a persistência das fotos.

Caso a flag savePhoto seja configurada com valor true a imagem será armazeda normalmente pelo fortface, seja no contexto SDK ou Backoffice. Porém, caso esse valor seja false temos alguns cenários:

• SDK

  Requisições feitas nas APIs do contexto SDK sempre retornarão no response a imagem capturada, no formato base64, quando a flag savePhoto for false. Isso ocorre porque o cliente não teve acesso à imagem capturada pelo SDK, então retornamos a foto para que o cliente possa armazená-la da forma que entender ser melhor.
  O cliente pode querer, mesmo armazenando a foto, que a mesma seja retornada no response. Para isso no contexto do SDK (enroll, identify, search, liveness), é possível informar no request a property returntPhoto. O valor padrão é false (exceto cenários onde a foto não é salva). Quando returntPhoto for true, a mesma será retornada no response em formato base64.

• Backoffice

  Requisições feitas nas APIs do contexto Backoffice não irão retornar a foto, pois já recebemos na requisição a imagem aberta em base64 e não faz sentido retornar algo que já foi enviado.

Atualização Automática de Foto de cadastro para usuários provenientes de tombamento

• O Fortface oferece a possibilidade de atualizar a foto do usuário automaticamente uma vez que a primeira identificação for realizada com sucesso. Para isso, considera-se os seguintes parâmetros:

  • Usuário proveniente de tombamento de bases legadas do cliente (backoffice/enroll)
  • Aprovado no Liveness
  • Primeira transação com sucesso acima do MatchLevel estabelecido pelo cliente

• Quando esses parâmetros são atendidos, a foto de cadastro do cliente é substituída por uma capturada através do SDK Fortface, aumentando assim a performance média da solução.

---

2.3 Certificados mTLS

Para reforçar ainda mais a segurança na comunicação entre o cliente e o Fortface, o processo de certificação mTLS foi aprimorado.

Agora, o cliente é responsável por gerar localmente o arquivo .csr (Certificate Signing Request) e enviá-lo ao Fortface.

Após o envio, retornaremos o certificado assinado, pronto para uso na integração.

Para facilitar o processo, disponibilizamos uma ferramenta com instruções detalhadas para gerar o certificado corretamente:

👉 https://mtls-tool.fortface.com/

Quando o cliente HTTPS do seu ambiente tiver suporte, prefira certificado (.crt ou .pem) e chave (.key) separados em vez de PFX; em alguns ambientes o uso direto de PFX pode resultar em erro (ex.: "Unsupported PKCS12 PFX data"). Para extrair o certificado do PFX: openssl pkcs12 -in arquivo.pfx -clcerts -nokeys -out certificado.crt -passin pass:SENHA. Use o .crt e o .key nas opções do cliente HTTPS (e passphrase se a chave for protegida por senha).