================================ 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. .. contents:: En esta página :local: :depth: 2 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). .. list-table:: Métodos :header-rows: 1 :widths: 15 55 30 * - 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 ---------------------- .. list-table:: :header-rows: 1 :widths: 20 80 * - 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:** .. code-block:: bash curl -X GET https://panel.example.com/notifications/api/v1/notifications/ \ -H "Authorization: Bearer $TOKEN" **Respuesta:** .. code-block:: json { "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:** .. code-block:: bash curl -X PATCH https://panel.example.com/notifications/api/v1/notifications/a1b2c3d4-e5f6-7890-abcd-ef1234567890/mark_read/ \ -H "Authorization: Bearer $TOKEN" **Respuesta:** .. code-block:: json { "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:** .. code-block:: bash curl -X PATCH https://panel.example.com/notifications/api/v1/notifications/mark_all_read/ \ -H "Authorization: Bearer $TOKEN" **Respuesta:** .. code-block:: json { "marked_read": 3 } **Ejemplo — Obtener contador de no leídas:** .. code-block:: bash curl -X GET https://panel.example.com/notifications/api/v1/notifications/unread_count/ \ -H "Authorization: Bearer $TOKEN" **Respuesta:** .. code-block:: json { "unread_count": 3 } **Ejemplo — Eliminar notificación:** .. code-block:: bash 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. .. list-table:: Métodos :header-rows: 1 :widths: 15 55 30 * - 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 ----------------------- .. list-table:: :header-rows: 1 :widths: 35 15 50 * - 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:** .. code-block:: bash curl -X GET https://panel.example.com/notifications/api/v1/preferences/ \ -H "Authorization: Bearer $TOKEN" **Respuesta:** .. code-block:: json { "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:** .. code-block:: bash 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:** .. code-block:: json { "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 }