Autenticar usuário

Este serviço valida tanto a prova 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 é 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 a Template Biométrico (TemplateRaw).

Endpoint

POST /services/authenticateUser

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, cifrado 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ória 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).
tracking	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 Service Result Code
serviceResultLog	string	Campo descritivo do resultado da execução. Inclui detalhes quando há um erro ou exceção.
serviceFacialSimilarityResult	number	Valor que indica a semelhança facial entre o registeredTemplateRaw e o bestImageToken. 1.0 = 100%
merchantReferenceId	string	Referência enviada no corpo da solicitação.
registeredTemplateRaw	string	Template Biométrico registrado retornado pelo SDK SelphID para uso em autenticações posteriores.
timestamp	string	Marca de tempo (UTC) da resposta no formato YYYY-MM-DDThh🇲🇲ssZ
transactionId	string	Identificador de transação associado à solicitação processada pela API.

Service Result Code

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

Código de resultado do serviço: Autenticar usuário

Códigos de resultado específicos do Endpoint authenticateUser:

serviceResultCode	Descrição	Código HTTP
0	Usuário autenticado com sucesso.	200
-100	O parâmetro registeredTemplateRaw não coincide com o ID: [XXX]	200
-101	O parâmetro bestImageToken não corresponde a uma pessoa viva.	200
-102	A autenticação do usuário falhou porque o templateRaw não corresponde.	200

Exemplo de resposta

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

400 Solicitação inválida

{
  "status": 400,
  "title": "Solicitação inválida",
  "detail": "Requisição inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Não autorizado

{
  "message": "Não autorizado"
}

403 Acesso negado

{
  "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita"
}

502 Gateway inválido

{
  "status": 502,
  "title": "Gateway inválido",
  "detail": "O servidor recebeu uma resposta inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "A solicitação do Endpoint excedeu o tempo limite"
}