===========================
Endpoints de Hosting
===========================

El módulo de hosting expone una API REST completa bajo el prefijo
``/hosting/api/rest/``. Todos los endpoints requieren autenticación y filtran
automáticamente los resultados por el **tenant activo** del usuario.

.. contents:: En esta página
   :local:
   :depth: 2

Sitios Web — ``/hosting/api/rest/sites/``
==========================================

Gestión completa de sitios web alojados. Cada sitio se sincroniza con el motor de hosting.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 45 40

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/sites/``
     - Listar sitios del tenant
   * - ``POST``
     - ``/hosting/api/rest/sites/``
     - Crear nuevo sitio web
   * - ``GET``
     - ``/hosting/api/rest/sites/{id}/``
     - Detalle de un sitio
   * - ``PUT``
     - ``/hosting/api/rest/sites/{id}/``
     - Actualizar sitio completo
   * - ``PATCH``
     - ``/hosting/api/rest/sites/{id}/``
     - Actualizar campos parciales
   * - ``DELETE``
     - ``/hosting/api/rest/sites/{id}/``
     - Eliminar sitio (soft delete)
   * - ``POST``
     - ``/hosting/api/rest/sites/{id}/request_ssl/``
     - Solicitar certificado SSL Let's Encrypt
   * - ``POST``
     - ``/hosting/api/rest/sites/provision_full/``
     - Provisionar sitio completo (site + DNS + mail + FTP + DB)
   * - ``POST``
     - ``/hosting/api/rest/sites/{id}/install_cms/``
     - Instalar CMS (WordPress, Joomla, PrestaShop)
   * - ``GET``
     - ``/hosting/api/rest/sites/available_cms/``
     - Listar CMS disponibles para auto-instalación

**Ejemplo — Listar sitios:**

.. code-block:: bash

   curl -X GET https://panel.example.com/hosting/api/rest/sites/ \
     -H "Authorization: Bearer $TOKEN"

**Respuesta:**

.. code-block:: json

   {
     "count": 2,
     "next": null,
     "previous": null,
     "results": [
       {
         "id": 1,
         "tenant": 1,
         "tenant_name": "Mi Empresa",
         "domain": "example.com",
         "hosting_site_id": 5,
         "ip_address": "*",
         "document_root": "/var/www/clients/client1/web1",
         "is_active": true,
         "ssl_enabled": true,
         "created_at": "2026-01-10T08:00:00Z",
         "updated_at": "2026-01-15T14:30:00Z"
       }
     ]
   }

**Ejemplo — Crear sitio:**

.. code-block:: bash

   curl -X POST https://panel.example.com/hosting/api/rest/sites/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"domain": "nuevo.com", "ip_address": "*"}'

**Ejemplo — Provisionar sitio completo (all-in-one):**

.. code-block:: bash

   curl -X POST https://panel.example.com/hosting/api/rest/sites/provision_full/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "domain": "miempresa.com",
       "create_dns": true,
       "create_mail": true,
       "create_ftp": true,
       "create_db": true,
       "create_traefik": true
     }'

Bases de Datos — ``/hosting/api/rest/databases/``
==================================================

Gestión de bases de datos MySQL provisionadas a través del motor de hosting.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/databases/``
     - Listar bases de datos
   * - ``POST``
     - ``/hosting/api/rest/databases/``
     - Crear nueva base de datos
   * - ``GET``
     - ``/hosting/api/rest/databases/{id}/``
     - Detalle de una base de datos
   * - ``DELETE``
     - ``/hosting/api/rest/databases/{id}/``
     - Eliminar base de datos

**Ejemplo — Respuesta de base de datos:**

.. code-block:: json

   {
     "id": 3,
     "tenant": 1,
     "tenant_name": "Mi Empresa",
     "name": "wp_miempresa",
     "hosting_database_id": 12,
     "db_user": "wp_user_12",
     "db_password": null,
     "is_active": true,
     "created_at": "2026-01-12T09:00:00Z",
     "updated_at": "2026-01-12T09:00:00Z"
   }

Zonas DNS — ``/hosting/api/rest/dns-zones/``
=============================================

