Geração do hash e do código numérico

stable

Este endpoint permite gerar um hash e um código numérico para realizar a validação TOTP.

📘

Nota

Recordamos que o parceiro enviará apenas o código numérico a seu cliente via mensagem (e-mail ou SMS, por exemplo) e deverá armazenar o hash para posterior validação.

Pré-requisito

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

• O parceiro possua um cadastro ativo e aprovado no Bankly.

Requisição

Requisição HTTP

HTTP

POST 'https://api-mtls.sandbox.bankly.com.br/totp

cURL

curl --request POST \ 
			--url 'https://api-mtls.sandbox.bankly.com.br/totp' \ 
			--header 'api-version: 1.0' \ 
			--header 'Content-Type: application/json' \ 
			--header 'Accept: application/json' \ 
			--header 'x-bkly-user-id: {{document_number}}' \ 
			--header 'Authorization: Bearer {{access_token}} \ 
			--data-raw '{ 
			    "context": "Pix", 
			    "operation": "RegisterEntry", 
			    "data": { 
			        "addressingKey": { 
			            "type": "PHONE", 
			            "value": "[phone]" 
			        } 
			    } 
			}'

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
totp.create	Concede acesso para gerar um hash e um código numérico para validação TOTP.

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-bkly-user-id	Obrigatório. Número do documento do cliente que faz a requisição. Insira apenas números, sem formatação (11 dígitos para CPF e 14 para CNPJ).

Parâmetros da rota (Path)

Não é necessário enviar parâmetros no path desta requisição.

Corpo da requisição (Body)

No body, envie os seguintes campos em formato JSON:

Nome	Tipo	Descrição
context	string	Obrigatório. Contexto de uso do TOTP. Exemplo: “Pix”.
operation	string	Obrigatório. Finalidade da geração do TOTP: “Portability” (portabilidade), “Ownership” (reivindicação) e “RegisterEntry” (cadastro de chaves).
data	object	Obrigatório. Campo dinâmico para que o parceiro insira as informações necessárias a serem enviadas, de acordo com a operação (operation), conforme detalhado na tabela a seguir.

Operação	Conteúdo do data	Tipo	Descrição
RegisterEntry	addressingKey	object	Objeto que deverá conter os dados da chave de endereçamento: type (“PHONE” ou “EMAIL”) e value (número do telefone ou endereço do e-mail).
Portability e Ownership	claimId	string	Informe o valor retornado ao requisitar a portabilidade de uma chave ou reivindicar sua posse.

🚧

Importante

É preciso realizar uma conexão entre o hash gerado e a operação na qual ele será utilizado. Portanto, se o campo data não trouxer as informações referentes à operação que utilizará o hash, não será possível usar o TOTP gerado.

Cadastro de chave

{ 
    "context": "Pix", 
    "operation": "RegisterEntry", 
    "data": { 
        "addressingKey": { 
            "type": "PHONE", 
            "value": "[phone]" 
        } 
    } 
}

Portabilidade de chave

{ 
  "context": "Pix", 
  "operation": "Portability", 
  "data": { 
      "claimId": "{{claim_id}}" 
  } 
}

Posse de chave

{ 
  "context": "Pix", 
  "operation": "Ownership", 
  "data": { 
      "claimId": "{{claim_id}}" 
  } 
}

Resposta (Response)

O status code 201 indicará sucesso na requisição.
Sendo bem-sucedido, o retorno irá trazer os seguintes campos em formato JSON:

Nome	Tipo	Descrição
hash	string	Código criptografado que o parceiro deverá armazenar para posterior validação.
code	string	Código numérico que o parceiro deverá enviar a seu cliente.

JSON

{ 
    "hash": "6c1f6497d8d3bddf02649f8cb34e9e90b916a59e502116c49fcfeef55fc7a8c8", 
    "code": "618467" 
}

Após receber o hash e o código retornados, é necessário que a aplicação do parceiro os envie para o seu cliente para que seja realizada a validação.

O envio pode ser feito via e-mail, no caso de chaves desse tipo, ou SMS, caso a chave seja o número de telefone.

📘

Nota

O parceiro pode utilizar o provedor de e-mail ou SMS que preferir para fazer a validação de TOTP com o seu usuário.

👍

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	Descrição
400	INVALID_PARAMETER	Campo não informado ou informado com valor inválido.
400	INVALID_USER_ID	O header x-bkly-user-id não foi informado ou ele contém um documento inválido.

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

Este endpoint não possui eventos relacionados a ele.