Endpoints de Base de Conocimiento

El módulo de base de conocimiento (KB) expone una API REST bajo el prefijo /kb/api/ para la gestión de categorías, artículos y anuncios del sistema. Los endpoints de lectura están disponibles para todos los usuarios autenticados; las operaciones de escritura están restringidas a administradores.

Categorías — `/kb/api/categories/`

Gestión de categorías de la base de conocimiento. Las categorías públicas son visibles para todos los usuarios autenticados. Los administradores pueden ver también las categorías privadas y realizar operaciones de escritura.

Métodos
Método	Endpoint	Descripción
`GET`	`/kb/api/categories/`	Listar categorías (públicas o todas para admin)
`POST`	`/kb/api/categories/`	Crear nueva categoría (solo admin)
`GET`	`/kb/api/categories/{id}/`	Detalle de una categoría
`PUT`	`/kb/api/categories/{id}/`	Actualizar categoría (solo admin)
`PATCH`	`/kb/api/categories/{id}/`	Actualizar campos parciales (solo admin)
`DELETE`	`/kb/api/categories/{id}/`	Eliminar categoría (solo admin)

Ejemplo — Listar categorías:

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

Respuesta:

{
  "count": 4,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Hosting",
      "slug": "hosting",
      "description": "Artículos sobre gestión de hosting compartido",
      "icon": "bi-globe",
      "parent": null,
      "order": 0,
      "is_public": true,
      "is_active": true,
      "articles_count": 12,
      "created_at": "2026-01-10T08:00:00Z"
    },
    {
      "id": 2,
      "name": "DNS",
      "slug": "dns",
      "description": "Guías de configuración DNS",
      "icon": "bi-diagram-3",
      "parent": 1,
      "order": 1,
      "is_public": true,
      "is_active": true,
      "articles_count": 5,
      "created_at": "2026-01-10T08:30:00Z"
    }
  ]
}

Note

El campo articles_count devuelve la cantidad de artículos publicados y públicos en cada categoría. El campo slug se genera automáticamente a partir del nombre si no se proporciona.

Ejemplo — Crear categoría (admin):

curl -X POST https://panel.example.com/kb/api/categories/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Facturación",
    "description": "Guías sobre facturación y pagos",
    "icon": "bi-receipt",
    "order": 3,
    "is_public": true
  }'

Artículos — `/kb/api/articles/`

Gestión de artículos de la base de conocimiento. El listado utiliza un serializador reducido (sin contenido completo); el detalle incluye el contenido Markdown, metadatos SEO y adjuntos. Al consultar el detalle de un artículo, se incrementa automáticamente el contador de visualizaciones.

Métodos
Método	Endpoint	Descripción
`GET`	`/kb/api/articles/`	Listar artículos (publicados para usuarios, todos para admin)
`POST`	`/kb/api/articles/`	Crear nuevo artículo (solo admin)
`GET`	`/kb/api/articles/{id}/`	Detalle completo de un artículo (incrementa vistas)
`PUT`	`/kb/api/articles/{id}/`	Actualizar artículo (solo admin)
`PATCH`	`/kb/api/articles/{id}/`	Actualizar campos parciales (solo admin)
`DELETE`	`/kb/api/articles/{id}/`	Eliminar artículo (solo admin)
`POST`	`/kb/api/articles/{id}/vote/`	Votar si el artículo fue útil

Estados del artículo 

Estado	Descripción
`draft`	Borrador (solo visible para administradores)
`published`	Publicado (visible para todos los usuarios)
`archived`	Archivado (solo visible para administradores)

Ejemplo — Listar artículos:

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

Respuesta (lista):

{
  "count": 25,
  "next": "https://panel.example.com/kb/api/articles/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Cómo configurar DNS para tu dominio",
      "slug": "como-configurar-dns-para-tu-dominio",
      "category": 2,
      "category_name": "DNS",
      "excerpt": "Guía paso a paso para configurar registros DNS A, CNAME, MX y TXT.",
      "status": "published",
      "is_featured": true,
      "is_public": true,
      "tags": "dns, dominios, configuración",
      "views_count": 342,
      "helpful_yes": 45,
      "helpful_no": 3,
      "author": 1,
      "author_name": "admin",
      "published_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-01T12:00:00Z"
    }
  ]
}

Ejemplo — Detalle de artículo:

curl -X GET https://panel.example.com/kb/api/articles/1/ \
  -H "Authorization: Bearer $TOKEN"

Respuesta (detalle):

