Conteúdo



01. Objetivo

O serviço permite a redefinição de senha de um usuário do produto Datasul, por meio de API, deste modo permitindo que aplicativos consigam solicitar a redefinição de senha. 


02. Configuração


A recuperação de senha deve estar ativa no produto.


DATASUL: É habilitada por meio da propriedade enable.recover.password. Para mais informações sobre a propriedade, acesse Documentação "datasul_framework.properties". 

DATASUL FOR THF: É habilitada nas Propriedades do Sistema. Para mais informações sobre a propriedade, acesse Segurança. 

Mensagem no DATASUL




Mensagem no DATASUL FOR THF



Verifique se os parâmetros de e-mail estão configurados e funcionais. O processo de redefinição de senha faz o uso do método de envio definido no produto.



DATASUL: Para mais informações sobre os parâmetros, acesse Parâmetros Email Foundation (BTB962ZB)

DATASUL FOR THF: Para mais informações sobre os parâmetros, acesse E-mail.

A mensagem não possui detalhes, por não receber detalhes de erro da api de envio de e-mail.



03. Como enviar código de acesso para o usuário


Para realizar o envio do código de acesso, utilize o serviço passwordReset existente no contexto totvs-login, seguindo as premissas: 

O método de requisição é do tipo POST 

Não possui autenticação na requisição.

Deve ser enviado o parâmetro email, contendo o e-mail do usuário do produto, que está solicitando o código de acesso.

O usuário relacionado ao e-mail:

  • Deve ser do tipo INTERNO.
  • O e-mail não pode estar associado a mais de um usuário válido.
  • Não pode estar bloqueado;
  • Não pode estar inativo;

  • Erros sem mensagens: Erro de sintaxe inválida, terá como retorno status 400 Bad Request. Exemplo: o parâmetro email errado (emaill) ou sem valor.

    Erros com mensagens: são retornadas no formato JSON.

Documentação da manutenção de usuário: Manutenção de Usuário (SEC000AA)

http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset?email=<E-MAIL_DO_USUÁRIO>



Ao executar o serviço com sucesso, o usuário receberá um e-mail contendo o código de acesso para redefinição de senha. 



O código de acesso deve ser encaminhado para o serviço de redefinição de senha. Para mais informações leia o conteúdo 04. Como redefinir a senha.

Código de acesso:

  • É anulado após o seu uso na redefinição de senha;
  • É válido por 10 minutos, após este tempo será considerado como inválido;

O template de e-mail pode ser modificado.

  • Para mais informações leia o conteúdo: 05. Como modificar o template do e-mail.

O código de acesso pode ser enviado juntamente com uma URL.

  • Para mais informações leia o conteúdo: 06. Como adicionar URL com o código de acesso no e-mail.



04. Como redefinir a senha


Para redefinir a senha, utilize o serviço passwordReset existente no contexto totvs-login, seguindo as premissas: 

O método de requisição é do tipo POST 

Não possui autenticação na requisição.

A autorização para redefinição de senha será por meio do código de acesso.

guid: É o código de acesso, que o usuário recebeu por e-mail;

newPassword: É a nova senha do usuário;

confirmNewPassword: É a confirmação da senha do usuário;

Exemplo:

Erros sem mensagens: Erro de sintaxe inválida, terá como retorno status 400 Bad Request. Exemplo: Corpo da requisição errada ou sem valor.

Erros com mensagens: são retornadas no formato JSON.

http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset



05. Como modificar o template do e-mail


A modificação do template do e-mail, ocorre por meio de uma chave referente ao template de e-mail parametrizado no produto. Deste modo o parâmetro keyTemplate deve ser enviado no serviço responsável pelo envio do código de acesso.   



http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset?email=<E-MAIL_DO_USUÁRIO>&keyTemplate=<CHAVE_DO_TEMPLATE> 




Gerenciamento de Templates


Neste momento, não existe uma interface gráfica para o gerenciamento de Templates;

  • Os Templates são utilizados especificamente para o processo de redefinição de senha.

A API para gerenciamento de templates requer autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul



Regras para desenvolvimento do template

O template deve ser criado em formato HTML;

O template não pode utilizar a tag <script>;

Deve ser criado um programa progress para retornar o Template HTML, neste programa deve existir a procedure pi-html tendo como parâmetro de entrada JsonObject e parâmetro de saída CHARACTER.

O parâmetro de entrada é do tipo JsonObject possuindo a estrutura:

{
  "guid": "Código de acesso do usuário",
  "cod_usuario": "Código do usuário",
  "nom_usuario": "Nome do usuário"
  "url": "Caso exista URL configurada no produto, será enviada juntamente com o código de acesso exemplo https://meu-endereco?guid=d4c3fad5-ef7a-838b-6c14-31d8786eb05c Para mais informações leia 06. Como adicionar URL com o código de acesso no e-mail",
}