Gestión de zonas DNS. Cada zona corresponde a un dominio y contiene registros DNS.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/dns-zones/``
     - Listar zonas DNS
   * - ``POST``
     - ``/hosting/api/rest/dns-zones/``
     - Crear nueva zona DNS
   * - ``GET``
     - ``/hosting/api/rest/dns-zones/{id}/``
     - Detalle de una zona
   * - ``PUT``
     - ``/hosting/api/rest/dns-zones/{id}/``
     - Actualizar zona
   * - ``DELETE``
     - ``/hosting/api/rest/dns-zones/{id}/``
     - Eliminar zona
   * - ``GET``
     - ``/hosting/api/rest/dns-zones/{id}/records/``
     - Listar registros de la zona

**Ejemplo — Respuesta de zona DNS:**

.. code-block:: json

   {
     "id": 1,
     "tenant": 1,
     "tenant_name": "Mi Empresa",
     "origin": "example.com.",
     "hosting_zone_id": 8,
     "ns_primary": "ns1.example.com.",
     "admin_email": "admin.example.com.",
     "ttl": 86400,
     "records_count": 5,
     "is_active": true,
     "created_at": "2026-01-10T08:00:00Z",
     "updated_at": "2026-01-10T08:00:00Z"
   }

Registros DNS — ``/hosting/api/rest/dns-records/``
===================================================

Gestión individual de registros DNS dentro de zonas. Soporta tipos A, AAAA, CNAME,
MX, TXT, NS, SRV, CAA y PTR.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/dns-records/``
     - Listar registros DNS
   * - ``POST``
     - ``/hosting/api/rest/dns-records/``
     - Crear nuevo registro
   * - ``GET``
     - ``/hosting/api/rest/dns-records/{id}/``
     - Detalle de un registro
   * - ``PUT``
     - ``/hosting/api/rest/dns-records/{id}/``
     - Actualizar registro
   * - ``DELETE``
     - ``/hosting/api/rest/dns-records/{id}/``
     - Eliminar registro

**Ejemplo — Crear registro A:**

.. code-block:: bash

   curl -X POST https://panel.example.com/hosting/api/rest/dns-records/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "zone": 1,
       "record_type": "A",
       "name": "www",
       "data": "203.0.113.10",
       "ttl": 3600
     }'

**Respuesta:**

.. code-block:: json

   {
     "id": 7,
     "zone": 1,
     "zone_origin": "example.com.",
     "record_type": "A",
     "name": "www",
     "data": "203.0.113.10",
     "priority": 10,
     "ttl": 3600,
     "hosting_record_id": 42,
     "is_active": true,
     "created_at": "2026-02-01T10:00:00Z",
     "updated_at": "2026-02-01T10:00:00Z"
   }

Buzones de Email — ``/hosting/api/rest/mailboxes/``
====================================================

Gestión de buzones de correo electrónico con soporte IMAP/POP3/SMTP.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/mailboxes/``
     - Listar buzones
   * - ``POST``
     - ``/hosting/api/rest/mailboxes/``
     - Crear nuevo buzón
   * - ``GET``
     - ``/hosting/api/rest/mailboxes/{id}/``
     - Detalle de un buzón
   * - ``PUT``
     - ``/hosting/api/rest/mailboxes/{id}/``
     - Actualizar buzón (password, nombre, cuota)
   * - ``DELETE``
     - ``/hosting/api/rest/mailboxes/{id}/``
     - Eliminar buzón

**Ejemplo — Crear buzón:**

.. code-block:: bash

   curl -X POST https://panel.example.com/hosting/api/rest/mailboxes/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "mail_domain": 1,
       "local_part": "info",
       "name": "Info Empresa",
       "password": "SecureP@ss123",
       "quota_mb": 500
     }'

**Respuesta:**

.. code-block:: json

   {
     "id": 5,
     "tenant": 1,
     "tenant_name": "Mi Empresa",
     "mail_domain": 1,
     "mail_domain_name": "example.com",
     "email": "info@example.com",
     "local_part": "info",
     "name": "Info Empresa",
     "hosting_mailbox_id": 23,
     "quota_mb": 500,
     "imap_enabled": true,
     "pop3_enabled": true,
     "smtp_enabled": true,
     "is_active": true,
     "created_at": "2026-02-01T12:00:00Z",
     "updated_at": "2026-02-01T12:00:00Z"
   }

