> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Carpetas y herramientas

> Organiza wokus y herramientas NPS, CSAT y CES en un solo árbol de carpetas: busca, compara cifras por tipo, mueve en lote y obtén el reporte y el CSV de una carpeta por API, SDK o MCP

Una **carpeta** agrupa wokus y herramientas NPS, CSAT y CES **en un mismo árbol**. Puedes anidar carpetas dentro de carpetas, mover cualquier herramienta entre ellas y mirar una carpeta completa como una sola unidad: sus cifras, su reporte y un CSV con todas sus respuestas.

Esta guía cubre cómo lo haces desde la API v1, los SDK oficiales y el servidor MCP. Los tres usan el mismo modelo.

## Cómo funciona

* Una **carpeta** tiene un nombre, un color opcional y, si está anidada, una carpeta padre. La **raíz** es el nivel sin carpeta.
* Cada **herramienta** (woku, NPS, CSAT o CES) vive en una sola carpeta o en la raíz. Las herramientas existentes siguen en la raíz hasta que las muevas.
* Al **eliminar una carpeta** no se elimina nada de lo que contiene: sus subcarpetas, wokus y herramientas suben a la carpeta padre (o a la raíz).
* Mover es siempre reversible y no cambia las respuestas ni los enlaces públicos de una herramienta.

<Note>
  Los cuatro tipos usan escalas distintas (estrellas de 1 a 5, NPS de 0 a 10, CSAT y CES de 1 a 5), por eso woku **nunca los promedia entre sí**. Cada tipo muestra su cifra principal en su escala nativa.
</Note>

## En la aplicación

En woku, la vista **Herramientas** muestra el mismo árbol: carpetas arriba y, debajo, wokus y herramientas NPS, CSAT y CES con su cifra principal. Se puede ver en **Rejilla** o en **Lista**, filtrar por tipo y buscar en toda la empresa (también por **trackers**, ver más abajo). Puedes crear carpetas con color, arrastrar herramientas a una carpeta o usar **Mover a...**, y cada carpeta tiene su menú para editarla, eliminarla, configurar sus alertas y su acceso por WhatsApp, y abrir su reporte.

El **reporte de una carpeta** tiene dos pestañas:

* **Análisis de texto** (la principal): el análisis con IA de todos los comentarios de la carpeta y sus subcarpetas, con la misma forma que el reporte de un woku (reconocimientos, oportunidades de mejora, nube de palabras y resumen). Mientras se genera, una barra de avance muestra que el reporte sigue en camino.
* **Métricas por herramienta**: cuatro tarjetas (una por tipo, cada una en su escala) con el cambio frente al periodo anterior, la evolución del resultado en el tiempo, la distribución de notas, de dónde vienen las respuestas y las herramientas que conviene atender primero. Se puede ver el historial completo o los últimos 7, 30 o 90 días.

Todo lo que ves en la aplicación está disponible también por API, SDK y MCP, salvo el acceso por WhatsApp de una carpeta, que por ahora se configura solo desde la aplicación.

## Carpetas

Usa `/v1/folders` para administrar el árbol.

| Operación | Endpoint |
| - | - |
| Listar carpetas (todas, o las subcarpetas de una) | `GET /v1/folders` |
| Crear una carpeta | `POST /v1/folders` |
| Obtener una carpeta con sus estadísticas | `GET /v1/folders/:id` |
| Renombrar, cambiar el color o definir los números de alerta de WhatsApp | `PATCH /v1/folders/:id` |
| Mover una carpeta (o enviarla a la raíz) | `PATCH /v1/folders/:id/move` |
| Eliminar una carpeta (su contenido sube al padre) | `DELETE /v1/folders/:id` |

Cada carpeta incluye su ruta (`path`, por ejemplo `Posventa > Entrega`) y las estadísticas de su subárbol: cuántas herramientas hay de cada tipo, cuántas subcarpetas y cuántas reseñas.

```bash theme={null}
curl --request POST https://clientapi.woku.app/v1/folders \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Posventa", "color": "#3498db" }'
```

Para anidar una carpeta, envía `parentFolderId`. Para mover una carpeta a la raíz, usa `PATCH /v1/folders/:id/move` con `{ "parentFolderId": null }`. Una carpeta no puede moverse dentro de sí misma ni de una de sus subcarpetas.

## Crear una herramienta dentro de una carpeta

Las creaciones de NPS, CSAT y CES aceptan `folderId` (los wokus siguen usando su propio flujo de creación y se mueven con `PATCH /v1/wokus/:id/move`). La carpeta debe ser de tu empresa; si no, la respuesta es `404`.

```bash theme={null}
curl --request POST https://clientapi.woku.app/v1/csat-tools \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "name": "Entrega", "question": "¿Qué tan satisfecho/a estás con la entrega?", "folderId": "<id de la carpeta>" }'
```

