Linha Datasul

Árvore de páginas


Pré Requisitos

  • TOTVS 12 com versão 12.1.15 ou superior;
  • Comunicação com o AppServer ativa e funcional para o resgate das informações 'base' para o envio de e-mail;
  • Servidor de e-mails com suporte a SMTP e uma conta válida para envio de e-mails.

Configurações Mínimas

Para utilização do serviço, algumas configurações são necessárias:

  • Inserir o trecho de código abaixo no arquivo "josso-agent-config.xml".
<partner-app>
	<context>/dts/datasul-mail</context>
</partner-app>


  • Configurar os parâmetros de localização e porta, interno e externo, do servidor de aplicação (JBoss) no programa 'Parâmetros Gerais Módulo Básico' (btb946aa), aba 'Servidor'. Para mais informações acesse Configurar Aba Servidor (BTB946AA).

  • Configurar os parâmetros para envio de e-mail utilizando o programa 'Parâmetros Email Foundation' (btb962zb).  Para mais informações acesse Parâmetros Email Foundation (BTB962ZB).

Mail Service

O Datasul Mail Service é um serviço que permite tanto aplicações Progress quanto HTML possam realizar envio de e-mails de forma simples.

Por se tratar de um serviço, a chamada para o envio do e-mail usando esta funcionalidade é realizada através de chamadas REST.

Exemplo da arquitetura do serviço:


Serviços Disponíveis

Através do contexto datasul-mail/resources existem 3 serviços disponíveis para envio de e-mails com as seguintes assinaturas:

@GET /help

Path: N/A.

Query: N/A.

Response: Retorna as propriedades do Mail Service (mail.smtp.sender, mail.smtp.auth, mail.smtp.user, mail.smtp.pass, mail.smtp.host, mail.smtp.port, mail.smtp.ssl.enable, mail.smtp.starttls.enable, mail.smtp.debug.enable).


EXEMPLO
http://<server>:8080/dts/datasul-mail/resources/help/


@POST /send: @Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN })

Este serviço recebe o e-mail e suas opções para envio. Não suporta anexos.

Path: N/A.

Query: N/A.

Body: JSON contendo a entidade Mail;

Response: Uma cópia da entidade Mail em formato JSON.


EXEMPLO
http://<server>:8080/dts/datasul-mail/resources/send/


@POST /send: @Consumes(MediaType.MULTIPART_FORM_DATA)

Este serviço recebe o e-mail e suas opções para envio. Suporta anexos.

Path: N/A.

Query: N/A.

Body: JSON contendo a entidade Mail;

Response: Uma cópia da entidade Mail em formato JSON.


EXEMPLO
http://<server>:8080/dts/datasul-mail/resources/send/



O objeto Mail, encaminhado no corpo das requisições, possui a seguinte estrutura:

  1. subject: (string) assunto do e-mail;
  2. content: (string) conteúdo do e-mail, podendo ser HTML;
  3. reply: (string) (opcional) endereço de e-mail que receberá a resposta do e-mail enviado;
  4. to: ([string]) lista contendo os endereços de destinatários;
  5. cc: ([string]) (opcional) lista contendo os endereços de destinatários a receberem a cópia do e-mail;
  6. bcc: ([string]) (opcional) lista contendo os endereços de destinatários a receberem a cópia oculta do e-mail;
  7. returnNotificationType: (integer) (opcional): indica como deve ser o retorno em caso do envio retornar alguma confirmação ou erro.
    1. 1. Retorna o e-mail completo;
    2. 2. Retorna apenas o cabeçalho (default). 
  8. deliveryNotification: (integer) (opcional): indica o tipo de notificação que o remetente gostaria de receber.
    1. -1. Nenhuma (defaul);
    2. 1. Ao entregar o e-mail ao destinatário;
    3. 2. Ao falhar na entrega ao destinatário;
    4. 4. Ao atrasar a entrega ao destinatário;
  9. readNotificationTo: (string) Em caso de leitura do e-mail, caso tenha sido informado um endereço válido para este atributo, este receberá uma notificação de que o e-mail foi lido;
  10. priority: (integer) (opcional): prioridade do e-mail:
    1. 1: Alta;
    2. 3: (default) Normal;
    3. 5: Baixa.



  • As mensagens de confirmação de entrega e falhas serão retornadas a caixa de e-mail do usuário que estiver sendo utilizado como sender pelo serviço de e-mail. Entretanto, quando informado um endereço de e-mail válido no atributo readNotificationTo, este receberá o e-mail de confirmação de leitura.


  • O envio de e-mail ocorre de forma assíncrona, desta forma os erros ou retornos de falhas do envio propriamente dito não são resgatados no momento da execução. Isso se deve ao fato de que o Datasul Mail Service delega ao servidor SMTP o envio da mensagem, sendo que este pode não efetuar o envio no momento em que for solicitado, variando de acordo com a sua fila de despachos e parametrizações.



Recursos Disponíveis

Para mais informações de quais são os recursos disponíveis quanto a esta opção de envio, consultar o link: Envio de E-mail Datasul.


API Progress

A API a ser utilizada no progress é a utapi019.p que está preparada para enviar e-mails de acordo com a configuração indicada no programa 'Parâmetros Email Foundation' (btb962zb).

Para mais informações sobre como utilizar a API utapi019 acesse Utilização de API de envio de e-mail.


