Solicitação de novo token

Este endpoint permite que o parceiro solicite um token de autenticação para realizar a confirmação da identidade do seu cliente.

Pré-requisito

Para que seja possível utilizar este endpoint, é necessário que:

O cliente de nosso parceiro tenha sido aprovado no processo de envio e análise de documentos.

Requisição (Request)

Requisição HTTP

POST https://api-mtls.sandbox.bankly.com.br/customers/{documentNumber}/id-token

--request POST \
--url 'https://api-mtls.sandbox.bankly.com.br/customers/64775621033/id-token' \
--header 'x-correlation-id: {{guid}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'api-version: 1.0' \
--data '{
    "challenge": "DEVICE_VERIFICATION",
    "claims": {
    "deviceHash": "9b0c0dfa48ae46923769e5329f1acb72dfb030bfab761cbeeaf8d04b7be6b384"
    },
    "ttl": 900,
    "provider": "UNICO_CHECK",
    "providerMetadata": {
    "encrypted": "TOKEN JWT"
    }
}'

Autorização

Para garantir a segurança nas requisições, todos os endpoints do Bankly utilizam scopes como parte do seu fluxo de autorização.
Esta requisição requer o scope descrito a seguir:

Scope	Descrição
`security.id-token.create`	Concede acesso para a criação de um token de autenticação de identidade.

Cabeçalhos (Headers)

Nome	Descrição
`api-version`	Obrigatório. Versão da API. Atualmente estamos na versão 1.0.
`Authorization`	Obrigatório. Token de autorização do tipo Bearer.
`x-correlation-id`	Obrigatório. Informe um GUID, sendo um novo cada requisição.

Parâmetros da rota (Path)

No path desta requisição envie os seguintes campos:

Nome	Tipo	Descrição
`documentNumber`	`path`	Obrigatório. Número de documento do cliente (CPF).

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`challenge`	`string`	Obrigatório. Tipo de desafio. Para a validação de um dispositivo, esse campo deve apresentar o valor "DEVICE_VERIFICATION”.
`claims`	`object`	Obrigatório. Objeto que contém informações sobre as claims (declarações adicionadas ao token para fornecer dados complementares sobre o contexto ou sobre as permissões associadas ao token).
`claims.deviceHash`	`string`	Obrigatório. Hash do dispositivo, retornado no endpoint de registro de novo dispositivo móvel.
`provider`	`string`	Obrigatório. Nome do provedor, que, nesse caso, é UNICO_CHECK.
`providerMetadata`	`object`	Obrigatório. Objeto que contém a imagem criptografada.
`providerMetadata.encrypted`	`string`	Obrigatório. Token JWT da imagem criptografada gerado dentro do aplicativo do parceiro no momento da captura da selfie. A imagem não deve ultrapassar 4 MB.
`tll`	`int`	Tempo de vida do token, que é de, no máximo, 900 segundos.

{
	"challenge": "DEVICE_VERIFICATION",
	"claims": {
		"deviceHash": "9b0c0dfa48ae46923769e5329f1acb72dfb030bfab761cbeeaf8d04b7be6b384"
	},
	"ttl": 900,
	"provider": "UNICO_CHECK",
	"providerMetadata": {
		"encrypted": "TOKEN JWT"
	}
}

🚧
Importante
É fundamental instruir o seu cliente a seguir todas as orientações para o envio de fotos para evitar erros na requisição.

Resposta (Response)

O status code 202 indicará que o token foi criado com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`id-token`	`string`	GUID do token gerado.
`expiresIn`	`integer`	Tempo de vida do token, que é de, no máximo, 900 segundos.

{
  "id-token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expiresIn": 900
}

👍
Dica
Para simular uma requisição nesse endpoint, acesse o API Reference.

Erros

Este endpoint pode retornar erros específicos, conforme a tabela a seguir:

