Conectar un sistema

Otro sistema puede pedirle a ELYRA que avise a la gente: que mande una carta ya configurada en Avisos —una alerta de caída, un recordatorio de cita, una campaña con su lista— o un mensaje suelto por un canal. ELYRA se encarga del canal (WhatsApp, Telegram, Teams, correo…), de la ventana de cada uno, de no repetir a nadie y de contar qué salió y qué no.

El sistema no configura nada de eso. Llama por el nombre de la carta y manda solo lo que ella pide: la lista, los datos del mensaje y, si toca, el momento.

El 1 y el 2 se hacen una vez, al montar la integración; el 3 y el 4, en cada envío.

Antes de empezar

Qué	Dónde
La dirección	La puerta de tu empresa, la misma del portal, con /api/integraciones/v1 detrás: https://tu-empresa.onelyra.com/api/integraciones/v1.
Una credencial para el sistema	En Conexiones › Integraciones › Nueva credencial, con las familias que necesite: envíos para mandar cartas y avisos, consultas para preguntar cómo está ELYRA. Una por sistema: así cada llamada dice quién la hizo, y revocarla corta solo a ese sistema. El secreto se ve una sola vez: La credencial.
La carta	En Avisos, configurada y encendida. El sistema la usa por su nombre.

Todo lo que está en esta sección es contrato: Lo que se garantiza.

La primera llamada, de punta a punta

Los dos pasos con una carta «Alerta de caída» que pide el dato alerta y sale a su propia audiencia. $CREDENCIAL es el secreto de la credencial (cs_…); también vale un token corto pedido con ella.

1 · Ver qué pide la carta

curl

curl -s "https://tu-empresa.onelyra.com/api/integraciones/v1/cartas/Alerta%20de%20caída" \
  -H "Authorization: Bearer $CREDENCIAL"

Python

import httpx

BASE = "https://tu-empresa.onelyra.com/api/integraciones/v1"
cabeceras = {"Authorization": "Bearer " + CREDENCIAL}   # del gestor de secretos

contrato = httpx.get(f"{BASE}/cartas/Alerta de caída", headers=cabeceras).json()
print(contrato["datos"], contrato["lista"]["la_trae_quien_envia"])

JavaScript

const BASE = "https://tu-empresa.onelyra.com/api/integraciones/v1";
const cabeceras = { Authorization: `Bearer ${CREDENCIAL}` }; // del gestor de secretos

const contrato = await (await fetch(
  `${BASE}/cartas/${encodeURIComponent("Alerta de caída")}`, { headers: cabeceras })).json();

La respuesta dice si la carta espera la lista con el envío, qué datos son obligatorios, si acepta un momento y trae un cuerpo de ejemplo listo para usar. Esta llamada se hace una vez, al montar la integración.

{
  "nombre": "Alerta de caída",
  "audiencia": "grupo",
  "lista": { "la_trae_quien_envia": false, "acepta": [], "canales": [], "un_canal": false },
  "datos": [{ "nombre": "alerta", "descripcion": "Qué se cayó", "obligatorio": true }],
  "cuando": { "acepta": false, "obligatorio": false, "de_la_carta": "Solo cuando la disparen" },
  "ejemplo": { "datos": { "alerta": "…" }, "id_envio": "un-id-tuyo-unico" }
}

2 · Enviarla

curl

curl -s -X POST "https://tu-empresa.onelyra.com/api/integraciones/v1/cartas/Alerta%20de%20caída/enviar" \
  -H "Authorization: Bearer $CREDENCIAL" -H "Content-Type: application/json" \
  -d '{"datos": {"alerta": "Se cayó el nodo 3"}, "id_envio": "INC000123-caida"}'

Python

r = httpx.post(f"{BASE}/cartas/Alerta de caída/enviar", headers=cabeceras, json={
    "datos": {"alerta": "Se cayó el nodo 3"}, "id_envio": "INC000123-caida"})
if r.status_code == 202:
    envio = r.json()
    print(envio["envio_id"], envio["cuenta"])
else:
    error = r.json()
    print(error["codigo"], error["detail"])   # se programa contra «codigo»

JavaScript

const r = await fetch(`${BASE}/cartas/${encodeURIComponent("Alerta de caída")}/enviar`, {
  method: "POST",
  headers: { ...cabeceras, "Content-Type": "application/json" },
  body: JSON.stringify({ datos: { alerta: "Se cayó el nodo 3" }, id_envio: "INC000123-caida" }),
});
const cuerpo = await r.json();
if (r.status === 202) console.log(cuerpo.envio_id, cuerpo.cuenta);
else console.log(cuerpo.codigo, cuerpo.detail); // se programa contra «codigo»

La respuesta es 202 con el envio_id y la cuenta de quién sale y quién no, cada uno con su motivo. El envío corre en segundo plano; cómo va se mira con GET /envios/{envio_id}. Toda respuesta lleva además X-Request-Id: es lo que se le manda a soporte si algo no cuadra.

Lo que sigue

• Lo que se garantiza: qué es contrato, cómo se versiona y qué cuenta como cambio que rompe.
• La credencial: las familias, la llave directa o el token corto, rotar y revocar.
• Errores, reintentos y duplicados: los códigos, cuáles se reintentan y cómo evitar duplicados.
• Enviar cartas: personas, grupos, listas, archivos y momentos.
• Referencia interactiva: cada llamada con su formulario, sus ejemplos y el código para copiar.