Endpoints de Notificaciones

El módulo de notificaciones expone una API REST bajo el prefijo /notifications/api/v1/ para la gestión de notificaciones in-app y preferencias de email por usuario. Todos los endpoints requieren autenticación y los resultados se filtran automáticamente por el usuario actual.

Notificaciones — /notifications/api/v1/notifications/

Gestión de notificaciones del usuario autenticado. Permite listar, consultar, marcar como leídas y eliminar notificaciones. No se permite la creación directa de notificaciones a través de la API (se generan internamente por el sistema).

Métodos

Método	Endpoint	Descripción
GET	/notifications/api/v1/notifications/	Listar notificaciones (más recientes primero)
GET	/notifications/api/v1/notifications/{id}/	Detalle de una notificación
DELETE	/notifications/api/v1/notifications/{id}/	Eliminar una notificación
PATCH	/notifications/api/v1/notifications/{id}/mark_read/	Marcar notificación como leída
PATCH	/notifications/api/v1/notifications/mark_all_read/	Marcar todas las notificaciones como leídas
GET	/notifications/api/v1/notifications/unread_count/	Obtener contador de notificaciones no leídas

Note

Este endpoint solo soporta los métodos GET, PATCH y DELETE. No se permite POST ni PUT ya que las notificaciones se crean internamente por el sistema (eventos de facturación, tickets, hosting, etc.).

Tipos de notificación

Tipo	Descripción
info	Información general
success	Operación exitosa
warning	Advertencia
error	Error del sistema
billing	Eventos de facturación
ticket	Eventos de tickets de soporte
hosting	Eventos de hosting
vps	Eventos de VPS
system	Notificaciones del sistema

Ejemplo — Listar notificaciones:

curl -X GET https://panel.example.com/notifications/api/v1/notifications/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta:

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "notification_type": "billing",
      "title": "Nueva factura generada",
      "message": "Se ha generado la factura INV-2026-0015 por 60.38 EUR.",
      "url": "/billing/invoices/a1b2c3d4/",
      "is_read": false,
      "is_email_sent": true,
      "created_at": "2026-02-08T10:00:00Z",
      "read_at": null,
      "metadata": {
        "invoice_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "amount": "60.38"
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "notification_type": "ticket",
      "title": "Nueva respuesta en ticket TK-000042",
      "message": "Un agente ha respondido a tu ticket de soporte.",
      "url": "/tickets/e5f6a7b8/",
      "is_read": true,
      "is_email_sent": true,
      "created_at": "2026-02-07T15:30:00Z",
      "read_at": "2026-02-07T16:00:00Z",
      "metadata": {}
    }
  ]
}

Ejemplo — Marcar notificación como leída:

curl -X PATCH https://panel.example.com/notifications/api/v1/notifications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/mark_read/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "notification_type": "billing",
  "title": "Nueva factura generada",
  "message": "Se ha generado la factura INV-2026-0015 por 60.38 EUR.",
  "url": "/billing/invoices/a1b2c3d4/",
  "is_read": true,
  "is_email_sent": true,
  "created_at": "2026-02-08T10:00:00Z",
  "read_at": "2026-02-09T10:15:00Z",
  "metadata": {
    "invoice_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "60.38"
  }
}

Ejemplo — Marcar todas como leídas:

curl -X PATCH https://panel.example.com/notifications/api/v1/notifications/mark_all_read/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta:

{
  "marked_read": 3
}

Ejemplo — Obtener contador de no leídas:

curl -X GET https://panel.example.com/notifications/api/v1/notifications/unread_count/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta:

{
  "unread_count": 3
}

Ejemplo — Eliminar notificación:

curl -X DELETE https://panel.example.com/notifications/api/v1/notifications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  -H "Authorization: Bearer $TOKEN"

Devuelve 204 No Content si la eliminación es exitosa.

Preferencias — /notifications/api/v1/preferences/

Gestión de preferencias de notificación del usuario autenticado. Este endpoint devuelve un objeto único (no una lista paginada) con las preferencias del usuario. Si el usuario no tiene preferencias configuradas, se crean automáticamente con los valores por defecto.

Métodos

Método	Endpoint	Descripción
GET	/notifications/api/v1/preferences/	Obtener preferencias de notificación
PUT	/notifications/api/v1/preferences/	Actualizar preferencias completas
PATCH	/notifications/api/v1/preferences/	Actualizar preferencias parciales

Campos de preferencias

Campo	Defecto	Descripción
email_on_ticket_reply	true	Recibir email cuando hay respuesta en un ticket
email_on_invoice	true	Recibir email cuando se genera una nueva factura
email_on_hosting_alert	true	Recibir email en alertas de hosting
email_on_vps_alert	true	Recibir email en alertas de VPS
email_on_system	true	Recibir email en notificaciones del sistema
in_app_enabled	true	Habilitar notificaciones in-app

Ejemplo — Obtener preferencias:

curl -X GET https://panel.example.com/notifications/api/v1/preferences/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta:

{
  "email_on_ticket_reply": true,
  "email_on_invoice": true,
  "email_on_hosting_alert": true,
  "email_on_vps_alert": true,
  "email_on_system": true,
  "in_app_enabled": true
}

Ejemplo — Desactivar emails de facturación:

curl -X PATCH https://panel.example.com/notifications/api/v1/preferences/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email_on_invoice": false}'

Respuesta:

{
  "email_on_ticket_reply": true,
  "email_on_invoice": false,
  "email_on_hosting_alert": true,
  "email_on_vps_alert": true,
  "email_on_system": true,
  "in_app_enabled": true
}