Status code	Código	Mensagem	Significado
400	—	Invalid challenge type.	O tipo do desafio enviado não é válido.
400	—	Invalid claims.	A propriedade `deviceHash` não pode ser nula ou vazia.
400	—	Invalid claim format. Claim should be a key value pair of string.	O formato do conteúdo enviado no objeto `claim` deve ser `string`.
400	—	Ttl should be equals or lower then 900 seconds.	O valor informado no campo `ttl` é superior a 900 segundos.
400	—	Encrypted size must be lower or equals 4 MB.	O tamanho da imagem criptografada ultrapassa 4 MB.
422	BIOMETRY_TOKEN_REFUSED	Biometry token refused. Please try send a image.	Não foi possível gerar um token para essa imagem. Tente enviá-la novamente.
422	IMAGE_REGISTRATION_NOT_FOUND	Image registration not found.	Não foi encontrada em nosso registro uma imagem que corresponda com a que foi enviada.
422	ID_TOKEN_REFUSED	Id Token refused. Please try send another image.	A imagem foi recusada. Verifique as orientações para o envio de imagens e solicite ao cliente que envie uma nova selfie.
422	PROVIDER_PROCESS_ID_NOT_FOUND	ProcessId not found. Make sure the SELFIE has been submitted and approved.	Não foi encontrado o identificador da selfie em nosso banco de dados. Verifique se no processo de Onboarding do cliente sua selfie foi aprovada.
422	INVALID_SELFIE	It's not an image or it's an injection attempt. Please try send another image.	A selfie não é válida por não se tratar de uma imagem. Há possibilidade de tentativa de fraude. Avalie o risco antes de solicitar uma nova imagem a seu cliente.
422	RESOLUTION_IMAGE_INVALID	The image must be in the HD standard or have a resolution greater than 640x480.	É preciso que a imagem possua padrão HD e possua resolução maior que 640x480.
422	PROCESS_ID_EXPIRED	The processId provided has expired. Make sure the SELFIE has been submitted and approved.	O identificador da selfie de nosso banco de dados está expirado. É necessário enviar uma nova selfie por meio do processo de Onboarding.
422	FACE_MUST_BE_CENTERED	The face must be centered in the capture area. Please try send another image.	Peça a seu cliente a manter o rosto centralizado na área de captura da imagem.
422	FACE_MUST_BE_CLOSER	The face must be closer to the camera. Please try send another image.	Instrua seu cliente a manter o rosto mais próximo da câmera no momento da captura da imagem.
422	FACE_MUST_BE_AWAY	The face must be further away from the camera. Please try send another image.	Solicite a seu cliente a manter o rosto mais distante da câmera no momento da captura da imagem.
422	BAD_LIGHTING	Bad lighting! Make sure the environment is not too dark and that the camera is not pointed against a light source. Please try send another image.	A iluminação do ambiente apresenta problemas. Peça a seu cliente que se certifique de que o ambiente não está escuro e nem com excesso de luz.
422	IMAGE_BLURRED_OR_OUT_OF_FOCUS	Image blurred or out of focus! Please try send another image.	A imagem está fora de foco. Solicite a seu cliente uma nova imagem.
422	TILTED_FACE	Tilted face! The face must be straight and looking at the camera. Please try send another image.	O rosto está inclinado. Instrua seu cliente a manter a face reta, olhando para a câmera.
422	SIDE_FACE	Side face! The face must be straight and looking at the camera. Please try send another image.	O cliente enviou uma foto do perfil de seu rosto. Instrua seu cliente a manter a face reta, olhando para a câmera.
422	IMAGE_HAS_NO_LIVE	It is not possible to identify if it is a live image. Assess the risk of registration before a new attempt.	Não é possível identificar prova de vida na imagem enviada. Avalie o risco antes de solicitar uma nova imagem a seu cliente.
422	WITHOUT_GLASSES	The selfie must be taken without glasses. Please try send another image.	Solicite a seu cliente que retire os óculos antes da captura da imagem.
422	IMAGE_BLURRED	Image blurred or out of focus. Please try send another image.	Instrua seu cliente a atentar-se ao foco no momento da captura da imagem.
422	JWT_REFUSED	Jwt refused. Please, try send another jwt.	O JWT foi recusado. É preciso enviar um novo.

Recordamos que esta API também poderá retornar erros comuns entre todos os endpoints. Portanto, recomendamos a consulta da documentação de erros, onde é possível encontrar as mensagens comuns em inglês que acompanham os erros 400 (se houver).

Eventos

Caso o parceiro deseje receber mensagens referentes aos eventos relacionados a esse endpoint, é preciso configurar o webhook. Os eventos são:

Nome do evento	Descrição
`ID_TOKEN_WAS_CREATED`	Token criado.
`ID_TOKEN_WAS_REFUSED`	Não foi possível gerar um token.
`ID_TOKEN_WAS_EXPIRED`	O tempo para criação do token expirou.

Solicitação de novo token

Pré-requisito

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧
Importante

Resposta (Response)

👍
Dica

Erros

Eventos

Pré-requisito

Requisição (Request)

Requisição HTTP

Autorização

Cabeçalhos (Headers)

Parâmetros da rota (Path)

Corpo da requisição (Body)

🚧Importante

Resposta (Response)

👍Dica

Erros

Eventos

🚧
Importante

👍
Dica