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": "ID_CLOUD"
}'

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 do 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. Neste caso, "ID_CLOUD".
`tll`	`int`	Tempo de vida do token, que é de, no máximo, 900 segundos.

{
	"challenge": "DEVICE_VERIFICATION",
	"claims": {
		"deviceHash": "9b0c0dfa48ae46923769e5329f1acb72dfb030bfab761cbeeaf8d04b7be6b384"
	},
	"ttl": 900,
	"provider": "ID_CLOUD"
}

🚧
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 200 indicará que foi criado o processo com sucesso.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
`userRedirectUrl`	`string`	Url para realizar o processo de biometria com webview.
`expiresAt`	`string`	Prazo de expiração da URL para criação do processo.

{
  "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
  "expiresAt": "2023-10-09T15:15:25.417105Z"
}

👍
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.

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.

🚧
Para solicitação de novo token
O token deverá ser obtido através dos eventos que são enviados no webhook do parceiro.