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

> Conecta Sperant, el CRM inmobiliario, con woku y encuesta a cada cliente después de su visita a un proyecto, ordenado por vendedor y equipo de ventas

El **conector Sperant de woku** convierte cada **visita registrada en Sperant** en una reseña
woku sobre la asesoría del vendedor. woku invita al cliente por **WhatsApp o email**, ordena las
reseñas en carpetas por **equipo de ventas** y por **vendedor**, y deja listos los **tickets de
soporte** y los **planes de acción** por equipo. No modifica nada en tu cuenta de Sperant: solo lee
los vendedores, proyectos y clientes que necesita para crear cada reseña.

## Qué es una visita

Sperant avisa a woku de **todos** sus eventos, pero solo dos cuentan como visita:

| Evento de Sperant | Cuenta como visita cuando |
| - | - |
| **Cliente nuevo** (`client_created`) | Su canal de entrada es uno de los configurados (por defecto **Visita Presencial**) |
| **Actividad manual** (`activity_manual_created`) | Su tipo de interacción es uno de los configurados (por defecto **Visita al proyecto** y **Visita a oficinas**) |

Los valores se comparan sin distinguir mayúsculas ni tildes, y los editas en la sección
**Visitas** de la integración. Cualquier otro evento se recibe y se ignora.

## Cómo funciona

1. Un vendedor registra en Sperant una visita a un proyecto (un cliente nuevo que llega en
   persona o una actividad de visita).
2. Sperant avisa a woku. woku lee en Sperant el nombre del **vendedor**, el **proyecto** y, en una
   actividad, el teléfono y el email del **cliente**.
3. woku crea una reseña con el texto **"Asesoría brindada por (vendedor) en el proyecto
   (proyecto)"** y la **foto del vendedor**, dentro de la carpeta del vendedor, que está dentro de
   la carpeta de su equipo.
4. woku invita al cliente de inmediato: por **WhatsApp** si tiene un teléfono válido, o por
   **email** si no. Sin teléfono ni email, la reseña se crea igual, pero no se envía.
5. La respuesta llega como cualquier otra reseña y alimenta tus métricas, los tickets de soporte y
   los planes de acción de su equipo.

Cada visita se procesa **una sola vez**: si Sperant reintenta el mismo aviso, woku no crea una
segunda reseña ni envía una segunda invitación.

## Cómo conectar

**1. Pega tu API key de Sperant**

En **Empresa → Integraciones → Sperant**, pega la **API key** de tu cuenta de Sperant, elige el
idioma de las invitaciones y presiona **Conectar**. woku valida la clave contra Sperant antes
de guardarla.

**2. Configura el webhook en Sperant**

Al conectar, woku te muestra **una sola vez** el **token** del webhook, junto con la URL
`https://api.woku.app/integrations/sperant/webhooks`. Configura el webhook de tu cuenta de
Sperant con esa URL y ese token: Sperant envía el token en cada aviso y así woku sabe que el
aviso es tuyo.

**3. Ordena tus equipos y vendedores**

Crea tus **equipos de ventas** y asigna cada vendedor a su equipo (ver abajo). Los vendedores
aparecen solos con su primera visita, o puedes traerlos de una vez con **Traer vendedores de
Sperant**.

> [!WARNING]
>
> El token se muestra **una sola vez**. Si lo pierdes, presiona **Generar un token nuevo** en la
> sección Conexión: el anterior deja de funcionar de inmediato, así que actualízalo también en
> Sperant.

## Equipos y vendedores

### Equipos

En la sección **Equipos** creas, renombras, ordenas y quitas tus equipos de ventas. Cada equipo
tiene:

* su **carpeta**, donde quedan las carpetas de sus vendedores;
* su **grupo de planes de acción**, que genera un borrador de plan cada **30 oportunidades de
  mejora** nuevas de ese equipo;
* opcionalmente, su propio **destino de soporte**: si agregas correos al equipo, los tickets de
  las reseñas de ese equipo llegan a esos correos en vez de al destino general de la integración.

Quitar un equipo **desactiva** su grupo y su destino (no los elimina) y deja a sus vendedores
**sin equipo**.

### Vendedores

En la sección **Vendedores** ves a cada vendedor con su foto, su rol en Sperant y su última visita.
Ahí le asignas un **equipo** y le subes una **foto**, que es la imagen de sus reseñas (si no tiene,
se usa la imagen del momento o el logo de tu empresa). El filtro **Por asignar** muestra a los
vendedores sin equipo.

