Autenticar usuário V2

Este serviço valida tanto o teste de vida quanto a autenticação facial. Compara o Template Biométrico, previamente validado e armazenado no repositório de dados do cliente durante o processo de Onboarding, com um bestImageToken gerado no momento da autenticação.

Funcionalidade

• Primeira chamada: Define um userId único para o usuário.

• Autenticação: Em cada tentativa de autenticação, o userId é enviado junto com o Template Biométrico registrado. Esse Template Biométrico é comparado com a imagem tokenizada atual (bestImageToken). Se houver correspondência e a verificação de vida for aprovada, o usuário é autenticado com sucesso.

Integração

Requer a implementação do Widget Selphi Mobile ou do Widget Selphi Web para gerar o bestImageToken e o Template Biométrico (TemplateRaw).

Endpoint

POST /services/authenticateUser/v2

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	API Key de autorização de acesso.
family	string	Não	Valor: Authentication. Obrigatório com o serviço de Tracking.

Todas as chamadas aos Endpoints para Tracking com Identity Platform devem conter o header family.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
userId	string	Sim	Identificador único do usuário. Deve ser persistido e associado ao Template Biométrico correspondente. Precisa de pelo menos dois dígitos.
registeredTemplateRaw	string	Sim	Template gerado pelo Widget Selphi, criptografado com AES256 e tokenizado, enviado em formato Base64. Representa o padrão facial do usuário com a pose frontal mais detectada.
image	string	Não	Imagem em formato Base64 obtida do registro civil. Torna-se obrigatória se o Template Biométrico registrado (registeredTemplateRaw) não for fornecido.
bestImageToken	string	Sim	Propriedade bestImage tokenizada gerada pelo Widget Selphi no momento da autenticação.
template	string	Não	Template Biométrico em formato Base64. Torna-se obrigatório se a bestImage tokenizada (bestImageToken) não for fornecida.
merchantReferenceId	string	Sim	Referência do cliente para cada autenticação. Recomenda-se que esse dado não contenha informações sensíveis como PII (informação de identificação pessoal).
rastreamento	object	Não	Objeto que representa as informações de Tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação: Com Template Biométrico registrado

{
  "userId": "001",
  "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Exemplo de solicitação: Com imagem do registro civil

{
  "userId": "001",
  "image": "/9j/4AAQ...",
  "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...",
  "merchantReferenceId": "authenticate-001",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço. Veja Código de Resultado do Serviço
serviceResultLog	string	Campo descritivo do resultado da execução. Inclui detalhes quando há um erro ou exceção. Se for bem-sucedido, indica a descrição do código de resultado.
serviceFacialSimilarityResult	number	Valor que indica a similaridade facial entre o registeredTemplateRaw e o bestImageToken. 1.0 = 100%
serviceFacialAuthenticationLog	string	Campo descritivo do resultado da autenticação facial. Inclui detalhes quando há um erro ou exceção no módulo.
serviceFacialAuthenticationResult	integer	Código que indica o resultado da autenticação facial. Ver Resultado da Autenticação Facial do Serviço
serviceLivenessResult	integer	Código que indica o resultado do teste de vida passivo. Ver Resultado do Service Liveness
serviceLivenessLog	string	Campo descritivo do resultado da verificação de vida passiva. Inclui detalhes quando há um erro ou exceção.
merchantReferenceId	string	Referência enviada no corpo da solicitação.
registeredTemplateRaw	string	Template Biométrico registrado devolvido pelo SDK SelphID para uso em autenticações posteriores.
timestamp	string	Marca temporal (UTC) da resposta no formato YYYY-MM-DDThh🇲🇲ssZ
transactionId	string	Identificador da transação associado à solicitação processada pela API.

Código de Resultado do Serviço

O serviceResultCode indica o resultado geral da execução do serviço:

serviceResultCode	Descrição	Código HTTP
0	A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente.	200

Resultado do Service Liveness

O serviceLivenessResult indica o resultado da avaliação do teste de vida passivo:

Código	Resultado	Descrição
0	None	Não foi possível avaliar o teste de vida.
1	Spoof	DEPRECADO. Usar 'NoLive' em seu lugar.
2	Uncertain	DEPRECADO
3	Live	Assume-se que o sujeito está vivo.
4	NoneBecauseBadQuality	Não foi possível avaliar o teste de vida devido à má qualidade da imagem.
5	NoneBecauseFaceTooClose	Não foi possível avaliar o teste de vida porque os rostos detectados estão muito próximos das bordas.
6	NoneBecauseFaceNotFound	Não foi possível avaliar o teste de vida porque não foram detectados rostos.
7	NoneBecauseFaceTooSmall	Não foi possível avaliar o teste de vida porque os rostos detectados são muito pequenos.
8	NoneBecauseAngleTooLarge	Não foi possível avaliar o teste de vida porque o ângulo entre os rostos excede o limite permitido.
9	NoneBecauseImageDataError	Não foi possível avaliar o teste de vida devido a erros no formato da imagem.
10	NoneBecauseInternalError	Não foi possível avaliar o teste de vida devido a um erro interno.
11	NoneBecauseImagePreprocessError	Não foi possível avaliar o teste de vida devido a um erro no pré-processamento da imagem.
12	NoneBecauseTooManyFaces	Não foi possível avaliar o teste de vida porque foram detectados muitos rostos na imagem.
13	NoneBecauseFaceTooCloseToBorder	Não foi possível avaliar o teste de vida porque o rosto está muito próximo da borda.
14	NoneBecauseFaceCropped	Não foi possível avaliar o teste de vida porque o rosto está cortado.
15	NoneBecauseLicenseError	Não foi possível avaliar o teste de vida devido a um erro de Licença.
16	NoneBecauseFaceOccluded	Não foi possível avaliar o teste de vida porque o rosto está ocluído.
17	NoLive	Não foi detectada vida.
18	NoneBecauseEyesClosed	Não foi possível avaliar o teste de vida porque os olhos da pessoa estão fechados.

Resultado da Autenticação Facial do Serviço

O serviceFacialAuthenticationResult indica o resultado das operações de correspondência facial:

Código	Resultado	Descrição
0	NONE	Não foi possível realizar a verificação facial.
1	NEGATIVE	O processo foi executado corretamente. A comparação do padrão facial dos rostos não corresponde.
3	POSITIVE	O processo foi executado corretamente. A comparação do padrão facial dos rostos é positiva. O valor de serviceFacialSimilarityResult indica a % de semelhança entre as imagens comparadas.
4	NENHUM DEVIDO A EXCESSO DE POSE	Não foi possível realizar a verificação facial devido à posição do rosto.
5	NENHUM DEVIDO A EXTRAÇÕES INVÁLIDAS	Não foi possível realizar a verificação facial devido a problemas na extração do padrão facial.

Exemplo de resposta

{
  "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155",
  "serviceResultCode": 0,
  "serviceResultLog": "",
  "serviceFacialSimilarityResult": 0.9946970343589783,
  "serviceFacialAuthenticationLog": "Positive",
  "serviceFacialAuthenticationResult": 3,
  "serviceLivenessLog": "Live",
  "serviceLivenessResult": 3,
  "timestamp": "2024-10-29T20:29:24Z",
  "transactionId": "531ecbb1-de3d-4907-a737-0db236674e9a",
  "registeredTemplateRaw": "BAIBAQGo+puJyHjfRD8n..."
}

400 Requisição inválida

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Não autorizado

{
  "message": "Unauthorized"
}

403 Acesso negado

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Gateway inválido

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Tempo limite do gateway

{
  "message": "Endpoint request timed out"
}