Filtrar el indice de documentacion por q
Consulta el indice de documentacion con `locale` y `q` para localizar articulos cuyo contenido contiene una cadena concreta. La API devuelve secciones y resumenes, no el detalle completo ni extractos de la coincidencia.
En este artículo
Usa esta guia cuando soporte, documentacion o implantacion necesiten comprobar rapidamente que hay articulos relacionados con un termino como `reservas` o `tpv` sin abrir cada articulo.
El filtro se ejecuta en el backend solo sobre las rutas exactas de indice `/api/public/docs` y `/api/app/docs`. La busqueda visible de la pantalla Docs es un filtro local de interfaz sobre resumenes ya cargados.
Antes de empezar
- El bundle de documentacion esta publicado en `backend/docs-content/articles.json` o `DOCS_CONTENT_PATH` apunta a un `articles.json` valido.
- La consulta se hace sobre la ruta de indice, sin seccion, articulo ni `assets` en el path.
- La peticion usa `GET`; `HEAD` solo sirve como comprobacion tecnica y no evalua `q`.
- Para `/api/app/docs`, el operador tiene Bearer token o cookie `access_token` validos. `/api/public/docs` no exige sesion.
Instrucciones
- 1.
Elegir el prefijo de API
Usa `GET /api/public/docs` para validar el indice publico sin sesion, o `GET /api/app/docs` para comprobar el mismo contrato desde una sesion autenticada. La diferencia operativa es la autenticacion; el filtro `q` es compartido.
- 2.
Enviar `locale` y `q`
Anade el idioma y el termino en query string, por ejemplo `GET /api/public/docs?locale=es&q=reservas` o `GET /api/app/docs?locale=es&q=tpv`. El backend recorta espacios de `q` y compara sin distinguir mayusculas de minusculas.
- 3.
Revisar el indice filtrado
Comprueba `query`, `article_count` y `sections`. Cada seccion agrupa articulos coincidentes por categoria y cada articulo se devuelve como resumen con identificadores, titulo, resumen, icono y marca de media.
- 4.
Interpretar las coincidencias
Un articulo puede aparecer aunque el termino no se vea en el resumen, porque la busqueda tambien evalua metadatos, introduccion, requisitos, pasos, validaciones y resultado del articulo completo.
- 5.
Separarlo de la busqueda visible
No documentes el buscador visible de `/docs` como una llamada backend con `q` en el flujo normal actual. La wiki publica y la pantalla Docs cargan el indice y filtran localmente los resumenes ya recibidos.
Validaciones y límites
- Si `q` falta o queda vacio tras recortar espacios, la API devuelve el indice completo del `locale`.
- Si no hay coincidencias, la respuesta sigue siendo `200 OK` con `article_count: 0` y `sections: []`.
- La busqueda es substring en minusculas: no es fuzzy, no tokeniza, no hace stemming y no elimina acentos.
- `q` no filtra rutas de detalle ni assets; solo afecta al indice exacto.
- El orden de secciones y articulos sigue el bundle `articles.json`; no hay ranking por relevancia.
- `theme` puede viajar como opcion general, pero no afecta al filtrado ni aparece en la respuesta de indice.
Resultado esperado
El operador obtiene un indice reducido al idioma solicitado y al termino `q`, con secciones y resumenes seguros para revisar documentacion sin exponer el cuerpo completo de los articulos.