Enviar cartas

Una carta se configura una vez en Avisos y decide qué espera; el envío manda solo eso. Hay una sola llamada para todos los casos:

POST /api/integraciones/v1/cartas/{nombre}/enviar

Qué lleva el cuerpo lo dice el contrato de la carta (GET /cartas/{nombre}, ver Conectar un sistema). Estas son las formas.

Una carta con su propia audiencia

Una carta a un grupo de la agenda, a unas personas o a quien ha escrito por un canal ya sabe a quién va. El envío trae solo sus datos:

{ "datos": { "alerta": "Se cayó el nodo 3" }, "id_envio": "INC000123-caida" }

Mandarle una lista responde 422 carta_con_audiencia: la audiencia es de la carta.

Una carta cuya lista trae quien la envía

Es la audiencia La lista la trae quien la envía. La lista va en para, y cada destinatario es una de tres cosas:

Destinatario	Cómo se escribe	Por dónde le llega
Una persona de la agenda	"P-7K2M9Q" o {"persona": "P-7K2M9Q"}	Su canal principal.
Un grupo de la agenda	{"grupo": "Gerentes de soporte"}	El canal principal de cada uno.
Una dirección	{"canal": "WhatsApp de citas", "identificador": "573001XXXXXX"}	Ese canal.

{
  "para": [
    "P-7K2M9Q",
    { "grupo": "Gerentes de soporte" },
    { "canal": "WhatsApp de citas", "identificador": "573001XXXXXX" }
  ],
  "datos": { "alerta": "Se cayó el nodo 3" }
}

• Una dirección sin canal solo vale si la carta sale por un único canal. Con varios, esa fila no sale y la respuesta dice por qué: ELYRA no adivina de qué canal es un número.
• El canal se escribe con su nombre en Conexiones (o su id), y tiene que ser uno de los que la carta permite.
• Nadie recibe dos veces: la misma dirección por el mismo canal, o una persona que está en el grupo y además en la lista, sale una vez.
• solo_por obliga a personas y grupos a recibir por un canal concreto en vez de su principal: "solo_por": "Correo de la mesa".

Datos distintos para cada destinatario

datos vale para todos; el de cada destinatario manda sobre él. Con eso cada uno recibe su mensaje:

{
  "para": [
    { "persona": "P-7K2M9Q", "datos": { "nombre": "Ana", "fecha": "15/10/2026" } },
    { "canal": "Telegram de citas", "identificador": "@luis_g",
      "datos": { "nombre": "Luis", "fecha": "16/10/2026" } }
  ],
  "datos": { "sede": "Sede Norte" }
}

Con la lista en un archivo

El mismo Excel o CSV que se sube en el portal, con sus columnas identificador, canal y los datos del mensaje (la plantilla de la carta está en GET /cartas/{nombre}/plantilla). Tres formas de mandarlo:

Subido (multipart)

curl -s -X POST "https://tu-empresa.onelyra.com/api/integraciones/v1/cartas/Recordatorio%20de%20citas/enviar" \
  -H "Authorization: Bearer $CREDENCIAL" \
  -F "archivo=@citas-15-oct.csv" \
  -F "id_envio=citas-2026-10-15"

Los demás campos van como campos del formulario; datos y para, como JSON en su campo.

En el JSON (base64)

{
  "archivo": { "nombre": "citas.csv", "datos": "aWRlbnRpZmljYWRvcixjYW5hbCxmZWNoYQo…" },
  "id_envio": "citas-2026-10-15"
}

Para sistemas que solo saben hablar JSON.

Por su dirección

{ "archivo_url": "https://archivos.tu-empresa.com/export/citas.csv" }

Solo https, y una dirección alcanzable desde internet: la red interna de la empresa no se alcanza por aquí.

Para una fecha y una hora

Si la carta tiene el cuándo Cuando lo diga quien la dispare, el envío lo trae, en ISO 8601 y con su zona horaria:

{ "para": ["P-7K2M9Q"], "datos": { "alerta": "Mantenimiento" },
  "cuando": "2026-10-15T22:00:00-05:00" }

Cada mensaje se prepara al enviar y se entrega a esa hora. Una fecha pasada (cuando_pasado), un cuando a una carta que decide el suyo (cuando_no_aceptado), o una carta que lo espera y no lo recibe (cuando_falta), responden 422 con su código.

Revisar sin enviar

"solo_revisar": true devuelve la misma cuenta que un envío —quién sale, quién puede no salir, quién no y por qué— y no envía nada. Sirve para probar la integración y para validar una lista antes de mandarla.

La respuesta y cómo va el envío

Un envío aceptado responde 202:

{
  "envio_id": "9b2f1c4e-0d1a-4c7e-9f5b-2a6d8e3c1b70",
  "estado": "corriendo",
  "cuenta": { "filas": 3, "listas": 2, "sin_ventana": 0, "errores": 1 },
  "filas": [
    { "n": 1, "identificador": "2001", "canal": "Telegram de soporte", "estado": "lista" },
    { "n": 2, "identificador": "573001XXXXXX", "canal": "WhatsApp de soporte", "estado": "lista" },
    { "n": 3, "identificador": "", "canal": "", "estado": "error",
      "motivo": "No hay ninguna persona «P-ZZZZZZ»." }
  ]
}

En cuenta	Qué es
listas	Salen.
sin_ventana	Pueden no salir: el canal no deja escribirles primero ahora (WhatsApp fuera de su ventana). Se intenta; si sigue cerrado, quedan como «no salió» con su motivo.
errores	No salen; cada fila dice por qué.

El envío corre en segundo plano, por tandas. Cómo va:

GET /api/integraciones/v1/envios/{envio_id}

Devuelve el estado (corriendo, terminado, parado, detenido) y el resultado de cada destinatario: entregado, en espera, programado, o el motivo por el que no salió. El mismo envío se ve, y se puede parar, en Actividad › Lotes.

Relacionado: Errores, reintentos y duplicados · Referencia interactiva · A quién le llega una carta.