EXEMPLO Progress: sendWithAttachment 
{utp\utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019. 

create tt-envio2.
assign tt-envio2.versao-integracao = 1
       tt-envio2.exchange    = NO
       tt-envio2.servidor    = 'smtp.totvs.com.br'
       tt-envio2.porta       = 587
       tt-envio2.destino     = "[email protected]"
       tt-envio2.remetente   = "[email protected]"
       tt-envio2.assunto     = "Datasul Mail Service"
       tt-envio2.mensagem    = "Hello from the other side !"
       tt-envio2.importancia = 2
       tt-envio2.log-enviada = NO
       tt-envio2.log-lida    = NO
       tt-envio2.acomp       = NO
       tt-envio2.formato     = 'html'.

CREATE tt-mensagem.
ASSIGN tt-mensagem.mensagem = tt-envio2.mensagem.

caso não sejam informados os campos da tabela tt-paramEmail2, serão utilizados as configurações dos parâmetros de email foundation */
CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 5
       tt-paramEmail2.mailUser = '<user_email>'
       tt-paramEmail2.mailPass = '<senha_email>'
       tt-paramEmail2.TLS      = NO
       tt-paramEmail2.SSL      = NO
       tt-paramEmail2.DEBUG    = YES. 


CREATE ttAttachment.
ASSIGN ttAttachment.fileName = '<nome_arquivo>'.

COPY-LOB FROM FILE ttAttachment.FILENAME TO ttAttachment.fileContent NO-CONVERT NO-ERROR.  /* caso esteja disponível apenas o binário do arquivo, basta atribui-lo ao campo ttAttachment.fileContent */

RUN pi-execute4 IN h-utapi019 (INPUT  Table tt-envio2,
    INPUT  Table tt-mensagem,
    INPUT  Table tt-paramEmail2,
    INPUT  TABLE ttAttachment,
    OUTPUT Table tt-erros).
if  return-value = "NOK" then do:
    for each tt-erros:
        disp tt-erros with 1 column width 300.
    end.                               
end.


API Javascript

Está é a API para utilização nos projetos utilizando THF e está disponível em forma de um serviço nomeado como 'MailService'. Para utilizá-lo, basta injetar o MailService no construtor do seu controller.

Sua principal função é realizar os envios de e-mail a partir de programas HTML, abstraindo a chamada REST (utilizando o Datasul Rest) para a API utapi019, que centraliza qualquer envio de e-mail, tornando a configuração de envio de e-mails única.


O MailService disponibiliza 2 métodos para realizar o envio de e-mail, contendo as seguintes assinaturas:



  1. send
    1. email: contendo o objeto Mail;
      1. reply: Remetente do e-mail;
      2. mailTo: Destinatário do e-mail;
      3. cc: Endereço de e-mail em cópia;
      4. subject: Assunto da mensagem;
      5. content: Conteúdo da mensagem.
    2. callback: função a ser chamada quando terminar o processo.



  1. sendWithAttachment
    1. email: contendo o objeto Mail;
      1. reply: Remetente do e-mail;
      2. mailTo: Destinatário do e-mail;
      3. cc: Endereço de e-mail em cópia;
      4. subject: Assunto da mensagem;
      5. content: Conteúdo da mensagem;
    2. files: anexo ou lista de arquivos anexos obtidos através do seletor de arquivos do navegador;
    3. callback: função a ser chamada quando terminar o processo;
    4. callbackProgress: função que devolve o '%' de progresso do envio dos anexos para o serviço, o evento retornado pelo server a entidade de Mail relacionada ao anexo;
    5. callbackError: função a ser chamada caso ocorra algum erro inesperado.



EXEMPLO JavaScript: send 
var controller;
controller = function ($rootScope, $scope, MailService) {
	this.sendEmail = funcion() {
		MailService.send({
			reply: "[email protected]",
		    mailTo: "[email protected]",
			cc: "[email protected]",
			subject: "Datasul Mail Service",
			content: "Hello from the other side !"
		}, function(result) {
			console.info(result);
		});
    };
};
controller.$inject = ['$rootScope', '$scope', 'MailService'];
EXEMPLO JavaScript: sendWithAttachment 
var controller;
controller = function ($rootScope, $scope, MailService) {
	this.onSelectFiles = function(selectedFiles) {
		if (angular.isDefined(selectedFiles)) {
			this.sendEmail(selectedFiles);
		}
	};
	this.sendEmail = funcion(files) {
		MailService.sendWithAttachment({
			reply: "[email protected]",
		    mailTo: "[email protected]",
			cc: "[email protected]",
			subject: "Datasul Mail Service",
			content: "Hello from the other side !"
		}, files, 
		function(result, mail) {
			console.info(result, mail);
		}, function(progress, evt, mail) {
			console.warn(progress, evt, mail);
		}, function(result, status, headers, config, email) {
			console.error(result, status, headers, config, email);
		});
    };
};
controller.$inject = ['$rootScope', '$scope', 'MailService'];
EXEMPLO HTML: sendWithAttachment 
<html>
	<head></head>
	<body>	
		<label class="btn btn-default pull-right"
    		   role="button"
	           for="file-input">
			Selecione os arquivos...
		</label>
		<span class="file-text"></span>
    	<input id="file-input"
        	type="file"
	        style="position:fixed;top:-999px;"
    	    ngf-select
        	ngf-change="controller.onSelectFiles($files);"
        	ngf-multiple="true"
            ngf-allow-dir="false"/>
	</body>
</html>