Alerta
La unidad de trabajo. Nace de un encargo y recorre un plan hasta terminar por entrega, desactivación o agotamiento.
Para integradores
Integrar alertas mediante API
Esta página explica los conceptos y el recorrido de una integración. No sustituye a la documentación técnica: sirve para valorar el encaje antes de entrar en detalle.
Vocabulario
Seis conceptos que conviene fijar
Casi toda la integración se explica con estos términos.
Plan
La secuencia ordenada de pasos que ejecuta la alerta, con su canal, sus destinatarios, sus reintentos, sus esperas y sus vueltas.
Encargo directo
El plan viaja en la propia llamada. Útil cuando depende de datos que solo conoce el sistema de origen.
Perfil
Un plan ya configurado con su código. La llamada solo lleva el código y el texto, y los destinatarios se resuelven desde las agendas vinculadas.
Intento
Cada ejecución de un envío por un canal, con su resultado, su error y su evidencia técnica si el proveedor la aporta.
Callback
La notificación webhook que Nura Alertas envía al sistema de origen cuando ocurre un evento relevante.
Autenticación
Una credencial por integración, con permisos por método
Descripción funcional. Los valores concretos no se publican y no aparecen en esta web.
Cómo se autentica
Cada integración usa el token de su credencial API en la llamada. El token se muestra una sola vez al crear la credencial y debe guardarse en ese momento.
Permisos por método
Cada credencial habilita individualmente los métodos que puede usar. Un método no habilitado responde con un error de autorización, y el intento queda registrado.
Ámbito
La credencial pertenece a un ámbito de cliente. Las alertas, los perfiles y las agendas a los que accede son los de ese ámbito y solo los de ese ámbito.
Revocación
Una credencial puede desactivarse sin afectar a las demás integraciones del mismo ámbito.
Recorrido
De la credencial a la primera alerta en producción
- 1
Crear la credencial
Desde la administración, con nombre propio para la integración, y guardar el token en el momento en que se muestra.
- 2
Habilitar los métodos
Solo los que la integración va a usar realmente. El resto se deja denegado.
- 3
Explorar la zona de pruebas
El integrador se acredita con su credencial y ve la lista de métodos permitidos, con su método HTTP, su ruta y su descripción.
- 4
Probar en vivo
Las pruebas se ejecutan contra la propia API con el mismo token, de modo que un permiso retirado se comporta igual que en producción.
- 5
Integrar el encargo
La aplicación encarga alertas directas o lanza perfiles según el caso, y guarda el identificador que devuelve el sistema.
- 6
Recibir el retorno
Si el encargo indica una dirección de callback, los eventos llegan allí. Si no, el estado se consulta cuando convenga.
Métodos
Qué se puede hacer desde una integración
Descripción a alto nivel. Las rutas exactas, los parámetros y los códigos de respuesta están en la documentación técnica.
Encargar una alerta directa
Crea una alerta con el texto y el plan que viajan en la llamada. Devuelve el identificador de la alerta creada.
Lanzar un perfil
Crea una alerta a partir del código de un perfil y el texto. El plan y los destinatarios se resuelven en el momento del lanzamiento y quedan congelados en la alerta.
Consultar una alerta
Devuelve el estado de la alerta y los intentos realizados con su canal, fecha, resultado y evidencia disponible.
Desactivar una alerta
Detiene los envíos futuros de esa alerta. Es idempotente: repetir la llamada no produce efectos adicionales.
Consultar el estado del servicio
Comprobación de disponibilidad del servicio y del motor de envío, para vigilancia desde el lado del integrador.
Ejemplo ilustrativo
Cómo es un encargo
Ejemplo ilustrativo, no un contrato de API. Los nombres de campo, las rutas y los valores definitivos están en la documentación técnica. No incluye credenciales ni datos reales.
{
"texto": "Temperatura fuera de umbral en la cámara 3",
"remitente": "Alertas de Planta",
"callback_url": "https://sistema-de-origen.example/alertas/callback"
}- texto
- El contenido del aviso que recibirá el destinatario, adaptado por cada canal.
- remitente
- Nombre visible del emisor. En correo sustituye el nombre del remitente; en Telegram y WhatsApp encabeza el texto; en llamada y push viaja como campo adicional. Es opcional.
- callback_url
- Dirección donde se notificarán los eventos de esta alerta. Es opcional: sin ella, el estado se consulta por API.
Ejemplo ilustrativo
Cómo es un callback
Ejemplo ilustrativo de la información que llega al sistema de origen cuando se produce un evento. La estructura definitiva está en la documentación técnica.
{
"evento": "intento_realizado",
"id_alerta": 10456,
"estado": "en_curso",
"intento": {
"numero": 2,
"canal": "telegram",
"fecha": "2026-08-22T09:14:07Z",
"resultado": "exito",
"evidencia": { "message_id": "ilustrativo" }
}
}- Eventos notificados
- Intento realizado y cambio de estado de la alerta.
- Reintentos
- El envío del callback tiene su propio ciclo de reintentos y su propio registro. Si el receptor no responde, la alerta continúa su plan sin verse afectada.
- Recomendación
- Conviene que el receptor sea idempotente: un mismo evento puede llegar más de una vez si un reintento se cruza con una respuesta lenta.
Pruebas
Probar con los permisos reales de la credencial
Solo lo permitido
La zona muestra exclusivamente los métodos habilitados para esa credencial, con su método HTTP, su ruta y su descripción.
Contra la API real
Las pruebas se ejecutan con el mismo token contra la propia API, sin intermediarios. Si un permiso se retira, la prueba también falla.
Sin datos ajenos
El acceso es por credencial y queda limitado al ámbito de esa credencial.
Referencia
Dónde está el detalle completo
- Qué contiene esta página
- Conceptos, recorrido de integración y operaciones a alto nivel, para valorar el encaje.
- Qué no contiene
- Rutas exactas, esquemas completos, códigos de error, límites y ejemplos ejecutables.
Dónde está
[PENDIENTE: enlace a la documentación técnica pública]
Mientras tanto, el equipo facilita la documentación al iniciar la integración.
Valorar la integración con el caso concreto
Con el sistema de origen, el volumen previsto y los canales necesarios, el equipo indica qué operaciones hacen falta y cómo se prepara el acceso.