# Integraciones ## Para qué sirve Una **integración** es un destino al que Lymen puede mandar avisos. La conectás una sola vez acá y después la elegís en los [perfiles de alerta](https://lymen.app/docs/operacion/perfiles-de-alerta/), las [automatizaciones](https://lymen.app/docs/operacion/automatizaciones/) y los [flujos](https://lymen.app/docs/operacion/flujos/). Las claves y direcciones secretas **no se escriben en esta pantalla**: se guardan cifradas en el [Llavero](https://lymen.app/docs/operacion/llavero/) y acá solo las elegís. > **Importante:** las integraciones se construyeron siguiendo la documentación de cada servicio, pero en esta versión **no se probaron con cuentas reales de cada proveedor**. No te podemos garantizar que funcionen en tu entorno sin pasar por la prueba. Usá siempre el botón **Probar** antes de depender de una, y mantené una vía alternativa de aviso hasta confirmar que llega. ## Cuándo usarlo - Al instalar Lymen, para definir por dónde se entera tu equipo. - Cuando cambia el canal de la guardia (por ejemplo, pasan de email a Telegram). - Cuando querés que los incidentes graves abran un ticket automáticamente. ## Quién puede qué | Rol | Qué puede hacer | |---|---| | Administración | Conectar, editar, probar y eliminar integraciones. | | Sistemas | Ver lo conectado (solo lectura). | | Negocio | No ve la opción. | ## La pantalla Arriba, la sección **Disponibles** muestra una tarjeta por servicio con su estado. Abajo, **Conectadas** lista lo que ya creaste: nombre, tipo, destino, qué credencial usa y en cuántos perfiles, automatizaciones o flujos se usa. | Estado de la tarjeta | Significa | |---|---| | Listo para usar (Email) | El envío de correos está funcionando. | | Sin configurar (u otro motivo) | El envío de correos no está listo; el motivo se lee en la tarjeta. | | N conectados | Hay N canales activos de ese tipo. | | Apagado | Hay canales creados, pero todos apagados. | | Sin conectar | Todavía no creaste ninguno. | ## Cómo se conecta una integración, paso a paso 1. Si la integración usa un secreto (token, URL secreta, API token), **primero cargalo en el [Llavero](https://lymen.app/docs/operacion/llavero/)** con el tipo de credencial que se indica abajo. 2. Entrá a **Configuración › Integraciones** y tocá la tarjeta del servicio. 3. Poné un **nombre** y completá los datos (ver cada servicio). 4. Elegí la credencial del Llavero. 5. Tocá **Guardar** y después **Probar**. El botón Probar se habilita cuando no hay cambios sin guardar. 6. Elegí la integración en tus perfiles de alerta, automatizaciones o flujos. ## Campos comunes | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | Nombre | Cómo la ves en los perfiles y flujos. | Vacío | 3 a 80 caracteres | Se muestra en los selectores; usá algo claro ("Slack guardia"). | | Credencial | El secreto que usa. | Ninguna | Una credencial del Llavero del tipo que corresponde | El secreto nunca se muestra. Si la credencial se elimina, la integración falla. | | Activo | Si manda avisos. | Sí | Sí / No | **Apagado no manda avisos** (en Jira, no abre tickets). Los perfiles que la usan dejan de llegar por ahí sin avisar. | | Probar | Manda un mensaje de prueba. | — | Botón | Es un envío **real**: avisá al equipo. Muestra si salió o el motivo del error. | | Eliminar | Borra la integración. | — | Botón con confirmación | La credencial queda en el Llavero. Los perfiles, automatizaciones y flujos que la usaban dejan de poder avisar por ahí. Antes de eliminar, mirá "Lo usan". | Los intentos fallidos de envío se reintentan: Lymen hace un intento y hasta tres reintentos con espera creciente. ## Email **Para qué sirve:** avisos al correo de cada contacto y reportes por email. | Qué pide | Dónde se saca | |---|---| | El email de cada persona | Se carga en [Contactos](https://lymen.app/docs/operacion/contactos/). | | El envío de correos | Lo deja funcionando quien instala Lymen (servidor de correo saliente). Se ve como "Listo para usar" en la tarjeta. | No se conecta con un diálogo: la tarjeta solo informa el estado. Los correos los envía la automatización del sistema **Aviso por email** (ver [Automatizaciones](https://lymen.app/docs/operacion/automatizaciones/)). **Impacto:** el correo viaja por el servidor de tu organización; si ese servidor está caído, los avisos por email no salen. ## Telegram **Para qué sirve:** avisos por un bot, a cada contacto o a un grupo. | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | Token del bot | Permite mandar mensajes con tu bot. | Ninguno | Una credencial del Llavero de tipo **Token** o **Texto** | Quien tiene el token puede escribir como tu bot: guardalo solo en el Llavero. | | Chat fijo (opcional) | Un grupo donde avisar. | Vacío | Número (puede empezar con `-`, por ejemplo `-1001234567890`), hasta 21 caracteres | Con chat fijo, el canal se puede elegir como canal de un perfil y manda al grupo. **Sin chat fijo, sale por el chat de cada contacto** y solo sirve desde los contactos. Cuando el aviso es para un contacto con chat cargado, se usa el chat del contacto. | **Cómo se obtiene:** 1. En Telegram, creá un bot hablando con el bot oficial de bots de Telegram (BotFather). Te da un **token**: cargalo en el [Llavero](https://lymen.app/docs/operacion/llavero/). 2. Para un grupo: sumá el bot al grupo y obtené el número del chat del grupo. 3. Para personas: cada una le escribe `/start` al bot y su número de chat se carga en [Contactos](https://lymen.app/docs/operacion/contactos/). ## Slack **Para qué sirve:** mensajes en un canal de tu espacio de Slack. | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | URL del webhook de Slack | A qué canal de Slack llegan los mensajes. | Ninguna | Una credencial del Llavero de tipo **Texto** que contiene la URL (`https://hooks.slack.com/…`) | La URL es un secreto: quien la tiene puede escribir en ese canal. Acá nunca se muestra. | **Cómo se obtiene:** en tu espacio de Slack, creá un *Incoming Webhook* para el canal elegido, copiá su URL y guardala en el [Llavero](https://lymen.app/docs/operacion/llavero/) como credencial de tipo **Texto**. ## Microsoft Teams **Para qué sirve:** mensajes en un canal de Teams. | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | URL del webhook de Teams | A qué canal de Teams llegan los mensajes. | Ninguna | Una credencial del Llavero de tipo **Texto** con la URL | Es un secreto, como en Slack. | **Cómo se obtiene:** en Teams, creá un flujo de *Workflows* con el desencadenador **"Cuando se recibe una solicitud de webhook de Teams"**, copiá su URL y guardala en el [Llavero](https://lymen.app/docs/operacion/llavero/) como credencial de tipo **Texto**. ## Webhook **Para qué sirve:** que cada aviso llegue a un sistema propio (tu mesa de ayuda, un script, otra herramienta), con firma para comprobar que viene de Lymen. | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | URL | A dónde se manda cada aviso. | Vacía | Una dirección que empiece con `https://`. Con `http://` solo se permite hacia la red interna autorizada. | Cada aviso (con datos del incidente) sale hacia esa dirección: usala solo con un sistema tuyo y de confianza. | | Secreto de la firma (opcional) | Firmar cada mensaje. | Sin firma | Una credencial del Llavero de tipo **Texto** o **Token** | Sin firma, cualquiera que conozca la URL podría mandarte avisos falsos. **Recomendado.** | Cada aviso se manda por POST, con un cuerpo JSON y estos datos: | Campo del JSON | Qué es | |---|---| | `version`, `origen` | Versión del formato y el origen (`lymen`). | | `ts` | Fecha y hora del envío. | | `idempotencyKey` | Clave única del aviso, para ignorar repetidos. | | `evento` | Se abrió, sigue abierto, recordatorio, se cerró o prueba. | | `cliente`, `perfil`, `incidente`, `contacto` | Datos de quién y qué disparó el aviso. | | `asunto`, `texto`, `link` | El mensaje y el enlace al incidente. | | `datos` | Datos extra, cuando lo manda un flujo. | Con secreto, cada mensaje lleva en los encabezados `X-Lymen-Timestamp` y `X-Lymen-Firma`. La firma es `sha256=` seguido del HMAC-SHA256 en hexadecimal del texto `timestamp.cuerpo`, con tu secreto como clave. También se mandan `Idempotency-Key` y `X-Lymen-Evento`. El receptor debería verificar la firma y ignorar claves repetidas. **Qué esperar:** Lymen espera hasta 10 segundos una respuesta con código 2xx. No sigue redirecciones. Reintenta ante 408, 429 y errores 5xx; no reintenta otros errores. ## Jira **Para qué sirve:** abrir un **ticket por cada incidente** y comentarlo al cerrarse. | Campo | Para qué sirve | Valor por defecto | Valores válidos | Impacto | |---|---|---|---|---| | Sitio de Jira | Tu Jira Cloud. | Vacío | `https://tuempresa.atlassian.net` (la dirección termina en `.atlassian.net`) | Solo se admite Jira Cloud. | | Proyecto | Dónde se crean los tickets. | Vacío | La clave del proyecto (por ejemplo `OPS`): empieza con letra, hasta 20 caracteres; se guarda en mayúsculas | Una clave equivocada hace fallar la creación del ticket. | | Tipo de ticket | Qué tipo se crea. | Vacío | Como se llama en tu Jira (por ejemplo `Task`) | Si tu Jira no tiene ese tipo, falla. | | Prioridad (opcional) | Prioridad del ticket. | Sin prioridad | Como se llama en tu Jira (por ejemplo `High`) | Vacía: Jira usa la de su proyecto. | | Correo y API token | Con qué cuenta se crean. | Ninguna | Una credencial del Llavero de tipo **Usuario y clave**: el usuario es tu correo de Atlassian y la clave es el API token | Los tickets figuran como creados por esa cuenta. | **Cómo se obtiene:** en tu cuenta de Atlassian, creá un *API token*, y cargá en el [Llavero](https://lymen.app/docs/operacion/llavero/) una credencial **Usuario y clave** con tu correo y ese token. **Comportamiento:** se crea **un solo ticket por incidente**. Si el perfil de alerta tiene activado "Avisar también cuando se cierra", se agrega un comentario al cerrarse; **el ticket no se cierra solo**. En el detalle del incidente ves el ticket, su estado y un botón **Reintentar** si no se pudo crear. Para que abra tickets, elegí el canal de Jira en un [perfil de alerta](https://lymen.app/docs/operacion/perfiles-de-alerta/). ## Problemas comunes - **Probar falla.** Leé el mensaje de error: suele ser una URL vencida o mal copiada, un token incorrecto o falta de permisos. Recargá la credencial en el Llavero. - **No aparece la credencial en el desplegable.** No existe una del tipo correcto. Cargala en el Llavero (el diálogo tiene un enlace) y volvé. - **No puedo elegir Telegram en un perfil.** El canal no tiene chat fijo y no es para grupos; usá los contactos o agregá un chat fijo. - **El webhook rechaza los avisos.** Verificá la firma con el secreto correcto y que tu servidor responda en menos de 10 segundos. - **Jira no abre el ticket.** Revisá proyecto, tipo de ticket y que el usuario tenga permiso para crear en ese proyecto.