# Servicios web de FSO Todos los ejemplos de esta página se ejecutaron con Devkron 2.0 detrás de nginx, con un usuario `web` que es `admin` en el manifiesto de la raíz y un usuario `cajero2` que solo tiene `write` en la carpeta `/compartido`. Los privilegios se explican en [Metadatos y privilegios](/es/devkron/2.0/marcos/fso/privilegios.md). ## lst.fso: listar carpetas y archivos Devuelve el contenido de una carpeta, y opcionalmente de sus subcarpetas, con filtro por nombre y búsqueda de texto dentro de los archivos. - **URL**: `{carpeta}/lst.fso` - **Método**: `GET` | Parámetro | Descripción | Predeterminado | |---|---|---| | `filter` | Filtro de nombres de archivo (`*.txt`); no afecta a carpetas | `*.*` | | `deep` | Niveles de subcarpetas. Con `0`, solo la carpeta indicada (las subcarpetas salen sin contenido) | `999` | | `search` | Texto a buscar dentro de los archivos (solo los de hasta `@dklfso_textfile_maxsize_r4search` bytes, 262 144 de forma predeterminada; los mayores se omiten al buscar) | vacío | | `mode` | `0` carpetas y archivos · `1` solo carpetas · `2` solo archivos · `3` solo los archivos que contienen `search` | `0` | | `uri`, `base_path`, `host` | Vea [Conceptos](/es/devkron/2.0/marcos/fso/#el-recurso-sobre-el-que-se-opera) | | Se omiten sin error los elementos sobre los que el usuario no tiene privilegio de listado, los archivos `._m_` y `._p_` y, con `@dklfso_protected_dir_restricted` en `@true`, la carpeta protegida. **Privilegio** sobre cada carpeta y archivo listado: `dkl_fso_list`, `write`, `read` + `plus` o `admin`. **Respuesta** con `mode` 0, 1 o 2: un árbol. Real, `GET /documentos/lst.fso` como anónimo, con `dkl_fso_list` para todos en la raíz: ```json {"success":1,"data":{"folders":null,"files":[{"type":"file","name":"notas.txt","path":"/documentos","fullpath":"/documentos/notas.txt","creation":"2026-10-27T11:33:18","lastaccess":"2026-10-27T11:33:18","lastwrite":"2026-10-27T11:33:18","length":16,"privileges":{"admin":[{"user":"web"}],"read":[{"user":"+"}],"dkl_fso_list":[{"user":"+"}]},"priv_inherited":2}]}} ``` Con `mode=3`, `data` es una **lista plana** de los archivos encontrados. Real, `GET /lst.fso?search=Segunda&filter=*.txt&mode=3`: ```json {"success":1,"data":[{"type":"file","name":"notas.txt","path":"/documentos","fullpath":"/documentos/notas.txt",...,"properties":{"autor":"ana"},...}]} ``` | Campo | Descripción | |---|---| | `type` | `folder` o `file` | | `name` | Nombre con extensión | | `path` | URI de la carpeta que lo contiene | | `fullpath` | URI completa | | `length` | Tamaño en bytes (solo archivos) | | `creation`, `lastaccess`, `lastwrite` | Fechas en UTC, `yyyy-MM-ddThh:mm:ss` (la hora sale en formato de 12 horas, sin AM/PM: es el formato del código) | | `properties` | [Propiedades extendidas](/es/devkron/2.0/marcos/fso/privilegios.md#propiedades-extendidas), si hay | | `privileges` | Manifiesto aplicable (propio o heredado), si hay | | `priv_inherited` | Niveles hacia arriba donde se encontró el manifiesto (`0` = propio) | | `folders`, `files` | Contenido (solo carpetas; nulo si está vacío) | Si el usuario no puede listar la carpeta pedida, `data` es nulo (`{"success":1,"data":null}`). ```text https://sitio.ejemplo.com/lst.fso https://sitio.ejemplo.com/documentos/lst.fso?filter=*.pdf&deep=0 https://sitio.ejemplo.com/lst.fso?search=guanabanas&filter=*.txt&mode=3 https://sitio.ejemplo.com/lst.fso?uri=/documentos/informes&mode=1 ``` ```bash # Solo carpetas de primer nivel curl -H "Authorization: Bearer MI_TOKEN" "https://sitio.ejemplo.com/lst.fso?mode=1&deep=0" ``` ## get.fso: metadatos de un archivo o carpeta - **URL**: `{recurso}/get.fso` - **Método**: `GET` - **Parámetros**: `uri`, `base_path`, `host` **Privilegio**: `dkl_fso_getprops`, `write`, `read` + `plus` o `admin`. El manifiesto (`privileges`) solo se incluye si además tiene `dkl_fso_getprivs`, `write`, `read` + `plus` o `admin`. Real, como `web` (admin): ```json {"success":1,"data":{"type":"file","fullpath":"/documentos/notas.txt","path":"/documentos","name":"notas.txt","creation":"2026-10-27T11:37:25","lastaccess":"2026-10-27T11:33:18","lastwrite":"2026-10-27T11:37:25","length":29,"properties":{"autor":"ana"},"privileges":{...},"priv_inherited":2}} ``` Como anónimo, con `dkl_fso_getprops` para todos pero sin `dkl_fso_getprivs`, la respuesta es la misma **sin** `privileges`. `data` es nulo si el recurso no existe, si el usuario no tiene el privilegio o si está en la carpeta protegida restringida; el servicio no distingue esos casos. ```text https://sitio.ejemplo.com/documentos/contrato.docx/get.fso https://sitio.ejemplo.com/get.fso?uri=/documentos/contrato.docx ``` ## set.fso: propiedades, privilegios y contenido de texto Para uno o varios recursos en una sola llamada: guardar sus propiedades extendidas, su manifiesto de privilegios y el contenido de archivos de texto (creándolos si no existen). - **URL**: `{carpeta}/set.fso` - **Método**: `POST` o `PUT` - **Cuerpo**: JSON (`application/json;charset=utf-8`), un objeto cuyas llaves son [URI de recursos](/es/devkron/2.0/marcos/fso/#claves-de-uri-en-los-cuerpos-json) | Campo | Descripción | |---|---| | `properties` | Objeto con las propiedades extendidas. **Sustituye por completo** las existentes | | `privileges` | Manifiesto de privilegios. **Sustituye por completo** el existente | | `text` | Contenido del archivo; si no existe, se crea. Solo archivos | | `text_encode` | Codificación de `text`; predeterminado `utf8` | Se procesan en el orden `properties`, `privileges`, `text`; si uno falla, los siguientes de esa misma llave no se procesan. ```json { ".": { "properties": { "titulo": "Documentos" } }, "notas.txt": { "properties": { "autor": "ana" }, "text": "Primera línea\nSegunda línea" }, "nuevo.txt": { "text": "creado con set.fso" }, "script.dkl": { "text": "x" }, "falta.txt": { "properties": { "a": 1 } } } ``` Respuesta real de `POST /documentos/set.fso` como `web` (admin): ```json {"success":1,"data":{ ".":{"props_done":1,"privs_done":0}, "notas.txt":{"props_done":1,"privs_done":0,"txt_done":1}, "nuevo.txt":{"props_done":0,"privs_done":0,"txt_done":1}, "script.dkl":{"props_done":0,"privs_done":0,"txt_done":1}, "falta.txt":{"props_done":0,"privs_done":0,"message":"{0} Resource not found[Ln= 40]"}}} ``` | Campo | Descripción | |---|---| | `props_done` | Se escribieron las propiedades | | `privs_done` | Se escribió el manifiesto | | `txt_done` | Presente si se envió `text`; se escribió el contenido | | `message` | Error de ese recurso | Una llave que no existe y no trae `text` da `Resource not found`. **Privilegios** (sobre el recurso, salvo la creación): | Campo | Requiere (alguno) | |---|---| | `properties` | `dkl_fso_setprops`, `write`, `admin` | | `privileges` | `dkl_fso_setprivs`, `write` + `plus`, `admin` | | `text` en archivo existente | `dkl_fso_overwrite`, `write`, `admin` | | `text` en archivo nuevo | `dkl_fso_upload`, `write` o `admin` **sobre la carpeta desde la que se llama** | Escribir `text` en un archivo con extensión de `@dklfso_danger_files_ext` (`.dkl`, `.dkh`) requiere además `dkl_fso_danger`, `write` + `plus` o `admin`. Comprobado como `cajero2` (solo `write`): `{"x.dkl":{"text":"y"}}` responde `No está autorizado, extensión restringida`, y cambiar el manifiesto (`privileges`) responde `No está autorizado` (le falta `plus`). ## upl.fso: subir archivos Sube uno o varios archivos `multipart/form-data` a la carpeta indicada. Puede crear subcarpetas y descomprimir `.zip`. - **URL**: `{carpeta}/upl.fso` - **Método**: `POST` o `PUT` ### Comportamiento - La carpeta de destino es la URI. Si no existe, se intenta crear (con sus intermedias) si el usuario tiene el privilegio de crear carpetas según el manifiesto que hereda y no es la carpeta protegida restringida. **Defecto conocido**: en la versión actual, crear la carpeta de destino falla siempre (`No está autorizado para crear la estructura de directorios`), incluso para `admin`, porque el manifiesto heredado se copia sin `*`. Cree antes la carpeta con `do.fso` (`mkdir`) o use subcarpetas en el nombre del campo (abajo), que sí funcionan. - Cada archivo se guarda con el nombre del atributo `filename` de su parte del formulario y se procesa por separado; el resultado se identifica por ese nombre. - **Si ya existe un archivo con ese nombre, se sobrescribe** (comprobado: se subió dos veces `dup.txt` con contenido distinto y quedó el segundo). La documentación 1.0 decía que se conservaba el existente. ### Subir carpetas completas Si el **nombre del campo** contiene `/`, la parte de carpeta se crea dentro del destino: | Nombre del campo | `filename` | Se guarda en | |---|---|---| | `archivo1` | `a.txt` | `{uri}/a.txt` | | `docs/2026/informe` | `a.txt` | `{uri}/docs/2026/a.txt` | ### Descomprimir un .zip Si el nombre del campo termina en `.zip` seguido del marcador `@dklfso_id_process_file` (`*`), es decir `.zip*`, el archivo se descomprime en el destino y el `.zip` se elimina. Requiere además `dkl_fso_zip`, `write`, `read` + `plus` o `admin`. Comprobado: un zip con `a.txt` y `sub/b.txt` dejó `a.txt` y `sub/b.txt` en la carpeta. ### Archivos .jsnwm Con un campo que termina en `.jsnwm*`, el archivo se envía al servicio de [websencia.dev](https://websencia.dev), se descarga el resultado y se descomprime en el destino; el `.jsnwm` se elimina. El servidor necesita salida a internet. (No se probó: el equipo de pruebas no tiene salida a ese servicio.) ### Privilegios Sobre la carpeta de destino: `dkl_fso_upload`, `write` o `admin`. Además: | Situación | Requiere (alguno) | |---|---| | Extensión de `@dklfso_danger_files_ext` | `dkl_fso_danger`, `write` + `plus`, `admin` | | Crear la carpeta de destino | `dkl_fso_mkdir`, `write`, `admin` | | Campo `.zip*` | `dkl_fso_zip`, `write`, `read` + `plus`, `admin` | ### Ejemplos ```html
``` ```html
``` Una carpeta completa con su estructura (JavaScript): ```html ``` ```bash # Un archivo curl -H "Authorization: Bearer MI_TOKEN" -F "archivo=@informe.pdf" "https://sitio.ejemplo.com/documentos/upl.fso" # Dentro de una subcarpeta (se crea si no existe) curl -H "Authorization: Bearer MI_TOKEN" -F "2026/q3/informe=@informe.pdf" "https://sitio.ejemplo.com/documentos/upl.fso" # Un zip que se descomprime curl -H "Authorization: Bearer MI_TOKEN" -F "paquete.zip*=@paquete.zip" "https://sitio.ejemplo.com/documentos/upl.fso" ``` Respuestas reales: ```text como web: {"success":1,"data":{"informe.pdf":{"done":1}}} como cajero2 con malo.dkl (sin danger): {"success":1,"data":{"malo.dkl":{"message":"No autorizado","done":0}}} sin archivos: {"success":0,"message":"{0} No se han enviado archivos[Ln= 46]"} destino que es un archivo: {"success":0,"message":"{0} El destino no es un directorio[Ln= 41]"} anónimo: {"success":0,"message":"{0} No está autorizado para subir archivos en esta ubicación[Ln= 42]"} ``` ## do.fso: crear, borrar, copiar, mover y renombrar Para uno o varios recursos en una llamada. - **URL**: `{carpeta}/do.fso` - **Método**: `POST` o `PUT` - **Cuerpo**: JSON con llaves de [URI de recursos](/es/devkron/2.0/marcos/fso/#claves-de-uri-en-los-cuerpos-json); cada valor trae `action` (sin distinguir mayúsculas) | `action` | Campos | Efecto | |---|---|---| | `mkdir` | `path` | La llave debe ser una **carpeta existente**; se crea dentro la subcarpeta `path` (puede ser `a/b/c`) | | `delete` | | Borra el archivo (con sus `._m_` y `._p_`) o la carpeta **con todo su contenido** | | `copy` | `to` | Copia el archivo, con su nombre, a la carpeta `to` (con `._m_` y `._p_`) | | `move` | `to` | Como `copy` y luego borra el original | | `rename` | `as` | Cambia el nombre dentro de la misma carpeta; los `._m_` y `._p_` se renombran | Notas: - **El recurso de cada llave debe existir** (también en `mkdir`: la llave es la carpeta donde se crea). - `to` es la carpeta de destino **desde la raíz del sitio** (`/archivo/2026`), no relativa a la URL. Si no existe, se intenta crear; por el mismo defecto que en `upl.fso`, eso falla hoy (`No está autorizado para crear la estructura de directorios`): cree antes la carpeta. - `copy`, `move` y `rename` solo operan con archivos; con una carpeta responden `Not implemented`. - **Si el destino ya tiene un archivo con ese nombre, se sobrescribe** (comprobado con `copy` y `rename`). La documentación 1.0 decía que la acción fallaba. ```json { ".": { "action": "mkdir", "path": "reportes/2026" }, "borrador.txt": { "action": "delete" }, "datos.csv": { "action": "copy", "to": "/respaldos" }, "viejo.csv": { "action": "move", "to": "/archivo/2025" }, "informe_final.pdf": { "action": "rename", "as": "informe_2026.pdf" }, "temporal": { "action": "delete" } } ``` Llamado en `/documentos/do.fso`, la primera llave crea `/documentos/reportes/2026`. ```bash curl -X POST -H "Authorization: Bearer MI_TOKEN" \ -H "Content-Type: application/json;charset=utf-8" \ -d '{ ".": { "action": "mkdir", "path": "reportes/2026" } }' \ "https://sitio.ejemplo.com/documentos/do.fso" ``` Respuesta real de una llamada con varias acciones: ```json {"success":1,"data":{".":{"done":1},"nuevo.txt":{"done":1},"informe.pdf":{"done":1}, "reportes":{"done":0,"message":"{0} Not implemented[Ln= 13]"}, "zzz.txt":{"done":0,"message":"{0} Resource not found[Ln= 81]"}, "notas.txt":{"done":0,"message":"{0} Command invalid[Ln= 136]"}}} ``` (`reportes` era una carpeta con `copy`; `zzz.txt` no existía; `notas.txt` traía una acción inválida.) **Privilegios** sobre el recurso de cada llave: | Acción | Privilegio específico | También lo dan | |---|---|---| | `mkdir` | `dkl_fso_mkdir` | `write`, `admin` | | `delete` | `dkl_fso_delete` | `write`, `admin` | | `copy` | `dkl_fso_copy` | `write`, `admin` | | `move` | `dkl_fso_move` | `write`, `admin` | | `rename` | `dkl_fso_rename` | `write`, `admin` | Además, `copy`, `move` y `rename` requieren sobre la **carpeta de destino** (en `rename`, la del archivo): `dkl_fso_upload`, `write` o `admin`; si el origen o el nombre final tienen extensión peligrosa, `dkl_fso_danger`, `write` + `plus` o `admin`; y si hay que crear la carpeta, `dkl_fso_mkdir`, `write` o `admin`. ## zip.fso `zip.fso` (programa `fso.zip.dkl`) es hoy una **copia anterior de `do.fso`**: acepta las mismas acciones con el mismo cuerpo, salvo que su `delete` de carpetas solo borra carpetas vacías (`Directory not empty`, comprobado). No comprime ni descomprime: para descomprimir al subir use el campo `.zip*` de `upl.fso`, y para crear o extraer archivos zip desde su código use [zip.dkh](/es/devkron/2.0/bibliotecas/estandar/zip.md). Use `do.fso` en lugar de `zip.fso`.