Para mover una herramienta que ya existe: `PATCH /v1/nps-tools/:id/move`, `PATCH /v1/csat-tools/:id/move` o `PATCH /v1/ces-tools/:id/move`, con `{ "folderId": "<id>" }` o `{ "folderId": null }` para la raíz. Todas las herramientas devuelven su `folderId` (`null` en la raíz).

## Buscar y listar herramientas

`GET /v1/tools` devuelve en una sola lista las carpetas y las herramientas de **todos los tipos**, paginadas por cursor.

| Parámetro | Qué hace |
| - | - |
| `folderId` | Lista el contenido directo de esa carpeta. Sin él, lista la raíz. |
| `scope=company` | Lista todas las herramientas de la empresa en una lista plana. |
| `q` | Busca en nombres y preguntas, sin distinguir mayúsculas ni acentos. La búsqueda abarca toda la empresa y también devuelve las carpetas que coinciden. |
| `types` | Filtra por tipo: `woku`, `nps`, `csat`, `ces` (separados por coma). |
| `sort` | `name` (por defecto), `-name`, `created` o `-created`. |
| `createdFrom`, `createdTo` | Rango de fechas de creación. |
| `trackers` | Chips de trackers, repetibles (`?trackers=TRR:00482&trackers=OC:2024`). Una herramienta coincide cuando tiene **todos**: el nombre del tracker se compara exacto y el valor de forma parcial y sin distinguir mayúsculas (`482` también coincide con `00482`). Máximo 10 chips. Como una búsqueda, abarca toda la empresa y no lista carpetas. Un tracker que la empresa no tiene no coincide con nada, y un chip sin nombre o sin valor responde `400`. |
| `limit`, `cursor` | Tamaño de página (hasta 100) y cursor de la página siguiente (`nextCursor`). |
| `foldersLimit`, `foldersCursor` | "Ver más" de carpetas: `foldersLimit` (1 a 100) pagina las carpetas del nivel; sin él se devuelven todas. Con `foldersCursor` (el `foldersNextCursor` anterior) se devuelve solo esa página de carpetas, sin herramientas. |

La respuesta trae `folders`, `foldersNextCursor`, `tools`, `nextCursor` y `facets` (cuántas herramientas hay de cada tipo con los filtros aplicados). Cada herramienta incluye `type`, `name`, `folderId`, `reviewCount`, `lastResponseAt` y su cifra principal en escala nativa (`headline`).

## Cifras por tipo

`GET /v1/tools/stats` entrega, para toda la empresa o para una carpeta y sus subcarpetas (`folderId`), las reseñas y la cifra principal de cada tipo, opcionalmente dentro de un periodo (`from`, `to`):

| Tipo | Cifra principal |
| - | - |
| Woku | Promedio de estrellas (1 a 5) |
| NPS | Puntaje NPS (de -100 a 100), con promotores, pasivos y detractores |
| CSAT | Porcentaje de satisfechos (puntajes 4 y 5) |
| CES | Promedio de esfuerzo (1 a 5) |

Un tipo sin respuestas devuelve `null` como cifra. Si un tipo falla al calcularse, informa `{ "error": true }` y los demás siguen siendo válidos.

## Métricas por herramienta de una carpeta

`GET /v1/folders/:id/metrics` entrega, para una carpeta y sus subcarpetas, las cifras de **cada** herramienta (woku, NPS, CSAT y CES) en un periodo, comparadas con el periodo anterior de la misma duración.

| Parámetro | Qué hace |
| - | - |
| `days` | Periodo en días: `7`, `30` (por defecto) o `90`. Con `0` se calcula todo el historial y `previous` viene vacío (`count: 0` y cifras `null`). |

La respuesta trae:

* `tools`: una fila por herramienta con `type`, `id`, `name`, `totalResponses`, `lastResponseAt` y dos ventanas, `current` y `previous`, cada una con `count`, `headline` (la cifra en su escala nativa), `positive` y `negative` (porcentaje de respuestas positivas y negativas: 4 y 5 o 1 y 2, o promotores y detractores en NPS) y los conteos crudos `positiveCount`, `negativeCount` y `scoreSum` para combinar herramientas sin error de redondeo.
* `daily`: las sumas diarias (en UTC) de ambos periodos por tipo (`count`, `scoreSum` y los conteos `positive` y `negative`), para dibujar una tendencia con cualquier agrupación. Las ventanas son días calendario UTC que terminan hoy, así que sumar `daily` del periodo da `current.count`.
* `distribution`: cuántas respuestas hubo por nota en el periodo. En NPS la posición 0 es la nota 0 (11 posiciones); en el resto la posición 0 es la nota 1 (5 posiciones).