Cuentas FTP — ``/hosting/api/rest/ftp-accounts/``
===================================================

Gestión de cuentas FTP asociadas a sitios web.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/ftp-accounts/``
     - Listar cuentas FTP
   * - ``POST``
     - ``/hosting/api/rest/ftp-accounts/``
     - Crear cuenta FTP
   * - ``GET``
     - ``/hosting/api/rest/ftp-accounts/{id}/``
     - Detalle de una cuenta FTP
   * - ``PUT``
     - ``/hosting/api/rest/ftp-accounts/{id}/``
     - Actualizar cuenta (password, directorio, cuota)
   * - ``DELETE``
     - ``/hosting/api/rest/ftp-accounts/{id}/``
     - Eliminar cuenta FTP

**Ejemplo — Crear cuenta FTP:**

.. code-block:: json

   {
     "site": 1,
     "username": "deploy_user",
     "password": "FtpP@ss456",
     "directory": "/web",
     "quota_mb": 1024
   }

Certificados SSL — ``/hosting/api/rest/ssl-certificates/``
============================================================

Gestión de certificados SSL, con soporte para Let's Encrypt automático.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 55 30

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/ssl-certificates/``
     - Listar certificados
   * - ``POST``
     - ``/hosting/api/rest/ssl-certificates/``
     - Crear y solicitar certificado
   * - ``DELETE``
     - ``/hosting/api/rest/ssl-certificates/{id}/``
     - Eliminar certificado
   * - ``POST``
     - ``/hosting/api/rest/ssl-certificates/{id}/request_letsencrypt/``
     - Solicitar Let's Encrypt
   * - ``POST``
     - ``/hosting/api/rest/ssl-certificates/{id}/renew/``
     - Renovar certificado

**Respuesta de certificado:**

.. code-block:: json

   {
     "id": 2,
     "site": 1,
     "site_domain": "example.com",
     "cert_type": "letsencrypt",
     "domain": "example.com",
     "expires_at": "2026-06-15T00:00:00Z",
     "is_active": true,
     "auto_renew": true,
     "is_expired": false,
     "days_until_expiry": 127,
     "created_at": "2026-01-15T10:00:00Z",
     "updated_at": "2026-01-15T10:00:00Z"
   }

Otros Endpoints de Hosting
===========================

Paquetes — ``/hosting/api/rest/packages/``
------------------------------------------

Lectura para todos los usuarios autenticados, escritura solo para admins.

Tenants — ``/hosting/api/rest/tenants/``
-----------------------------------------

Gestión de tenants (organizaciones). Incluye acciones:

- ``POST /hosting/api/rest/tenants/{id}/sync/`` — Sincronizar con el motor de hosting
- ``GET /hosting/api/rest/tenants/{id}/stats/`` — Estadísticas de uso

Dominios de Email — ``/hosting/api/rest/mail-domains/``
--------------------------------------------------------

CRUD completo de dominios de email.

Alias de Email — ``/hosting/api/rest/mail-aliases/``
-----------------------------------------------------

CRUD de alias de email (redirecciones).

Usuarios Shell — ``/hosting/api/rest/shell-users/``
----------------------------------------------------

Gestión de usuarios SSH/shell asociados a sitios web.

Configuración WhiteLabel — ``/hosting/api/rest/whitelabel/``
=============================================================

Gestión de configuración de marca blanca por tenant. Permite a los
administradores personalizar el aspecto del panel (logos, colores, textos,
CSS y dominio personalizado) para cada organización. Solo accesible para
administradores; los superusuarios ven todas las configuraciones, los
administradores de tenant solo la de su propio tenant.

.. list-table:: Métodos
   :header-rows: 1
   :widths: 15 50 35

   * - Método
     - Endpoint
     - Descripción
   * - ``GET``
     - ``/hosting/api/rest/whitelabel/``
     - Listar configuraciones de marca blanca
   * - ``POST``
     - ``/hosting/api/rest/whitelabel/``
     - Crear configuración de marca blanca
   * - ``GET``
     - ``/hosting/api/rest/whitelabel/{id}/``
     - Detalle de una configuración
   * - ``PUT``
     - ``/hosting/api/rest/whitelabel/{id}/``
     - Actualizar configuración completa
   * - ``PATCH``
     - ``/hosting/api/rest/whitelabel/{id}/``
     - Actualizar campos parciales
   * - ``DELETE``
     - ``/hosting/api/rest/whitelabel/{id}/``
     - Eliminar configuración

