===========================
Descripción General del API
===========================

NoxPanel expone una API REST completa construida con **Django REST Framework** (DRF).
Todos los módulos (hosting, facturación, tickets) están disponibles como endpoints JSON
para integración con aplicaciones externas, scripts de automatización y paneles personalizados.

.. image:: /_static/screenshots/02_swagger_api.jpg
   :alt: Swagger API Documentation
   :width: 100%
   :align: center

|

URL Base
========

Todas las peticiones a la API usan la siguiente URL base:

.. code-block:: text

   https://<tu-dominio>/

Los endpoints de cada módulo se organizan bajo prefijos específicos:

- **Hosting**: ``/hosting/api/rest/``
- **Facturación**: ``/billing/api/``
- **Tickets**: ``/tickets/api/``
- **Cuentas**: ``/accounts/api/``
- **Base de Conocimiento**: ``/kb/api/``
- **Notificaciones**: ``/notifications/api/v1/``
- **Dashboard**: ``/api/v1/dashboard/``
- **Storefront**: ``/storefront/api/``
- **WhiteLabel**: ``/hosting/api/rest/whitelabel/``

Autenticación
=============

La API soporta dos mecanismos de autenticación simultáneamente:

JWT Bearer Token
----------------

El método recomendado para integraciones externas y scripts.

.. code-block:: text

   Authorization: Bearer <access_token>

- El **access token** tiene una vida de **60 minutos**.
- El **refresh token** tiene una vida de **7 días**.
- Al refrescar el token, se genera un nuevo refresh token (rotación automática).
- El token anterior queda invalidado tras la rotación.

Para obtener tokens, consulta :doc:`authentication`.

Autenticación por Sesión
------------------------

Usado automáticamente por el panel web de NoxPanel. Las peticiones AJAX desde el
navegador incluyen la cookie de sesión Django y el token CSRF.

.. code-block:: text

   Cookie: sessionid=<session_id>
   X-CSRFToken: <csrf_token>

Formato de Respuesta
====================

Todas las respuestas de la API se devuelven en formato **JSON**.

Respuesta exitosa (objeto)
--------------------------

.. code-block:: json

   {
     "id": 1,
     "name": "Mi Sitio Web",
     "domain": "example.com",
     "is_active": true,
     "created_at": "2026-01-15T10:30:00Z"
   }

Respuesta exitosa (lista paginada)
-----------------------------------

.. code-block:: json

   {
     "count": 42,
     "next": "https://panel.example.com/hosting/api/rest/sites/?page=2",
     "previous": null,
     "results": [
       {
         "id": 1,
         "domain": "example.com"
       }
     ]
   }

Paginación
==========

La API usa paginación por página con un tamaño por defecto de **20 elementos**.

.. list-table:: Parámetros de Paginación
   :header-rows: 1
   :widths: 20 60 20

   * - Parámetro
     - Descripción
     - Ejemplo
   * - ``page``
     - Número de página (comienza en 1)
     - ``?page=2``
   * - ``page_size``
     - Elementos por página (máx. 100)
     - ``?page_size=50``

Rate Limiting
=============

La API implementa limitación de tasa para proteger el servicio:

.. list-table:: Límites de Tasa
   :header-rows: 1
   :widths: 30 30 40

   * - Tipo de Usuario
     - Límite
     - Descripción
   * - Anónimo
     - 120 peticiones/minuto
     - Peticiones sin autenticación
   * - Autenticado
     - 1200 peticiones/minuto
     - Peticiones con token JWT o sesión

Cuando se excede el límite, la API devuelve un error ``429 Too Many Requests``
con la cabecera ``Retry-After`` indicando los segundos a esperar.

Filtrado y Ordenación
=====================

Los endpoints de lista soportan filtrado y ordenación mediante query parameters:

.. code-block:: text

   GET /hosting/api/rest/sites/?search=example&ordering=-created_at

- ``search``: Búsqueda por texto en campos relevantes
- ``ordering``: Campo por el que ordenar (prefijo ``-`` para descendente)

Códigos de Error
================

La API utiliza códigos de estado HTTP estándar:

.. list-table:: Códigos de Estado
   :header-rows: 1
   :widths: 15 30 55

   * - Código
     - Nombre
     - Descripción
   * - ``200``
     - OK
     - Petición exitosa (GET, PUT, PATCH)
   * - ``201``
     - Created
     - Recurso creado exitosamente (POST)
   * - ``204``
     - No Content
     - Recurso eliminado exitosamente (DELETE)
   * - ``400``
     - Bad Request
     - Error de validación en los datos enviados
   * - ``401``
     - Unauthorized
     - Token no proporcionado o inválido
   * - ``403``
     - Forbidden
     - Sin permisos para realizar la operación
   * - ``404``
     - Not Found
     - Recurso no encontrado
   * - ``429``
     - Too Many Requests
     - Límite de tasa excedido
   * - ``500``
     - Internal Server Error
     - Error interno del servidor

Formato de error
----------------

.. code-block:: json

   {
     "detail": "Mensaje descriptivo del error."
   }

Errores de validación:

.. code-block:: json

   {
     "domain": ["Este campo es requerido."],
     "name": ["El nombre ya existe para este tenant."]
   }

Aislamiento Multi-Tenant
=========================

Todas las peticiones autenticadas se ejecutan en el contexto del **tenant activo** del usuario.
Los recursos devueltos están filtrados automáticamente por tenant, garantizando el aislamiento
completo de datos entre organizaciones.

Los usuarios superadmin pueden ver recursos de todos los tenants.

Versionado
==========

Actualmente la API se encuentra en su versión **v1** (implícita).
En futuras versiones se añadirá un prefijo ``/api/v2/`` para mantener
retrocompatibilidad.