Las escalas nunca se mezclan entre tipos. Una herramienta sin respuestas devuelve `null` como cifra. En el MCP, `get_folder_tools_metrics` devuelve `toolCount` y las herramientas con más respuestas (`limit`, 50 por defecto), y las sumas diarias solo con `includeDaily`.

```bash theme={null}
curl "https://clientapi.woku.app/v1/folders/FOLDER_ID/metrics?days=30" \
  --header "Authorization: Bearer $WOKU_API_KEY"
```

## Mover en lote

`POST /v1/tools/move` mueve hasta 200 elementos de tipos mezclados en una sola llamada. Es idempotente: mover elementos adonde ya están funciona sin error. Si falta un elemento o la carpeta de destino, no se mueve nada.

```json theme={null}
{
  "items": [
    { "type": "csat", "id": "<id de la herramienta>" },
    { "type": "woku", "id": "<id del woku>" },
    { "type": "folder", "id": "<id de una carpeta>" }
  ],
  "folderId": null
}
```

Usa `"folderId": null` para enviar los elementos a la raíz.

## Reporte, PDF y CSV de una carpeta

* `GET /v1/folders/:id/report` genera (y guarda) un reporte con IA sobre **todas** las herramientas de la carpeta y sus subcarpetas: reconocimientos, oportunidades de mejora, nube de palabras y resumen. Cada cita conserva el contexto de su herramienta. Como las escalas son distintas, el reporte no incluye una distribución de puntajes. Un reporte ya generado se reutiliza mientras no cambie la cantidad de reseñas; usa `regenerate=true` para forzar uno nuevo y `lang=es` o `lang=en` para el idioma. Una carpeta sin herramientas, o con menos de dos respuestas con comentario, devuelve un reporte vacío, no un error.
* `GET /v1/folders/:id/pdf` descarga el reporte en un archivo PDF (`lang=es` o `lang=en`), con un desglose por tipo de herramienta (cantidad, respuestas y cifra principal en su escala nativa). No incluye distribución de puntajes. Es un archivo binario: está en la API y los SDK, y no en el servidor MCP.
* `GET /v1/folders/:id/csv` descarga un archivo CSV con **una fila por respuesta** de todas las herramientas de la carpeta y sus subcarpetas: carpeta y ruta, tipo y nombre de la herramienta, puntaje con su escala, comentario, tipo de comentario (texto o audio), clasificación (reconocimiento o mejora), correo del cliente, canal y fecha. Un cliente que ya no existe deja la celda vacía, y una respuesta anónima aparece como `Anónimo`.

## Alertas de WhatsApp por carpeta

Una carpeta puede avisar por WhatsApp cuando llega un comentario clasificado como **oportunidad de mejora** en cualquiera de sus herramientas: wokus, NPS, CSAT o CES. Los destinatarios son los números configurados en la carpeta.

```bash theme={null}
curl --request PATCH https://clientapi.woku.app/v1/folders/FOLDER_ID \
  --header "Authorization: Bearer $WOKU_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "whatsappAlertRecipients": [{ "whatsappId": "56912345678", "name": "Ana" }] }'
```

* `whatsappAlertRecipients` **reemplaza** la lista anterior (máximo 10); envía `[]` para quitar todos los números. El número va en formato E.164 sin el `+`.
* Cada número puede llevar `sources` (`woku`, `nps`, `csat`, `ces`): los tipos de comentario que lo avisan. Si no lo envías, avisa por los cuatro. Los números que ya existían antes de esta función siguen recibiendo solo alertas de wokus.
* Un número de una carpeta también recibe los avisos de las herramientas de sus subcarpetas, una sola vez aunque esté en varias.
* Cada carpeta devuelve la lista en `whatsappAlertRecipients`.
* Para que un viaje que crea una herramienta por pedido no sature a nadie, cada número recibe como máximo **5 avisos de herramientas por hora**; los siguientes se descartan.
* El aviso se envía **una sola vez por respuesta** y cuenta como una notificación de WhatsApp de tu plan. Incluye la empresa, la herramienta con su carpeta, el cliente, el comentario y el puntaje en su escala.
* En el MCP, `update_folder` acepta el mismo campo.

## Viajes en carpetas

Cada viaje del cliente crea sus propias herramientas CSAT, CES y NPS, y miles de ellas si el viaje crea una por pedido. Para que no queden sueltas en la raíz, woku puede ordenarlas solas en el árbol **Viajes > viaje > momento**.

