> ## 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.

# Conector Zendesk

> Conecta tu cuenta de Zendesk con woku mediante un API token y envía tickets a tu equipo de soporte cuando una opinión lo amerita

El **conector Zendesk de woku** vincula tu cuenta de Zendesk con tu
empresa en woku usando un **API token**. Su propósito es alimentar los
**tickets a SAC** del módulo Soporte: cuando el motor detecta una
opinión negativa que amerita seguimiento, woku crea un ticket
directamente en tu Zendesk, con el contexto del cliente y de la
respuesta que lo originó.

<Note>
  La conexión se crea una sola vez y queda disponible para todos los
  destinos de tickets de tipo Zendesk de tu empresa. Los destinos no
  guardan credenciales propias: siempre referencian la conexión.
</Note>

## Antes de empezar: obtén el API token en Zendesk

<Steps>
  <Step title="Abre la configuración de API">
    En Zendesk, entra al **Admin Center** y navega a **Aplicaciones e
    integraciones → API**.
  </Step>

  <Step title="Habilita el acceso por token">
    Activa la opción de **acceso por token** (Token access). Si esta
    opción está deshabilitada en tu cuenta, woku no podrá validar la
    credencial y la conexión fallará.
  </Step>

  <Step title="Crea un API token">
    Genera un nuevo API token y cópialo. Zendesk lo muestra una sola
    vez, así que guárdalo hasta terminar la conexión en woku.
  </Step>
</Steps>

<Tip>
  Usa el email de un **agente o administrador real** de tu Zendesk. Los
  tickets que woku crea quedan a nombre de ese usuario, por lo que
  conviene que sea una cuenta activa del equipo de soporte.
</Tip>

## Crear la conexión en woku

En **Empresa → Integraciones**, ubica la tarjeta **Zendesk** y completa
tres datos:

| Campo            | Descripción                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| Subdominio       | El subdominio de tu cuenta. Acepta `acme`, `acme.zendesk.com` o la URL completa; woku lo normaliza automáticamente. |
| Email del agente | El correo del agente o administrador dueño del token.                                                               |
| API token        | El token generado en el Admin Center, de mínimo 8 caracteres.                                                       |

Antes de guardar, woku **valida la credencial en vivo** contra la API
de Zendesk (consulta tu propio usuario en `/api/v2/users/me.json` con
autenticación básica de email y token). Si el token es inválido, o tu
cuenta tiene deshabilitado el acceso por token, la creación falla y
woku te muestra el motivo.

<Note>
  Una empresa puede tener **varias conexiones Zendesk, una por
  subdominio** (los duplicados se rechazan). Es útil si operas instancias
  separadas por país o por unidad de negocio.
</Note>

## Seguridad y ciclo de vida de la conexión

* El token se guarda **cifrado** y es de **solo escritura**: la
  interfaz nunca lo vuelve a mostrar, solo una pista enmascarada.
* Para **rotar el token**, edita la conexión e ingresa el nuevo valor.
  woku lo verifica en vivo contra Zendesk antes de persistirlo; si no
  es válido, la conexión conserva el token anterior.
* El botón **Probar** re-verifica la conexión en cualquier momento y
  registra su salud. Si Zendesk responde con un error de autenticación,
  la conexión queda marcada como **requiere re-autenticación**.
* Cada conexión muestra su estado: **conectada**, **requiere
  re-autenticación** o **error**. Además puedes **habilitarla o
  deshabilitarla** sin perder la configuración, o **eliminarla** por
  completo.

## Qué hace woku con la conexión

La conexión alimenta los **destinos de tickets a SAC** del módulo
Soporte. Un destino de tipo Zendesk referencia la conexión y,
opcionalmente, un **Group ID**: el grupo de agentes de Zendesk que
recibirá los tickets de ese destino.

Cuando el motor escala una opinión negativa, woku crea el ticket en tu
Zendesk (`/api/v2/tickets.json`) con:

* **Asunto** y **descripción en HTML** con el resumen del caso.
* **Solicitante**: el nombre y el email del cliente afectado, para que
  el ticket quede asociado a la persona correcta.
* **Prioridad** mapeada según la severidad del caso: `urgent`, `high`,
  `normal` o `low`.
* **Etiquetas**: `woku`, `voc`, la herramienta de origen (woku, NPS,
  CSAT o CES) y el nivel de riesgo de fuga del cliente.
* **Grupo**: el Group ID del destino, si lo configuraste.

El enlace al ticket creado queda guardado en woku. Desde el detalle del
ticket puedes abrirlo en Zendesk con **Ver en el SAC**.

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Qué permisos necesita el token?">
    El token hereda los permisos del agente cuyo email configuraste. Para
    crear tickets basta un agente estándar; usa un administrador si tu
    cuenta restringe la creación de tickets por API.
  </Accordion>

  <Accordion title="¿Qué pasa si roto o revoco el token en Zendesk?">
    La conexión dejará de autenticar y, en la siguiente verificación,
    quedará marcada como **requiere re-autenticación**. Edita la conexión
    e ingresa el token nuevo; woku lo valida en vivo antes de guardarlo.
  </Accordion>

  <Accordion title="¿Puedo conectar más de una cuenta de Zendesk?">
    Sí. Puedes crear varias conexiones, siempre que cada una apunte a un
    **subdominio distinto**. Luego cada destino de tickets elige qué
    conexión usar.
  </Accordion>

  <Accordion title="¿Qué pasa con los tickets si elimino la conexión?">
    Los tickets ya creados **permanecen en tu Zendesk**: woku solo
    elimina la conexión y sus credenciales. Los destinos que dependían de
    ella dejan de poder enviar hasta que los apuntes a otra conexión.
  </Accordion>
</AccordionGroup>

## Siguiente paso

<Card title="Tickets a SAC" href="/docs/guias/tickets-sac" horizontal>
  Conoce el motor de escalamiento: cómo se detectan las opiniones que
  ameritan un ticket, cómo se rutean a cada destino y cómo se hace el
  seguimiento desde woku.
</Card>