> ## 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. # Agregar una tarea (borrador o plan gestionado) ## OpenAPI ````yaml /openapi-v1.es.json post /v1/action-plans/{id}/tasks openapi: 3.0.3 info: title: Woku Client API v1 description: >- API publica de Woku Client. Cambia el selector de version en la parte superior para ver la referencia v0. Esta especificacion cubre: - **Wokus**, crear wokus, obtener datos de reseñas, enviar reseñas de texto/voz, compartir por correo. - **Empresas**, `GET /companies/me` devuelve la empresa que hace la llamada. - **Reportes**, reportes NPS a nivel de empresa y por herramienta. - **Trackers externos**, etiqueta tus Wokus con identificadores de sistemas de terceros (id de transaccion de CRM, id de orden de ERP, etc.) y buscalos despues. - **Destinos de tickets**, configura las plataformas de SAC (Zendesk, Salesforce, Slack), un servicio HTTP personalizado o direcciones de correo que reciben tickets de soporte clasificados por IA, y las condiciones de tracker que enrutan un ticket a uno de ellos. - **Grupos de planes de accion**, define que feedback de VoC (condiciones de tracker) redacta un plan de mejora y quien es el responsable. - **Planes de accion**, lee planes redactados por IA y gestiona su ciclo de vida (aprobar, enviar a una herramienta externa o trabajarlos en el kanban gestionado de woku). ## Autenticacion Todos los endpoints requieren un token Bearer en el encabezado `Authorization`. Obten la clave de API de tu empresa desde el panel de Woku. ``` Authorization: Bearer your_api_key_here ``` ## URL base Produccion: `https://clientapi.woku.app` ## Modelo (Trackers externos) - **Definicion de tracker** (`ExternalTracker`): una entrada del catalogo por empresa como `{ name: 'trr', system: 'crm interno', description: '...' }`. La define un administrador en el panel de Woku. - **Valor de tracker** (`WokuExternalTrackerValue`): un valor de tipo cadena asociado a un par (Woku, Tracker). Varios Wokus pueden compartir el mismo valor. ## Modelo (enrutamiento / condiciones de grupo) `TicketRoutingCondition` (Destinos de tickets) y `ActionPlanGroupCondition` (Grupos de planes de accion) comparten la misma forma: una expresion booleana de filas sobre valores de `ExternalTracker`, con AND ligando mas fuerte que OR. Cada fila coincide cuando el feedback lleva `trackerId` con un valor que, para el operador `equals`, es igual a `value`, o, para el operador `any`, es cualquier valor (el tracker completo; en ese caso `value` se omite). `relationToPrevious` une una fila con la anterior (`AND` mismo grupo, `OR` inicia un grupo nuevo); la primera fila lo omite. version: 1.0.0 contact: name: Woku Support url: https://woku.app email: team@woku.app servers: - url: https://clientapi.woku.app description: Servidor de produccion security: [] tags: - name: Wokus description: >- Crear wokus, obtener datos de reseñas, enviar reseñas de texto y voz, compartir enlaces de reseñas por correo. - name: Empresas description: Endpoint de la empresa que hace la llamada. - name: Reportes description: >- Reportes NPS para la empresa que hace la llamada y herramientas NPS individuales. - name: NPS description: >- Captura calificaciones NPS (a nivel de empresa o por herramienta NPS) y obten las definiciones de herramientas NPS. - name: CSAT description: >- Captura calificaciones CSAT (satisfaccion 1-5) a nivel de empresa o por herramienta CSAT, obten definiciones de herramientas y respuestas, y envia feedback de texto y voz. - name: CES description: >- Captura calificaciones CES (esfuerzo) a nivel de empresa o por herramienta CES, obten definiciones de herramientas y respuestas, y envia feedback de texto y voz. - name: Trackers externos description: >- Etiqueta Wokus con identificadores de sistemas externos y buscalos por nombre + valor. - name: Cuarentenas description: >- Verifica si un encuestado esta actualmente en cuarentena antes de solicitarle feedback. - name: Invitaciones description: >- Distribucion de encuestas: envia encuestas NPS, forms e invitaciones de reseña de woku por correo o WhatsApp. - name: Forms description: Obten definiciones de forms y envia respuestas desde tu propia interfaz. - name: Flows description: >- Renderiza recorridos de Flow (wokus ordenados con un NPS opcional) en tu propia app. - name: Capturas description: Ingesta de capturas del SDK movil - name: Destinos de tickets description: >- Configura donde se entregan los tickets de soporte clasificados por IA (Zendesk, Salesforce, Slack, un servicio HTTP personalizado o correo simple) y el enrutamiento basado en trackers que elige un destino. - name: Grupos de planes de acción description: >- Define que feedback de VoC (condiciones de tracker) redacta un plan de accion y quienes son los responsables. - name: Planes de acción description: >- Lee planes de mejora redactados por IA y gestiona su ciclo de vida: aprobar, enviar a Jira/monday.com/ClickUp/Notion o trabajarlos dentro del kanban gestionado de woku. paths: /v1/action-plans/{id}/tasks: post: tags: - Planes de acción summary: Agregar una tarea (borrador o plan gestionado) operationId: createActionPlanTask parameters: - $ref: '#/components/parameters/ActionPlanIdPath' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateActionPlanTaskRequest' examples: default: value: text: Llamar al cliente para coordinar el retiro. responses: '201': description: Tarea agregada; devuelve el plan completo actualizado content: application/json: schema: $ref: '#/components/schemas/ActionPlan' '400': description: Texto de tarea inválido, o el plan ya tiene 100 tareas content: application/json: schema: $ref: '#/components/schemas/ValidationError' '403': description: Clave de API invalida o faltante content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Plan no encontrado content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '409': description: El plan no es un borrador ni esta en progreso content: application/json: schema: $ref: '#/components/schemas/ConflictError' security: - BearerAuth: [] components: parameters: ActionPlanIdPath: name: id in: path required: true description: ObjectId de MongoDB del plan de accion. schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 507f1f77bcf86cd799439041 schemas: CreateActionPlanTaskRequest: type: object required: - text properties: text: type: string maxLength: 160 ActionPlan: type: object properties: _id: type: string example: 507f1f77bcf86cd799439041 companyId: type: string groupId: type: string title: type: string maxLength: 200 summary: type: string description: >- Lo que dijeron los clientes (sintesis narrativa, sin numeros inventados). objective: type: string expectedImpact: type: string theme: type: string description: >- Tema detectado que aborda el plan (por ejemplo "Demoras en despacho"). tasks: type: array items: $ref: '#/components/schemas/ActionPlanTask' patterns: type: array items: $ref: '#/components/schemas/ActionPlanPattern' sources: type: array items: type: string enum: - woku - nps - csat - ces description: Fuentes de VoC con evidencia en el alcance congelado. status: type: string enum: - draft - approved - sent - canceled - delivery_error - in_progress - completed description: >- `in_progress`/`completed` son el ciclo de vida gestionado (in-house); el resto aplica a planes enviados a una herramienta externa o en espera de aprobacion. priority: type: string enum: - high - medium - low description: >- Prioridad determinista (calculada por el motor); nunca la define el LLM. evidence: $ref: '#/components/schemas/ActionPlanEvidence' generation: $ref: '#/components/schemas/ActionPlanGeneration' delivery: $ref: '#/components/schemas/ActionPlanDelivery' approvedBy: type: string approvedAt: type: string format: date-time canceledBy: type: string canceledAt: type: string format: date-time completedAt: type: string format: date-time description: Se sella cuando un plan gestionado se cierra (estado `completed`). aiGenerated: type: boolean default: true createdAt: type: string format: date-time updatedAt: type: string format: date-time ValidationError: type: object properties: statusCode: type: integer example: 400 message: oneOf: - type: string - type: array items: type: string error: type: string example: Bad Request ForbiddenError: type: object properties: statusCode: type: integer example: 403 message: type: string example: Authentication required error: type: string example: Forbidden NotFoundError: type: object properties: statusCode: type: integer example: 404 message: type: string example: External tracker not found error: type: string example: Not Found ConflictError: type: object properties: statusCode: type: integer example: 409 message: type: string example: Cannot approve a plan in status "approved" error: type: string example: Conflict ActionPlanTask: type: object description: >- Una tarea del plan. En un plan gestionado (estado `in_progress`) tambien lleva un `status` de kanban y un `assigneeId` opcional. properties: _id: type: string example: 507f1f77bcf86cd799439051 text: type: string maxLength: 160 order: type: integer status: type: string enum: - todo - in_progress - done default: todo assigneeId: type: string description: Miembro del grupo responsable de la tarea (planes gestionados). completedAt: type: string format: date-time description: >- Se sella cuando la tarea pasa a `done`, y se limpia cuando vuelve atras. ActionPlanPattern: type: object properties: key: type: string description: Clave de cluster estable del motor de review-intelligence. label: type: string mentions: type: integer description: Conteo real de menciones sobre toda la poblacion comentada. ActionPlanEvidence: type: object description: >- Snapshot de evidencia congelado: el alcance analitico exacto al momento de la generacion mas conteos deterministas. Nunca se recalcula despues de la generacion. properties: windowFrom: type: string format: date-time windowTo: type: string format: date-time description: Cota superior exclusiva de la ventana. conditionsSnapshot: type: array items: $ref: '#/components/schemas/ActionPlanGroupCondition' description: >- Copia de las condiciones del tracker del grupo al momento de la generacion. negatives: type: integer description: Items de mejora comentados dentro del alcance. positives: type: integer description: Items de reconocimiento comentados dentro del alcance. total: type: integer description: >- Items comentados dentro del alcance (los items de solo puntaje nunca cuentan como evidencia). quotes: type: array items: $ref: '#/components/schemas/ActionPlanQuote' ActionPlanGeneration: type: object description: Trazabilidad de la ejecucion del LLM que redacto el plan. properties: model: type: string promptVersion: type: string generatedAt: type: string format: date-time ActionPlanDelivery: type: object description: >- Estado de entrega a la integracion, completado por la fase de envio. `provider` es `internal` para un plan gestionado. properties: provider: type: string enum: - jira - monday - clickup - notion - internal resourceLabel: type: string description: >- Etiqueta legible del recurso de destino (proyecto/tablero/lista/pagina). externalUrl: type: string externalId: type: string tasksCreated: type: integer lastError: type: string description: Motivo de falla del conector en el ultimo intento. sentAt: type: string format: date-time sentBy: type: string ActionPlanGroupCondition: type: object description: >- Una fila de condicion: el feedback debe llevar `trackerId` con un valor que coincida segun `operator`. Las filas forman una expresion booleana (AND liga mas fuerte que OR) mediante `relationToPrevious`; el grupo cuenta un elemento de feedback cuando CUALQUIER grupo OR de sus filas coincide por completo. required: - trackerId properties: relationToPrevious: type: string enum: - AND - OR description: Une esta fila con la anterior. Se omite en la primera fila. trackerId: type: string description: Id de ExternalTracker (el catalogo de trackers de la empresa). example: 507f1f77bcf86cd799439011 operator: type: string enum: - equals - any default: equals description: >- `equals` compara el valor del tracker contra `value`. `any` coincide con cualquier valor del tracker (el tracker completo; `value` se omite). value: type: string maxLength: 200 description: >- El valor con el que el tracker debe coincidir. Requerido salvo que operator sea "any". ActionPlanQuote: type: object description: Una cita textual del cliente congelada en el snapshot de evidencia. properties: text: type: string source: type: string enum: - woku - nps - csat - ces contextLabel: type: string description: Etiqueta legible de donde proviene la cita (herramienta/operacion). occurredAt: type: string format: date-time score: type: number description: Puntaje crudo en la escala propia de la fuente. securitySchemes: BearerAuth: type: http scheme: bearer description: >- Clave de API de la empresa. Obtenla desde tu panel de Woku en Configuracion > API Keys. La misma clave usada para los endpoints v0. ````