* La organización es **opcional por empresa**. Se activa una vez y desde entonces las herramientas nuevas de cada momento se ubican en la carpeta de su momento.
* Al activarla, una **pasada única en segundo plano** mueve las herramientas de los viajes existentes que aún no tienen carpeta. Es repetible sin efectos: no toca lo que ya tiene carpeta y una segunda corrida no cambia nada.
* Si mueves una herramienta a otra carpeta, **no vuelve sola** a su sitio. Mover o renombrar las carpetas del árbol nunca rompe un viaje: el siguiente caso sigue creando su herramienta en la carpeta de su momento, donde esté ahora.
* Las integraciones ordenan sus propias carpetas de la misma manera (por ejemplo, Shopify y Pancake).

| Operación | Endpoint |
| - | - |
| Ver el estado (si está activa, si está en curso y cuánto falta) | `GET /v1/journey-folders` |
| Activar y ejecutar la pasada única (responde `202`; `409` si ya está en curso) | `POST /v1/journey-folders/organize` |

El estado incluye `enabled`, `enabledAt`, `organizedAt`, `organizing` y `pending` (viajes y herramientas que siguen sin carpeta). Consúltalo de vez en cuando mientras `organizing` sea `true`.

```bash theme={null}
curl --request POST https://clientapi.woku.app/v1/journey-folders/organize \
  --header "Authorization: Bearer $WOKU_API_KEY"
```

`GET /v1/journeys` y `GET /v1/journeys/:id` devuelven `folderId` (la carpeta del viaje) y `momentFolders` (la carpeta de cada momento, por su clave). Antes de organizar, `folderId` es `null` y `momentFolders` es `{}`. Las carpetas que crea woku (la raíz `Viajes`, cada viaje, cada momento y las de integraciones) informan su `origin` en `GET /v1/folders` y `GET /v1/tools`: `journeys-root`, `journey`, `journey-moment` o `integration`. Las carpetas de integraciones informan además `integrationProvider` (por ejemplo `shopify` o `pancake`). Tus propias carpetas tienen `origin: null`.

```ts theme={null}
const status = await woku.journeyFolders.status();
if (!status.enabled) await woku.journeyFolders.organize();
const journey = await woku.journeys.get(journeyId);
console.log(journey.folderId, journey.momentFolders);
```

En el servidor MCP, `get_journey_folders_status` y `organize_journey_folders` hacen lo mismo, y `get_journey` y `list_journeys` incluyen `folderId` y `momentFolders`.

## SDK y MCP

<CodeGroup>
  ```ts JavaScript theme={null}
  const folder = await woku.folders.create({ name: 'Posventa' });
  await woku.csatTools.create({ name: 'Entrega', question: '¿Qué tan satisfecho/a estás?', folderId: folder.id });

  for await (const tool of await woku.tools.list({ folderId: folder.id, types: ['csat', 'nps'] })) {
    console.log(tool.type, tool.name, tool.headline.value);
  }
  const stats = await woku.tools.stats({ folderId: folder.id });
  await woku.tools.move({ items: [{ type: 'csat', id: toolId }], folderId: null });
  const csv = await woku.folders.csv(folder.id);
  const pdf = await woku.folders.pdf(folder.id, { lang: 'es' }); // Uint8Array
  const metrics = await woku.folders.metrics(folder.id, { days: 30 }); // por herramienta, frente al periodo anterior
  const tagged = await woku.tools.list({ trackers: ['TRR:00482'] });
  ```

  ```python Python theme={null}
  folder = woku.folders.create({"name": "Posventa"})
  woku.csat_tools.create({"name": "Entrega", "question": "¿Qué tan satisfecho/a estás?", "folderId": folder["id"]})

  for tool in woku.tools.list({"folderId": folder["id"], "types": ["csat", "nps"]}):
      print(tool["type"], tool["name"], tool["headline"]["value"])
  stats = woku.tools.stats({"folderId": folder["id"]})
  woku.tools.move({"items": [{"type": "csat", "id": tool_id}], "folderId": None})
  csv_text = woku.folders.csv(folder["id"])
  pdf_bytes = woku.folders.pdf(folder["id"], {"lang": "es"})
  metrics = woku.folders.metrics(folder["id"], {"days": 30})  # por herramienta, frente al periodo anterior
  tagged = woku.tools.list({"trackers": ["TRR:00482"]})
  ```
</CodeGroup>

Referencia completa en [SDK de JavaScript](/docs/development/sdk-javascript) y [SDK de Python](/docs/development/sdk-python).

En el servidor MCP, un agente cuenta con `search_voc_tools` (con `trackers`), `get_voc_tools_stats`, `get_folder_tools_metrics`, `move_voc_tools`, `create_folder`, `update_folder`, `move_folder` y `delete_folder`. `get_folder_report` acepta `scope: "all"` para el reporte mixto y `format: "csv"` para las respuestas, y `create_nps_tool`, `create_csat_tool` y `create_ces_tool` aceptan `folderId`. El playbook `organize_listening` de `woku_guide` guía el proceso. Consulta [Herramientas del MCP](/docs/mcp/tools).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.