{
  "id": 1,
  "title": "Cómo configurar DNS para tu dominio",
  "slug": "como-configurar-dns-para-tu-dominio",
  "category": 2,
  "category_name": "DNS",
  "content": "# Configurar DNS\n\nPara configurar los registros DNS de tu dominio...",
  "excerpt": "Guía paso a paso para configurar registros DNS A, CNAME, MX y TXT.",
  "status": "published",
  "is_featured": true,
  "is_public": true,
  "tags": "dns, dominios, configuración",
  "views_count": 343,
  "helpful_yes": 45,
  "helpful_no": 3,
  "author": 1,
  "author_name": "admin",
  "meta_title": "Configurar DNS - Guía completa",
  "meta_description": "Aprende a configurar registros DNS paso a paso.",
  "attachments": [
    {
      "id": 1,
      "file": "/media/kb/attachments/2026/01/dns-diagram.png",
      "filename": "dns-diagram.png",
      "file_size": 45320,
      "uploaded_at": "2026-01-15T10:00:00Z"
    }
  ],
  "published_at": "2026-01-15T10:00:00Z",
  "created_at": "2026-01-14T09:00:00Z",
  "updated_at": "2026-02-01T12:00:00Z"
}

Note

El campo views_count se incrementa automáticamente cada vez que se accede al detalle del artículo. Los campos helpful_yes y helpful_no se modifican a través de la acción vote.

Ejemplo — Votar artículo como útil:

curl -X POST https://panel.example.com/kb/api/articles/1/vote/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"helpful": true}'

Respuesta:

{
  "status": "voted"
}

Para votar que el artículo no fue útil, enviar {"helpful": false}.

Ejemplo — Crear artículo (admin):

curl -X POST https://panel.example.com/kb/api/articles/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cómo instalar WordPress",
    "category": 1,
    "content": "# Instalar WordPress\n\nSigue estos pasos...",
    "excerpt": "Guía para instalar WordPress en tu hosting.",
    "status": "published",
    "is_public": true,
    "tags": "wordpress, cms, instalación"
  }'

Note

El campo author se asigna automáticamente al usuario autenticado que crea el artículo. El campo slug se genera a partir del título si no se proporciona explícitamente.

Anuncios — `/kb/api/announcements/`

Gestión de anuncios del sistema (mantenimientos, novedades, avisos críticos). Los anuncios activos son visibles para todos los usuarios autenticados. Los administradores pueden crear, editar y eliminar anuncios.

Métodos
Método	Endpoint	Descripción
`GET`	`/kb/api/announcements/`	Listar anuncios (activos para usuarios, todos para admin)
`POST`	`/kb/api/announcements/`	Crear nuevo anuncio (solo admin)
`GET`	`/kb/api/announcements/{id}/`	Detalle de un anuncio
`PUT`	`/kb/api/announcements/{id}/`	Actualizar anuncio (solo admin)
`PATCH`	`/kb/api/announcements/{id}/`	Actualizar campos parciales (solo admin)
`DELETE`	`/kb/api/announcements/{id}/`	Eliminar anuncio (solo admin)

Tipos de anuncio 

Tipo	Descripción
`info`	Información general
`warning`	Aviso importante
`critical`	Incidencia crítica
`maintenance`	Mantenimiento programado
`release`	Novedad o actualización del sistema

Ejemplo — Listar anuncios:

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

Respuesta:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Mantenimiento programado - 15 Feb 2026",
      "content": "El próximo sábado 15 de febrero realizaremos tareas de mantenimiento en los servidores de hosting. El servicio podría verse afectado entre las 02:00 y las 06:00 CET.",
      "announcement_type": "maintenance",
      "is_active": true,
      "is_pinned": true,
      "show_in_dashboard": true,
      "show_in_banner": true,
      "author": 1,
      "author_name": "admin",
      "published_at": "2026-02-08T10:00:00Z",
      "expires_at": "2026-02-16T06:00:00Z"
    },
    {
      "id": 2,
      "title": "Nueva funcionalidad: Auto-instalador de CMS",
      "content": "Ahora puedes instalar WordPress, Joomla y PrestaShop con un solo clic desde el panel de hosting.",
      "announcement_type": "release",
      "is_active": true,
      "is_pinned": false,
      "show_in_dashboard": true,
      "show_in_banner": false,
      "author": 1,
      "author_name": "admin",
      "published_at": "2026-02-05T12:00:00Z",
      "expires_at": null
    }
  ]
}

Ejemplo — Crear anuncio (admin):

curl -X POST https://panel.example.com/kb/api/announcements/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Actualización del panel v2.5",
    "content": "Hemos lanzado la versión 2.5 con mejoras de rendimiento y nuevas funcionalidades.",
    "announcement_type": "release",
    "is_pinned": false,
    "show_in_dashboard": true,
    "show_in_banner": false
  }'

Note

El campo author se asigna automáticamente al usuario autenticado. Si se establece expires_at, el anuncio se ocultará automáticamente después de esa fecha para los usuarios regulares (los administradores siguen viéndolo).

Endpoints de Base de Conocimiento

Categorías — /kb/api/categories/

Artículos — /kb/api/articles/

Estados del artículo

Anuncios — /kb/api/announcements/

Tipos de anuncio

Categorías — `/kb/api/categories/`

Artículos — `/kb/api/articles/`

Estados del artículo 

Anuncios — `/kb/api/announcements/`

Tipos de anuncio 