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.

URL Base

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

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.

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 Autenticación.

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.

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)

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

Respuesta exitosa (lista paginada)

{
  "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.

Parámetros de Paginación
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:

Límites de Tasa
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:

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:

Códigos de Estado
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

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

Errores de validación:

{
  "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.