Un vendedor nuevo, que todavía no tiene equipo, **no pierde sus visitas**: sus reseñas se crean en
la carpeta **Sin equipo**. Cuando le asignas un equipo, su carpeta se mueve bajo la del equipo y
sus reseñas, **las pasadas y las futuras**, pasan a contar para ese equipo en los planes de acción
y en los tickets de soporte. Ese traspaso corre en segundo plano y toma unos minutos.

## Organización en carpetas

```
📁 Equipo Norte          (carpeta del equipo)
├── 📁 Ana Pérez         (reseñas de sus visitas)
└── 📁 Luis Rojas
📁 Sin equipo
└── 📁 Vendedor nuevo
```

## El viaje

En **Viaje de visitas** ves el momento **Visita**: la reseña que se envía apenas Sperant registra
la visita. Puedes desactivarlo, elegir el **canal** (WhatsApp y luego email, o solo email),
escribir tu propio **mensaje** en español e inglés (usa `{seller}` y `{project}` para incluir el
vendedor y el proyecto) y subir una **imagen** para los vendedores sin foto.

> [!NOTE]
>
> La definición del viaje es **tuya**: una vez que guardas tus cambios, woku deja de sobrescribirla
> con los valores por defecto.

## Tickets de soporte y planes de acción

Al conectar Sperant, woku crea **una sola vez** dos recursos llamados **Integración Sperant**:

| Recurso | Qué hace |
| - | - |
| **Destino de soporte** (tipo email) | Recibe los [tickets a SAC](https://woku.app/docs/guides/support-tickets.md) de las reseñas que ameritan atención, cuando su equipo no tiene correos propios. Llegan al email de la persona que conectó Sperant. |
| **Grupo de planes de acción** | Escucha las reseñas de todos los equipos y, cuando acumula **100 oportunidades de mejora** nuevas, genera un [borrador de plan de acción](https://woku.app/docs/action-plans/create-plan.md). |

Además, cada **equipo** suma su propio grupo de planes (30 mejoras) y, si le agregas correos, su
propio destino de soporte, que tiene prioridad sobre el de la integración.

> [!NOTE]
>
> Los destinos y los grupos son **tuyos**: puedes editarlos (sumar correos o encargados, cambiar el
> umbral), desactivarlos o eliminarlos desde **Soporte** y **Planes de acción**. woku solo actualiza
> el nombre de un equipo que renombras y los correos que editas en la sección Equipos, y desactiva
> los de un equipo que quitas.

## Qué datos usa woku

* **Del aviso de Sperant**: el tipo de evento, el vendedor, el proyecto, el canal de entrada o el
  tipo de interacción, y el teléfono y el email del cliente nuevo.
* **De la API de Sperant**: el nombre del vendedor, el nombre del proyecto y, en una actividad, el
  teléfono y el email del cliente.

Cada reseña queda etiquetada con los trackers `sperant_seller_id`, `sperant_team`,
`sperant_project_id`, `sperant_project_name` y `sperant_event`, para que puedas filtrar y agrupar
tus resultados por vendedor, equipo y proyecto.

## Preguntas frecuentes

> **¿Qué pasa con los eventos de Sperant que no son visitas?**
>
> woku los recibe y responde de inmediato, pero no crea nada. Así Sperant nunca ve un error de
> parte de woku.

> **¿Cómo pruebo la integración sin contactar clientes?**
>
> Activa el **Modo de prueba** en Ajustes: las visitas siguen creando sus reseñas, pero no se
> envía ninguna invitación. La sección **Estado** muestra el último evento recibido y la última
> visita registrada.

> **¿Qué pasa si cambio la API key en Sperant?**
>
> Pega la nueva clave en la sección **API key** de la integración. Si Sperant rechaza la clave
> guardada, woku lo avisa en la sección Estado y deja de registrar visitas hasta que la
> actualices.

> **¿Cómo desconecto Sperant?**
>
> En **Empresa → Integraciones → Sperant → Desconectar**. Se eliminan la conexión y sus
> credenciales; las reseñas, las respuestas, los grupos y los destinos ya creados **se
> conservan**. Recuerda quitar el webhook en Sperant.


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