Campos
------

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Campo
     - Tipo
     - Descripción
   * - ``id``
     - int
     - Identificador único (solo lectura)
   * - ``tenant``
     - int
     - ID del tenant asociado
   * - ``brand_name``
     - string
     - Nombre de marca (sustituye "NoxPanel" en el panel)
   * - ``logo_url``
     - URL
     - URL del logo personalizado
   * - ``favicon_url``
     - URL
     - URL del favicon personalizado
   * - ``primary_color``
     - string
     - Color primario en formato hex (ej: ``#4F46E5``)
   * - ``secondary_color``
     - string
     - Color secundario en formato hex (ej: ``#10B981``)
   * - ``sidebar_bg_color``
     - string
     - Color de fondo del sidebar (ej: ``#1e1e2e``)
   * - ``sidebar_text_color``
     - string
     - Color del texto del sidebar (ej: ``#cdd6f4``)
   * - ``custom_css``
     - text
     - CSS personalizado inyectado en el panel
   * - ``footer_text``
     - string
     - Texto del pie de página
   * - ``footer_url``
     - URL
     - URL del enlace del pie de página
   * - ``email_from_name``
     - string
     - Nombre del remitente en emails
   * - ``email_from_address``
     - email
     - Dirección email del remitente
   * - ``custom_panel_domain``
     - string
     - Dominio personalizado del panel (ej: ``panel.mihosting.com``)
   * - ``is_active``
     - bool
     - Si la configuración está activa
   * - ``created_at``
     - datetime
     - Fecha de creación (solo lectura)
   * - ``updated_at``
     - datetime
     - Fecha de última actualización (solo lectura)

**Ejemplo — Crear configuración de marca blanca:**

.. code-block:: bash

   curl -X POST https://panel.example.com/hosting/api/rest/whitelabel/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "tenant": 1,
       "brand_name": "Mi Hosting Pro",
       "logo_url": "https://cdn.mihosting.com/logo.png",
       "favicon_url": "https://cdn.mihosting.com/favicon.ico",
       "primary_color": "#2563EB",
       "secondary_color": "#059669",
       "sidebar_bg_color": "#111827",
       "sidebar_text_color": "#F3F4F6",
       "footer_text": "Mi Hosting Pro - Todos los derechos reservados",
       "footer_url": "https://mihosting.com",
       "email_from_name": "Mi Hosting Pro",
       "email_from_address": "noreply@mihosting.com",
       "custom_panel_domain": "panel.mihosting.com"
     }'

**Respuesta (201 Created):**

.. code-block:: json

   {
     "id": 1,
     "tenant": 1,
     "brand_name": "Mi Hosting Pro",
     "logo_url": "https://cdn.mihosting.com/logo.png",
     "favicon_url": "https://cdn.mihosting.com/favicon.ico",
     "primary_color": "#2563EB",
     "secondary_color": "#059669",
     "sidebar_bg_color": "#111827",
     "sidebar_text_color": "#F3F4F6",
     "custom_css": "",
     "footer_text": "Mi Hosting Pro - Todos los derechos reservados",
     "footer_url": "https://mihosting.com",
     "email_from_name": "Mi Hosting Pro",
     "email_from_address": "noreply@mihosting.com",
     "custom_panel_domain": "panel.mihosting.com",
     "is_active": true,
     "created_at": "2026-02-09T10:00:00Z",
     "updated_at": "2026-02-09T10:00:00Z"
   }

**Ejemplo — Actualizar colores:**

.. code-block:: bash

   curl -X PATCH https://panel.example.com/hosting/api/rest/whitelabel/1/ \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "primary_color": "#7C3AED",
       "custom_css": ".navbar { border-bottom: 2px solid #7C3AED; }"
     }'

.. note::

   Cada tenant solo puede tener una configuración de marca blanca (relación
   OneToOne). Si se intenta crear una segunda configuración para el mismo
   tenant, se producirá un error de unicidad.