====== Fábrica - Servicios Web - Integraciones - AdaEmailService ======
Este servicio permite el envío de correos electrónicos. Actualmente soporta los siguientes servidores de correo:
* Ionos
* Gmail*
* Outlook
//*Requiere generación de clave de aplicaciones//
===== Nueva Implementación =====
Se adiciona soporte API MailerSend para envios masivos por medio de tokens de autorización. Favor ver [[#Liberación Versión 2.0.0 Correos Masivos|Versión 2.0.0]] para más información. A partir de la fecha 05/06/2023 la versión 1.0.0 queda obsoleta y no debe ser utilizada para procesos de producción((Se prevee eliminar el soporte de esa versión en liberaciones posteriores)).
===== Descripción del Servicio =====
^Nombre^Descripción^Tipo Servicio^Tecnología^Lenguaje^Tipo Desarrollo^Versión Desarrollo^Archivo de Configuración^
|AdaEmailServie|Permite el envío de correos electrónicos.|Rest|SpringBoot 2.7.6|Java 11.0.315|Nuevo|11.6.0.1|application.properties|
^Tipo Empaquetado^Gestor de Dependencias^Servidor de Despliegue^IDE Proyecto^Tipo Repositorio^Url Desarrollo^Url Calidad^Url Producción^
|war|Maven 3.8.1|WildFly 20|SpringTools 4.16.1|Subversión|[[http://adacsc.co:1443/svn/repository/ADA/SICOFERP/fuentes/branches/development/core/Microservicios/AdaEmailService
|SVN branches]]|[[http://adacsc.co:1443/svn/repository/ADA/SICOFERP/fuentes/trunk/development/core/Microservicios/AdaEmailService
|SVN trunk]]|[[|SVN tags]]|
^Dependencias^^^^^^^^
^groupId^artifactId^^version^scope^optional^Descripción^^
|org.springframework.boot|spring-boot-starter-data-rest||N/A|N/A|N/A|API de mapeo de rutas||
|org.springframework.boot|spring-boot-starter-web||N/A|N/A|N/A|Core Servicios Web||
|org.springframework.boot|spring-boot-devtools||N/A|runtime|true|Recarga de aplicaciones||
|org.projectlombok|lombok||N/A|N/A|true|API de anotaciones para reducción de código||
|org.springframework.boot|spring-boot-starter-test||N/A|test|N/A|Core Springboot||
|org.postgresql|webjars-locator-jboss-vfs||0.1.0|N/A|N/A|Plugins para despliegue en Wildfly||
|org.springframework.boot|spring-boot-starter-tomcat||N/A|provided|N/A|Servidor Embebido Tomcat||
|org.apache.maven.plugins|maven-compiler-plugin||3.8.1|N/A|N/A|Gestor de dependencias||
|org.springdoc|springdoc-openapi-ui||1.5.12|N/A|N/A|Plugins para generar documentación Swagger||
|org.springframework.boot|spring-boot-starter||N/A|N/A|N/A|Core Springboot||
|com.sun.mail|javax.mail||1.6.2|N/A|N/A|Envío de correos||
|org.freemarker|freemarker||N/A|N/A|N/A|Plantillas de Texto||
|com.mailersend|java-sdk||1.0.0|N/A|N/A|Envío de correos por medio del API MailerSend||
^Documentación Operaciones^^^^^^^^
^Tipo^Documentación^^^^^^Visor^
|Swagger|[[https://factory-ws-utilities17.adacsc.co/AdaEmailService/v3/api-docs|Ver Documento Json]]||||||https://editor.swagger.io/|
|Javadoc|[[http://adacsc.co:1443/svn/repository/ADA/SICOFERP/fuentes/branches/development/core/Microservicios/AdaEmailService/doc|Directorio Javadoc]]||||||Navegador Web|
^Ambientes de Despliegue^^^^^^^^
^Tipo^Url^^Observaciones^^^^^
|Desarrollo:|http://localhost:8080||Ambiente de desarrollo|||||
|Calidad:|http://srv-appeon-000-w23.adacsc.co/AdaEmailService||Ambiente de validación|||||
|Producción:|https://factory-ws-utilities17.adacsc.co/AdaEmailService||Ambiente de producción|||||
===== Información Adicional =====
===== Despliegue =====
==== Requisitos Técnicos Servidor ====
* Servidor Wildlfy 20 o superior
* Java 11 o OpenJDK 11
* S.O. Linux
* Ram 4GB o superior
* Disco Duro 64 GB
* Publicar la URL y Puerto del WildFly
=== Notas ===
* URL Base Local - Index: http://localhost:8088
* URL Base QA - Index: http://srv-appeon-000-w23.adacsc.co/AdaEmailService
* URL Base Producción - Index: https://factory-ws-utilities17.adacsc.co/AdaEmailService
===== Ejemplos de envio de correos =====
==== Envio servidor Ionos ====
Esta versión esta Obsoleta. Por favor utilice la [[#Liberación Versión 2.0.0 Correos Masivos|Versión 2.0.0]]
//URL: email/v1/send
{
"smtpHost": "smtp.ionos.com",
"smtpPort": 587,
"smtpAuth": "true",
"smtpMailUser": "email.test@ada.co",
"smtpMailPassword": "password",
"smtpStartTlsEnabled": false,
"smtpSessionDebug": true,
"subject": "Título de Prueba",
"content": "Contenido de prueba",
"html": false,
"toEmail": [
{
"address": "notififacionTo.test@ada.co",
"persona": "Notificación To"
}
],
"ccEmail": [
{
"address": "notififacionCc.test@ada.co",
"persona": "Notificación Cc"
}
],
"bccEmail": [
{
"address": "notififacionBcc.test@ada.co",
"persona": "Notificación Bcc"
}
]
}
==== Envio servidor Outlook ====
Esta versión esta Obsoleta. Por favor utilice la [[#Liberación Versión 2.0.0 Correos Masivos|Versión 2.0.0]]
//URL: email/v1/send
{
"smtpHost": "smtp.outlook.com",
"smtpPort": 587,
"smtpAuth": "true",
"smtpMailUser": "correo",
"smtpMailPassword": "password",
"smtpStartTlsEnabled": true,
"smtpSessionDebug": true,
"subject": "Prueba",
"content": "Ejemplo",
"html": false,
"toEmail": [
{
"address": "correo",
"persona": "persona"
}
],
"ccEmail": [
{
"address": "correo copia",
"persona": "Persona Copia"
}
],
"bccEmail": [
{
"address": "Correo copia oculta",
"persona": "Persona copia oculta"
}
]
}
==== Envio servidor Gmail ====
Esta versión esta Obsoleta. Por favor utilice la [[#Liberación Versión 2.0.0 Correos Masivos|Versión 2.0.0]]
//URL: email/v1/send
{
"smtpHost": "smtp.gmail.com",
"smtpPort": 587,
"smtpAuth": "true",
"smtpMailUser": "correo",
"smtpMailPassword": "clave aplicacion",
"smtpStartTlsEnabled": true,
"smtpSessionDebug": true,
"subject": "Prueba",
"content": "Ejemplo",
"html": false,
"toEmail": [
{
"address": "Correo",
"persona": "Persona"
}
],
"ccEmail": [
{
"address": "Correo copia",
"persona": "Persona copia"
}
],
"bccEmail": [
{
"address": "Correo copia oculta",
"persona": "Persona copia oculta"
}
]
}
===== Liberación Versión 2.0.0 Correos Masivos =====
Se libera versión con soporte de envios masivos sin necesidad de servidor SMTP utilizando el API de envios masivos [[https://app.mailersend.com/|MailerSend]].
==== Documentación Técnica Javadoc ====
Se libera la documentación técnica javadoc la cual puede ser consultada desde la carpeta de documentación del proyecto en la ruta del [[http://adacsc.co:1443/svn/repository/ADA/SICOFERP/fuentes/branches/development/core/Microservicios/AdaEmailService/doc|SVN]]
=== Nota ===
Debe descargar el proyecto para visualizar la documentación.
==== Documentación Técnica OpenAPI ====
Se libera documentación OpenAPI V3 la cual se comparte a continuación y puede ser visualizada en el [[https://editor.swagger.io/|visor swagger]]
=== Nota ===
Copie el siguiente texto en formato JSON y peguelo en el panel izquierdo del visor [[https://editor.swagger.io/|visor swagger]]
{
"openapi": "3.0.1",
"info": {
"title": "OpenAPI definition",
"version": "v0"
},
"servers": [
{
"url": "http://factory-ws-utilities17.adacsc.co/AdaEmailService",
"description": "Generated server url"
}
],
"tags": [
{
"name": "EmailController",
"description": "Controlador que gestiona los envíos de correos electrónicos en las aplicaciones."
}
],
"paths": {
"/email/v2/send": {
"post": {
"tags": [
"EmailController"
],
"summary": "send",
"description": "Envía correos electrónicos utilizando el API de envio masivo MailerSend.",
"operationId": "send",
"parameters": [
{
"name": "token",
"in": "header",
"description": "Token API utilizado para realiza el envío. Si no se especifica se utiliza uno genérico.",
"required": false,
"schema": {
"type": "string"
},
"example": "eyFDSFDSF4%$#%$#%VFDvcxvkxkvljxkljelkrjklcjvklcxjvklxjv"
},
{
"name": "emailDto",
"in": "query",
"description": "Objeto con la configuración del envio y contenido del correo electrónico que será enviado",
"required": true,
"schema": {
"$ref": "#/components/schemas/EmailDto"
}
}
],
"responses": {
"500": {
"description": "Se han generado inconsistencias al crear el registro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
},
"202": {
"description": "Correo electrónico enviado correctamente.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
},
"503": {
"description": "No se puede enviar el correo electrónico.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
}
}
}
},
"/email/v1/send": {
"post": {
"tags": [
"EmailController"
],
"summary": "send",
"description": "Envía correos electrónicos.",
"operationId": "send_1",
"parameters": [
{
"name": "emailConfigDto",
"in": "query",
"description": "Objeto con la configuración del envio y contenido del correo electrónico que será enviado",
"required": true,
"schema": {
"$ref": "#/components/schemas/EmailConfigDto"
},
"example": {
"smtpHost": "smtp.ionos.com",
"smtpPort": 587,
"smtpAuth": "true",
"smtpMailUser": "email.test@ada.co",
"smtpMailPassword": "password",
"smtpStartTlsEnabled": false,
"smtpSessionDebug": true,
"subject": "Título de Prueba",
"content": "Contenido de prueba",
"html": false,
"toEmail": [
{
"address": "notififacionTo.test@ada.co",
"persona": "Notificación To"
}
],
"ccEmail": [
{
"address": "notififacionCc.test@ada.co",
"persona": "Notificación Cc"
}
],
"bccEmail": [
{
"address": "notififacionBcc.test@ada.co",
"persona": "Notificación Bcc"
}
]
}
}
],
"responses": {
"500": {
"description": "Se han generado inconsistencias al crear el registro.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
},
"202": {
"description": "Correo electrónico enviado correctamente.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
},
"503": {
"description": "No se puede enviar el correo electrónico.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GenericResponseDto"
}
}
}
}
},
"deprecated": true
}
},
"/email/": {
"get": {
"tags": [
"EmailController"
],
"summary": "index",
"description": "Método de validación de estado del microservicio",
"operationId": "index",
"responses": {
"200": {
"description": "Microsericio en linea",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailController"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AddressConfigDto": {
"type": "object",
"properties": {
"address": {
"type": "string"
},
"persona": {
"type": "string"
}
},
"description": "Clase Dto que contiene la configuración de la dirección de correo electronico."
},
"AttachmentConfigDto": {
"type": "object",
"properties": {
"fileName": {
"type": "string"
},
"fileContentStringBase64": {
"type": "string"
},
"typeContent": {
"type": "string"
}
},
"description": "Clase Dto que contiene la configuración del archivo que se adjuntará al correo electrónico."
},
"EmailDto": {
"type": "object",
"properties": {
"from": {
"$ref": "#/components/schemas/AddressConfigDto"
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"html": {
"type": "boolean"
},
"attachmentBase64": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentConfigDto"
}
},
"toEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
},
"ccEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
},
"bccEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
}
},
"description": "Clase Dto que contiene la configuración e información del correo electrónico."
},
"GenericResponseDto": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int64"
},
"message": {
"type": "string"
},
"content": {
"type": "object"
}
},
"description": "Dto generico utilizado para respuestas en servicios."
},
"EmailConfigDto": {
"type": "object",
"properties": {
"smtpHost": {
"type": "string"
},
"smtpPort": {
"type": "string"
},
"smtpAuth": {
"type": "string"
},
"smtpMailUser": {
"type": "string"
},
"smtpMailPassword": {
"type": "string"
},
"smtpStartTlsEnabled": {
"type": "string"
},
"smtpSslTrust": {
"type": "string"
},
"smtpSessionDebug": {
"type": "boolean"
},
"subject": {
"type": "string"
},
"content": {
"type": "string"
},
"html": {
"type": "boolean"
},
"attachmentBase64": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AttachmentConfigDto"
}
},
"toEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
},
"ccEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
},
"bccEmail": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressConfigDto"
}
}
},
"description": "Clase Dto que contiene las configuraciones de autenticación y envío del correo electrónico."
},
"EmailController": {
"type": "object"
}
}
}
}
==== Ejemplo de Consumo ====
El siguiente es un ejemplo de consumo del nuevo servicio. Los parametros de consumo se describen como se configurarían en un cliente Rest como Postman.
//Http: POST
//URL: https://factory-ws-utilities17.adacsc.co/AdaEmailService/email/v2/send
//Header: token = Token API utilizado para realiza el envío. Si no se especifica se utiliza uno genérico.
//Parametro en el Body: Ver el json a continuación
{
"from": {
"address": "dirección de correo de origen",
"persona": "Nombre de la cuenta de origen"
},
"subject": "Asunto del correo",
"content": "Contenido del correo, puede ser un bloque html o texto plano",
"html": true,
"attachmentBase64": [
{
"fileName": "Nombre del archivo con extensión",
"fileContentStringBase64": "Contenido del archivo en Base64",
"typeContent": "Mime type del archivo Ej: Para un PDF sería application/pdf"
}
],
"toEmail": [
{
"address": "Correo de destino",
"persona": "Nombre asociado al correo de destino."
}
],
"ccEmail": [
{
"address": "Correo de copia",
"persona": "Nombre asociado al correo de copia."
}
],
"bccEmail": [
{
"address": "Correo de copia oculta",
"persona": "Nombre asociado al correo de copoa oculta."
}
]
}
==== Ejemplo de Respuesta exitosa de Consumo ====
{
"code": 1,
"message": "Correo electronico enviado correctamente: ID 647a19cc646885576c0b2524",
"content": null
}
==== Consideraciones ====
A partir de al fecha el componente está publicado y disponible para envios de correos. Favor tener presente las siguientes consideraciones para el correcto uso del componente.
* Cada aplicación que requiera el uso del envio de correo debe solicitar a TI la generación de un token de autorización con el cual se puede consumir el servicio. De esta forma se puede hacer seguimiento.
* El correo puede hacer envios masivos pero por control el máximo de envio se establece a 100 por correo.
* El API soporta un maximo de 10 correos para copias.
* El API soporta un maximo de 10 correos para copias ocultas.
* Los archivos adjuntos se deben enviar en String Base64
[[ada:howto:sicoferp:factory:integrations|←Volver atrás]]