> ## 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. # Asigna un valor de tracker a una entidad de VoC por nombre de tracker (upsert) > Idempotente. Si `(entityType, id, trackerName)` ya tiene un valor, se **sobrescribe**. El servidor resuelve el tracker por nombre dentro de la empresa del solicitante. Falla con 404 si el nombre del tracker es desconocido para la empresa, 400 si el tipo de entidad no es soportado o el tracker esta inactivo, 403 si la entidad pertenece a otra empresa. ## OpenAPI ````yaml /openapi-v1.es.json post /v1/external-trackers/{entityType}/{id} 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/external-trackers/{entityType}/{id}: post: tags: - Trackers externos summary: >- Asigna un valor de tracker a una entidad de VoC por nombre de tracker (upsert) description: >- Idempotente. Si `(entityType, id, trackerName)` ya tiene un valor, se **sobrescribe**. El servidor resuelve el tracker por nombre dentro de la empresa del solicitante. Falla con 404 si el nombre del tracker es desconocido para la empresa, 400 si el tipo de entidad no es soportado o el tracker esta inactivo, 403 si la entidad pertenece a otra empresa. operationId: v1AssignEntityExternalTracker parameters: - name: entityType in: path required: true description: >- Tipo de entidad de VoC que lleva el valor de tracker. `woku` no se permite aqui; usa las rutas dedicadas `/v1/external-trackers/wokus/{wokuId}`. schema: type: string enum: - nps - csat - ces - form - flow example: nps - name: id in: path required: true description: ObjectId de MongoDB de la entidad de VoC. schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 507f1f77bcf86cd799439abc requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignExternalTrackerRequest' examples: trr: summary: Etiqueta una respuesta de NPS con un id de transaccion de CRM value: name: trr value: TX-2026-00043 sku: summary: Etiqueta una respuesta de CES con un SKU de producto value: name: sku value: WK-PRO-2024-BLUE responses: '201': description: Valor asignado (creado) o actualizado content: application/json: schema: $ref: '#/components/schemas/V1EntityExternalTrackerValue' '400': description: Tipo de entidad no soportado, tracker inactivo o error de validacion content: application/json: schema: $ref: '#/components/schemas/ValidationError' '403': description: La entidad no pertenece a la empresa del solicitante content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Nombre de tracker no encontrado o entidad no encontrada content: application/json: schema: $ref: '#/components/schemas/NotFoundError' security: - BearerAuth: [] components: schemas: AssignExternalTrackerRequest: type: object required: - name - value properties: name: type: string description: >- Nombre de la definicion del tracker a nivel de empresa al que pertenece el valor. example: trr maxLength: 60 value: type: string description: Valor del identificador externo (siempre se almacena como string). example: TX-2026-00043 maxLength: 500 V1EntityExternalTrackerValue: type: object description: >- Valor de un tracker vinculado a una entidad VoC especifica (herramienta NPS/CSAT/CES, Form o Flow). El par polimorfico `(entityType, entityId)` generaliza lo que `WokuExternalTrackerValue` hace para los Wokus. required: - _id - companyId - entityType - entityId - trackerId - value properties: _id: type: string example: 507f1f77bcf86cd799439015 companyId: type: string example: 507f1f77bcf86cd799439012 entityType: type: string description: Tipo de entidad VoC que lleva este valor. enum: - nps - csat - ces - form - flow example: nps entityId: type: string description: Entidad VoC a la que pertenece este valor. example: 507f1f77bcf86cd799439abc trackerId: type: string description: Referencia a la definicion del tracker a nivel de empresa. example: 507f1f77bcf86cd799439014 value: type: string description: Identificador externo (por ejemplo, id de transaccion del CRM). example: TX-2026-00043 maxLength: 500 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 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. ````