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

# Conexión con Tokko Broker

> Cómo obtener y configurar tu API Key de Tokko Broker

# Conexión con Tokko Broker

La API Key es la credencial que permite que Tokko Plugins se comunique de forma segura con tu CRM de Tokko Broker. Sin ella, el plugin no puede sincronizar propiedades, agentes ni contactos.

## Obtener tu API Key

<Warning>
  **Importante:** El API Key de tu cuenta es **única e intransferible** y a través de ella se accede a datos sensibles de la inmobiliaria. Compártela solamente con personas o empresas de tu absoluta confianza. Para acceder a esta información necesitas contar con un **rol Administrador** dentro de la cuenta de Tokko Broker.
</Warning>

Gracias a la API Key puedes realizar integraciones con aplicaciones asociadas a Tokko Broker (como Tokko Plugins) para captar la máxima cantidad de leads posible.

### Pasos para obtenerla

<Steps>
  <Step title="Inicia sesión en Tokko Broker">
    Accede a tu cuenta en [tokkobroker.com](https://www.tokkobroker.com/) con tus credenciales de Administrador.
  </Step>

  <Step title="Ingresa en &#x22;Mi Empresa&#x22;">
    Desde el panel principal, abre la sección **Mi Empresa** ([tokkobroker.com/company](https://www.tokkobroker.com/company/)).
  </Step>

  <Step title="Haz clic en &#x22;Permisos&#x22;">
    Dentro de Mi Empresa, ingresa a la pestaña **Permisos** ([tokkobroker.com/company/permissions](https://www.tokkobroker.com/company/permissions)).
  </Step>

  <Step title="Copia el código de API Key">
    En el apartado **Api Key**, selecciona el código que aparece y cópialo. Esa cadena es la que vas a pegar en la configuración de Tokko Plugins.
  </Step>
</Steps>

<Info>
  **Guía oficial de Tokko Broker:** [¿Cómo saber cuál es la API KEY de mi cuenta?](https://dudas.tokkobroker.com/es/articles/432304-como-saber-cual-es-la-api-key-de-mi-cuenta) — incluye el video explicativo paso a paso.
</Info>

<Tip>
  Si no puedes ver la sección **Permisos** o el código de API Key, tu usuario probablemente no tiene rol de Administrador. Pídele a alguien con ese rol que te envíe la clave o te asigne los permisos correspondientes.
</Tip>

***

## Configurar la API Key en WordPress

### Ingresa tu API Key

<Steps>
  <Step title="Accede al panel de WordPress">
    Ingresa al administrador de tu sitio WordPress con un usuario con permisos de administrador.
  </Step>

  <Step title="Abre Tokko Plugins">
    En el menú lateral, selecciona **Tokko Plugins** → **Configuration**.
  </Step>

  <Step title="Busca la tarjeta API Connection">
    En la sección **Configuration** encontrarás la tarjeta **API Connection** con el campo **API Key**.
  </Step>

  <Step title="Pega tu clave">
    Pega la API Key que copiaste desde Mi Empresa → Permisos en Tokko Broker.
  </Step>

  <Step title="Guarda los cambios">
    Haz clic en **Save Settings**. El plugin mostrará un badge **Connected / Not Connected** según el estado actual.
  </Step>
</Steps>

***

## Probar la Conexión

Después de ingresar tu API Key, es importante verificar que la conexión funciona correctamente.

### Ejecutar Prueba de Conexión

<Steps>
  <Step title="Ubica el botón Test Connection">
    En la tarjeta **API Connection**, junto al campo **API Key**, verás el botón **Test Connection**.
  </Step>

  <Step title="Haz clic en el botón">
    El plugin llamará a la API de Tokko Broker usando tu clave y te mostrará el resultado inline, sin necesidad de recargar la página.
  </Step>

  <Step title="Observa el badge de estado">
    El indicador de la tarjeta cambia a **Connected** (verde) cuando la prueba es exitosa, o a **Not Connected** (rojo) si hay algún problema.
  </Step>
</Steps>

### Resultado Exitoso

Si la conexión es exitosa, verás un mensaje de confirmación y el badge pasa a **Connected**. Esto confirma que:

* Tu API Key es válida.
* El plugin puede comunicarse con la API de Tokko Broker.
* Tu cuenta está activa y responde correctamente a las peticiones.

<Info>
  El idioma de la API (`api-lang`) se determina por la configuración de tu cuenta en Tokko Broker y no se puede modificar desde el plugin. El plugin lo muestra de forma informativa.
</Info>

### Errores Comunes de Conexión

#### Error: "API Key inválida"

**Causa:** La clave ingresada no es reconocida por Tokko Broker.

**Solución:**

* Verifica que hayas copiado la clave completa sin espacios
* Asegúrate de no haber agregado espacios al principio o al final
* Vuelve a copiar la clave desde Tokko Broker
* Intenta pegar en un editor de texto primero para verificar

#### Error: "No autorizado (401)"

**Causa:** La API Key ya no es reconocida por Tokko Broker. Lo más común es que alguien la regeneró en **Mi Empresa → Permisos** y la clave que tiene el sitio quedó obsoleta.

**Solución:**

* Entra a **Mi Empresa → Permisos** en Tokko Broker y verifica cuál es la clave actual.
* Copia la cadena actual y pégala en **Tokko Plugins → Configuration → API Connection**, luego ejecuta **Test Connection**.
* Si no puedes ver la sección Permisos, tu usuario no tiene rol Administrador; pídele la clave a alguien con ese rol.
* Si el error persiste con una clave válida, contacta al soporte de Tokko Broker desde el chat del [Centro de ayuda](https://dudas.tokkobroker.com/).

#### Error: "Servidor no encontrado"

**Causa:** No se puede alcanzar el servidor de Tokko Broker.

**Solución:**

* Verifica tu conexión a internet
* Asegúrate de que Tokko Broker no está en mantenimiento
* Comprueba que no haya restricciones de firewall
* Espera unos minutos e intenta de nuevo
* Si persiste, contacta al soporte de Tokko Broker

#### Error: "Límite de solicitudes excedido (429)"

**Causa:** Has excedido el número de llamadas a la API permitidas.

**Solución:**

* Espera entre 5-15 minutos antes de intentar de nuevo
* Reduce la frecuencia de sincronización automática
* Evita hacer múltiples pruebas de conexión consecutivas
* Consulta tus límites de API en Tokko Broker

#### Error: "Conexión expirada (timeout)"

**Causa:** La solicitud tardó demasiado en completarse.

**Solución:**

* Intenta más tarde (el servidor de Tokko Broker podría estar congestionado)
* Verifica tu ancho de banda disponible
* Revisa la salud de tu servidor WordPress
* Si el problema persiste, aumenta el tiempo de espera en configuración

***

## Regenerar o Cambiar tu API Key

En Tokko Broker **hay una sola API Key activa por cuenta**. Si la regeneras, la clave anterior deja de funcionar inmediatamente, por lo que cualquier integración que siga usándola (Tokko Plugins incluido) dejará de sincronizar hasta que la actualices.

### Cuándo regenerar la clave

* **Sospecha de filtración:** si crees que la clave fue compartida o expuesta públicamente.
* **Cambio de personal:** cuando alguien con acceso ya no debería poder usarla.
* **Política de seguridad:** si tu empresa requiere rotación periódica de credenciales.

### Pasos para regenerar y actualizar

<Steps>
  <Step title="Solicita la nueva clave en Tokko Broker">
    Desde **Mi Empresa → Permisos**, genera una nueva API Key. Si no ves la opción, contacta al soporte de Tokko Broker desde el chat para que te ayuden con la regeneración.
  </Step>

  <Step title="Copia el nuevo código">
    Copia la nueva cadena de API Key desde la misma pantalla de Permisos.
  </Step>

  <Step title="Actualiza WordPress">
    En **Tokko Plugins → Configuration → API Connection**, reemplaza la clave anterior por la nueva y guarda los cambios.
  </Step>

  <Step title="Prueba la conexión">
    Ejecuta **Test Connection** para confirmar que la nueva clave responde correctamente antes de dejar el sitio desatendido.
  </Step>
</Steps>

<Warning>
  Si regeneras la clave en Tokko Broker y olvidas actualizarla en WordPress, las sincronizaciones siguientes fallarán con error de autenticación y se detendrán automáticamente por los circuit breakers del plugin.
</Warning>

***

## Qué necesita la API Key para funcionar

En Tokko Broker la API Key no expone permisos granulares configurables: **da acceso a los datos de la inmobiliaria según el rol de quien administra la cuenta**. Lo que debes verificar del lado de Tokko es:

* Que tu cuenta de Tokko Broker esté **activa** (plan vigente).
* Que existan **propiedades publicadas** que quieras sincronizar.
* Que la clave provenga de un usuario con rol **Administrador**.

Del lado del plugin, la API Key es suficiente para sincronizar propiedades, imágenes, agentes, desarrollos (emprendimientos) y recibir leads. No necesitas una clave distinta para cada función.

***

## Seguridad y Mejores Prácticas

### Protege tu API Key

<Steps>
  <Step title="Guarda en lugar seguro">
    No almacenes la clave en archivos de texto sin encriptar o en correos electrónicos
  </Step>

  <Step title="Usa variables de entorno">
    Para instalaciones avanzadas, considera usar archivo `.env` con variables de entorno
  </Step>

  <Step title="Limita el acceso">
    Solo los administradores de WordPress deben acceder a la configuración del plugin
  </Step>

  <Step title="Monitorea el uso">
    Revisa los logs de sincronización para detectar actividad inusual
  </Step>
</Steps>

### Auditoría de uso

Para revisar cómo se está usando la clave puedes:

* **Desde Tokko Plugins:** abrir el **historial de reportes** del tab Sincronización. Cada reporte indica qué sincronizaciones se hicieron (manuales, por cron o selectivas), cuántas propiedades e imágenes se procesaron y si hubo errores de autenticación.
* **Desde Tokko Broker:** si sospechas de uso indebido, contacta al soporte de Tokko desde el chat del [Centro de ayuda](https://dudas.tokkobroker.com/) para revisar la actividad de la clave y, si hace falta, regenerarla.

Si detectas accesos que no reconoces, regenera la API Key en **Mi Empresa → Permisos** y actualízala en todos los sitios/integraciones que la usen.

***

## Solucionar Problemas Avanzados

### Conexión funciona pero la sincronización falla

Si la prueba de conexión es exitosa pero las propiedades no se sincronizan:

1. Confirma que existan **propiedades publicadas y visibles** en Tokko Broker (las propiedades en borrador o archivadas no se sincronizan).
2. Revisa el **reporte de la última sincronización** desde **Tokko Plugins → Sincronización → Ver reporte** para identificar qué propiedad falló y por qué.
3. Usa la acción **"¿Por qué no veo esta propiedad?"** en el tab **Propiedades** para diagnosticar en vivo si una propiedad existe en Tokko, si está publicada en WordPress, si tiene imágenes y si tiene errores registrados.
4. Intenta una sincronización manual desde **Sincronizar ahora** para ver el progreso en tiempo real.

### Contactar al soporte

Si después de seguir estos pasos aún tienes problemas:

<Steps>
  <Step title="Reúne información">
    Ten lista la URL del sitio, el mensaje de error exacto y, si es posible, el CSV del último reporte de sincronización (disponible desde el modal de reportes).
  </Step>

  <Step title="Para dudas del lado Tokko Broker">
    Usa el chat del [Centro de ayuda de Tokko Broker](https://dudas.tokkobroker.com/) en la parte inferior derecha.
  </Step>

  <Step title="Para dudas del lado del plugin">
    Escríbenos a [soporte@tokkoplugins.com](mailto:soporte@tokkoplugins.com) describiendo qué intentabas hacer y qué error recibiste.
  </Step>
</Steps>

<Tip>
  Tener tu API Key configurada correctamente es el primer paso para que todo el plugin funcione. Si tienes dudas, no dudes en contactar al soporte.
</Tip>