Obtener artículo
Consulta el detalle localizado de un artículo de documentación desde la wiki pública o desde Documentación autenticada, usando la sección y el slug del artículo o un slug legado de un solo segmento.
En este artículo
Usa esta guía cuando necesites comprobar cómo Antylogic resuelve un artículo concreto de ayuda desde el bundle de documentación. La wiki pública y la pantalla autenticada usan el mismo contenido; cambia la autenticación requerida y el prefijo usado para publicar assets.
La ruta recomendada usa `sectionSlug` más `articleSlug`, porque la app y la wiki llegan al detalle desde el índice de documentación. El slug de un solo segmento queda sólo como compatibilidad para enlaces antiguos.
Antes de empezar
- `backend/docs-content/articles.json` debe estar disponible mediante `DOCS_CONTENT_PATH` o el path por defecto `./docs-content`.
- Para abrir el detalle desde `/api/app/docs/...` o `antylogic://docs/...`, el usuario debe tener una sesión válida; no se requiere un permiso adicional de negocio.
- Para que las imágenes se vean completas, `DOCS_ASSETS_PATH` debe resolver los assets referenciados por el bundle.
- En la app y en la wiki, el operador normalmente parte del índice de documentación, que ya proporciona `section_slug` y `slug`.
Instrucciones
- 1.
Abrir el artículo público
Accede a `/docs/acceso/es-iniciar-sesion-nativa?lang=es`. La wiki pública carga el detalle desde `/api/public/docs/acceso/es-iniciar-sesion-nativa?locale=es&platform=mobile&theme=light` y debe mostrar título, introducción, pasos, validaciones y media o placeholder sin pedir sesión.
- 2.
Comprobar el detalle autenticado
Con una sesión activa de la demo ES, abre `antylogic://docs/acceso/es-iniciar-sesion-nativa` o navega desde el índice de ayuda. La ruta equivalente es `/api/app/docs/acceso/es-iniciar-sesion-nativa?locale=es&platform=mobile&theme=light`.
- 3.
Seleccionar variante de idioma, plataforma y tema
Usa `locale`, `platform` o `device`, y `theme` para pedir la variante correcta. El backend normaliza el idioma a `es` o `en`, la plataforma a `mobile`, `tablet` o `web`, y el tema a `light` o `dark`.
- 4.
Revisar el contrato JSON
La respuesta del detalle debe incluir `version`, `locale`, `platform`, `theme`, `section` y `article`. Dentro de `article` aparecen introducción, prerrequisitos, pasos, validaciones, resultado, `icon_name` y `media`.
- 5.
Gestionar rutas antiguas y errores
Si el artículo no aparece, confirma primero que el índice lo liste con la sección y el slug esperados. Los endpoints también aceptan `/api/public/docs/{articleSlug}` y `/api/app/docs/{articleSlug}` para enlaces antiguos, pero las rutas nuevas deben mantener sección más artículo.
Validaciones y límites
- `GET /api/public/docs/{sectionSlug}/{articleSlug}` expone el contenido sin autenticación ni permisos de negocio.
- `GET /api/app/docs/{sectionSlug}/{articleSlug}` exige sesión general mediante `requireAuthMiddleware`, sin permisos por organización, ubicación, rol, reportes, TPV ni reservas.
- `section.slug` se deriva de la categoría del artículo; `article.slug` se deriva de `ID`, `SourceGuideID` o `Title`, comparados como slugs normalizados.
- `q` no filtra el detalle del artículo; la búsqueda se aplica al índice de documentación.
- Si el asset es resoluble, `article.media[].src` apunta a `/api/public/docs/assets/{path}` o `/api/app/docs/assets/{path}` según el prefijo de la petición.
- El detalle no valida que los archivos de media existan físicamente; esa comprobación ocurre al pedir `/api/*/docs/assets/{path}`.
- `HEAD` en rutas de detalle devuelve 200 antes de validar que el artículo exista; documentarlo como comportamiento implementado.
- Si falta `articles.json`, la API responde 503; si el JSON no se puede decodificar, responde 500; métodos distintos de GET y HEAD reciben 405.
Resultado esperado
El operador puede abrir el mismo artículo localizado desde la wiki pública o desde Documentación autenticada, reconocer qué variante se ha seleccionado y distinguir si un problema pertenece al bundle, a la sesión o a los assets de documentación.