O parâmetro de saída é do tipo CHARACTER, onde deve ser retornado o Template HTML.


USING Progress.Json.ObjectModel.*.

{include/i-prgvrs.i EXEMPLO 2.00.00.001 }

PROCEDURE pi-html:
    DEFINE INPUT   PARAMETER jsonIn    AS JsonObject NO-UNDO.
    DEFINE OUTPUT  PARAMETER htmlOut   AS CHARACTER  NO-UNDO.
	
	//Implementar Lógica para criar o retorno HTML    
END PROCEDURE.

Exemplo de programa retornando Template Html





Como criar um Template

O método de requisição é do tipo POST 

A requisição precisa ser autenticada.

key: Chave do template, não pode passar o limite de 20 caracteres. Exemplos: fnd_access_code, app_rh_access_code.

value: Campo contendo o programa reponsável pelo retorno do Template HTML.

{
  "key": "fnd_access_code",
  "value": "sec/exemplo.p"
}

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates



Como atualizar um Template

O método de requisição é do tipo PUT

A requisição precisa ser autenticada.

value: Campo contendo o programa reponsável pelo retorno do Template HTML.

{
  "value": "sec/exemplo.p"
}

Atentar para a chave do template na URL

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code



Como remover um Template

O método de requisição é do tipo DELETE

A requisição precisa ser autenticada.

Atentar para a chave do template na URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code



Como retornar um Template

O método de requisição é do tipo GET

A requisição precisa ser autenticada.

Atentar para a chave do template na URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates/fnd_access_code



Como retornar todos os Templates

O método de requisição é do tipo GET

A requisição precisa ser autenticada.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/templates



06. Como adicionar URL com o código de acesso no e-mail


Para adicionar uma URL com código de acesso no e-mail, deve ser adicionado o parâmetro keyUrl com a chave da URL parametrizada no produto.

O parâmetro keyUrl dever ser enviado no serviço responsável pelo envio do código de acesso.

http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset?email=<E-MAIL_DO_USUÁRIO>&keyUrl=<CHAVE_DA_URL> 


Observar o Link https://meu-endereco?guid=d4c3fad5-ef7a-838b-6c14-31d8786eb05c

A URL parametrizada no produto keyUrl=fnd_access_code, possui o valor "https://meu-endereco", deste modo o valor sendo existente será enviado o código de acesso por meio do parâmetro guid "guid=d4c3fad5-ef7a-838b-6c14-31d8786eb05c"




Gerenciamento de URLs

Neste momento, não existe uma interface gráfica para o gerenciamento de URLs;

  • As URLs são utilizadas especificamente para o processo de redefinição de senha.

A API para gerenciamento de URLs requer autenticação. Para mais informações sobre autenticação de API acesse a página Desenvolvimento de APIs para o produto Datasul



Como criar uma URL

O método de requisição é do tipo POST 

A requisição precisa ser autenticada.

key: Chave da URL, não pode passar o limite de 20 caracteres. Exemplos: fnd_access_code, app_rh_access_code

value: Campo contendo a URL

JSON

{
  "key": "fnd_access_code",
  "value": "https://meu-endereco"
}

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/urls



Como atualizar uma URL

O método de requisição é do tipo PUT

A requisição precisa ser autenticada.

value: Campo contendo a URL

JSON

{
  "value": "https://meu-endereco"
}

Atentar para a chave da URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/urls/fnd_access_code



Como remover uma URL

O método de requisição é do tipo DELETE

A requisição precisa ser autenticada.

Atentar para a chave da URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/urls/fnd_access_code



Como retornar uma URL

O método de requisição é do tipo GET

A requisição precisa ser autenticada.

Atentar para a chave da URL.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/urls/fnd_access_code



Como retornar todas as URLs

O método de requisição é do tipo GET

A requisição precisa ser autenticada.

http://<SERVIDOR>:<PORTA>/api/sec/v1/passwordReset/urls



07. Como modificar template e adicionar URL com o código de acesso no e-mail

Para modificar template e adicionar URL com o código de acesso no e-mail, os parâmetros keyUrl e keyTemplate devem ser enviados no serviço responsável pelo envio do código de acesso.

O parâmetro keyTemplate foi apresentado no conteúdo  05. Como modificar o template do e-mail.


O parâmetro keyUrl foi apresentado no conteúdo 06. Como adicionar URL com o código de acesso no e-mail.


http://<SERVIDOR>:<PORTA>/totvs-login/passwordReset?email=<E-MAIL_DO_USUÁRIO>&keyUrl=<CHAVE_DA_URL>&keyTemplate=<CHAVE_DO_TEMPLATE>


IMPORTANTE!

Disponível para releases 12.1.29 e superiores.