Guía completa para conectarte a la API de Tokko Broker

Si trabajas en el mundo inmobiliario y usas Tokko Broker como CRM, tarde o temprano vas a necesitar conectar tu sitio web, tu app o alguna herramienta externa con los datos de Tokko. La buena noticia: Tokko tiene una API REST que te permite hacer exactamente eso. La mala: la documentación oficial es escasa y el foro de developers está lleno de preguntas sin responder.

En esta guía te explico todo lo que necesitas para dar tus primeros pasos con la API de Tokko Broker: cómo obtener tu API Key, cómo hacer tu primera llamada, qué endpoints tienes disponibles, y cómo manejar los errores más comunes. Si alguna vez te encontraste con un 401 misterioso o un 429 que no entiendes, esta guía es para ti.

Qué es la API de Tokko Broker y para qué sirve

La API de Tokko Broker es una interfaz REST que te permite acceder de forma programática a los datos de tu cuenta: propiedades, desarrollos inmobiliarios, contactos, agentes y más. Funciona sobre HTTPS y devuelve datos en formato JSON.

Con la API puedes:

  • Mostrar propiedades en tu sitio web sincronizando automáticamente desde Tokko
  • Enviar leads desde formularios de contacto directo al CRM de Tokko
  • Conectar con herramientas externas como Excel, Power BI, Zapier o tu propio sistema
  • Automatizar procesos como reportes, alertas de cambios o publicación en portales

La base de la API es:

https://www.tokkobroker.com/api/v1/

Todas las llamadas van contra esa URL, agregando el endpoint específico, tu API Key y el formato de respuesta.

Cómo obtener tu API Key

Tu API Key es el único método de autenticación de la API. No hay OAuth, no hay tokens temporales: es una key estática que se pasa como parámetro en cada request.

Para obtenerla:

  1. Inicia sesión en tu cuenta de Tokko Broker
  2. Ve a Configuración > Integraciones > API
  3. Copia tu API Key (es un string alfanumérico largo)

Si no ves la opción de API en tu cuenta, contacta al soporte de Tokko para que te la habiliten. Algunas cuentas necesitan que se activen permisos específicos, especialmente si necesitas acceso de escritura (por ejemplo para enviar leads).

Importante: Tu API Key tiene acceso a todos los datos de tu cuenta. No la expongas en código del lado del cliente (JavaScript del navegador), no la subas a repositorios públicos, y no la compartas. Trátala como una contraseña.

Tu primera llamada a la API

Vamos a hacer la llamada más simple posible: obtener una propiedad de tu cuenta para verificar que todo funciona. Te muestro cómo hacerlo con Postman, cURL, PHP y Node.js.

Con Postman

Si prefieres una interfaz gráfica, Postman es la forma más rápida de probar la API sin escribir código:

  1. Abre Postman y crea un nuevo request de tipo GET
  2. En la URL escribe: https://www.tokkobroker.com/api/v1/property/
  3. En la pestaña Params agrega:
    • key = TU_API_KEY
    • format = json
    • limit = 1
  4. Haz clic en Send

Vas a ver la respuesta JSON directamente en Postman, con formato legible y la posibilidad de explorar cada campo. Es ideal para entender la estructura de los datos antes de escribir código.

Con cURL (terminal)

bash
curl "https://www.tokkobroker.com/api/v1/property/?key=TU_API_KEY&format=json&limit=1"

Con PHP

php
<?php
$api_key = 'TU_API_KEY';
$url = "https://www.tokkobroker.com/api/v1/property/?key={$api_key}&format=json&limit=1";$response = file_get_contents($url);
$data = json_decode($response, true);

echo «Total de propiedades: » . $data[‘meta’][‘total_count’] . «\n»;
echo «Primera propiedad: » . $data[‘objects’][0][‘publication_title’] . «\n»;

Con JavaScript (Node.js)

javascript
const apiKey = 'TU_API_KEY';
const url = `https://www.tokkobroker.com/api/v1/property/?key=${apiKey}&format=json&limit=1`;const response = await fetch(url);
const data = await response.json();

console.log(`Total de propiedades: ${data.meta.total_count}`);
console.log(`Primera propiedad: ${data.objects[0].publication_title}`);

Si todo está bien, vas a recibir una respuesta JSON con esta estructura:

json
{
"meta": {
"limit": 1,
"offset": 0,
"total_count": 342
},
"objects": [
{
"id": 12345,
"publication_title": "Departamento 3 ambientes en Palermo",
"address": "Av. Santa Fe 3200"
}
] }

El objeto meta te dice cuántas propiedades totales hay y cómo está paginada la respuesta. El array objects contiene las propiedades en sí.

Endpoints principales

La API de Tokko expone varios endpoints. Estos son los que vas a usar más seguido:

Endpoint Método Descripción
/api/v1/property/ GET Listar propiedades con paginación
/api/v1/property/{id}/ GET Obtener una propiedad específica
/api/v1/property/search/ POST Buscar propiedades con filtros
/api/v1/development/ GET Listar desarrollos inmobiliarios
/api/v1/development/{id}/ GET Obtener un desarrollo específico
/api/v1/webcontact/ POST Enviar un lead/contacto al CRM
/api/v1/contact/ GET Consultar contactos existentes
/api/v1/user/ GET Consultar usuarios/agentes
/api/v1/location/quicksearch/ GET Buscar ubicaciones para filtros

Parámetros comunes

Todos los endpoints GET aceptan estos parámetros:

  • key — Tu API Key (obligatorio)
  • format — Siempre json
  • limit — Cantidad de resultados por página (default: 20, máximo recomendado: 50)
  • offset — Desde qué resultado empezar (para paginación)
  • lang — Idioma de la respuesta (es, en, pt)

Ejemplo de paginación

Para recorrer todas las propiedades, necesitas paginar con limit y offset:

php
<?php
$api_key = 'TU_API_KEY';
$limit = 50;
$offset = 0;
$all_properties = [];do {
$url = «https://www.tokkobroker.com/api/v1/property/?key={$api_key}&format=json&limit={$limit}&offset={$offset}»;
$response = file_get_contents($url);
$data = json_decode($response, true);

$all_properties = array_merge($all_properties, $data[‘objects’]);
$offset += $limit;

// Esperar entre llamadas para no exceder rate limits
sleep(1);
} while ($offset < $data[‘meta’][‘total_count’]);

echo «Propiedades descargadas: » . count($all_properties) . «\n»;

Tip: Si solo necesitas saber qué propiedades cambiaron desde la última sincronización, puedes usar el parámetro fields=id,deleted_at para traer una respuesta mucho más ligera y luego descargar solo las que cambiaron.

Errores comunes y cómo resolverlos

Este es el punto donde la mayoría se atora. La API de Tokko devuelve códigos HTTP estándar, pero los mensajes no siempre son claros. Aquí van los más frecuentes:

401 Unauthorized

json
{"detail": "Authentication credentials were not provided."}

Causa: Tu API Key es inválida, está vacía, o no la estás enviando correctamente.

Solución:

  • Verifica que el parámetro se llame key (no api_key, no token)
  • Verifica que no haya espacios en blanco al copiar la key
  • Confirma que la key no haya sido revocada desde el panel de Tokko

403 Forbidden

Causa: Tu cuenta no tiene permisos para acceder a ese endpoint. Esto es común con endpoints de escritura.

Solución: Contacta a soporte de Tokko y pídeles que habiliten los permisos de API necesarios para tu cuenta.

405 Method Not Allowed

Causa: Estás usando el método HTTP equivocado. El error más común es hacer GET a /property/search/ que requiere POST.

Solución:

  • /property/ usa GET para listar
  • /property/search/ usa POST con un body JSON para buscar con filtros
  • /webcontact/ usa POST para enviar leads

429 Too Many Requests

Causa: Excediste el límite de llamadas por unidad de tiempo (rate limit).

Solución:

  • Agrega delays entre llamadas (1-2 segundos entre cada una)
  • Reduce la frecuencia de sincronización
  • Usa paginación con limit=50 en vez de hacer muchas llamadas de limit=5
  • Implementa reintentos con backoff exponencial (espera cada vez más entre reintentos)

500 / 502 / 503 — Error del servidor

Causa: La API de Tokko está temporalmente caída o con problemas.

Solución: Estos errores son transitorios. Implementa una lógica de reintentos:

php
<?php
function tokko_api_request($url, $max_retries = 3) {
for ($attempt = 1; $attempt <= $max_retries; $attempt++) {
$response = wp_remote_get($url, ['timeout' => 20]);if (!is_wp_error($response)) {
$code = wp_remote_retrieve_response_code($response);
if ($code === 200) {
return json_decode(wp_remote_retrieve_body($response), true);
}
}

// Backoff exponencial: 2s, 4s, 6s
sleep(2 * $attempt);
}

return null; // Todos los reintentos fallaron
}

Error CORS (desde el navegador)

Causa: La API de Tokko no permite llamadas directas desde JavaScript del navegador (no envían headers CORS).

Solución: Nunca llames a la API desde el frontend. Además de no funcionar por CORS, expones tu API Key en el código fuente. Usa siempre un backend (PHP, Node.js, Python) como intermediario.

Mejores prácticas para trabajar con la API

Después de trabajar extensivamente con la API de Tokko, estas son las prácticas que recomendamos:

1. Siempre implementa reintentos

La API de Tokko puede tener intermitencias. Una buena implementación reintenta al menos 3 veces con backoff exponencial antes de considerar un error como definitivo.

2. Respeta los rate limits

No bombardees la API con cientos de llamadas en paralelo. Agrega delays entre llamadas, especialmente cuando estás paginando sobre muchas propiedades.

3. Usa timeouts adecuados

Un timeout de 20-30 segundos es razonable para la mayoría de las llamadas. Las llamadas que traen muchas propiedades pueden tardar más.

4. Cachea lo que puedas

No descargues todo el catálogo de propiedades cada vez. Implementa sincronización incremental: guarda timestamps y solo descarga lo que cambió desde la última vez.

5. Nunca expongas tu API Key

Toda comunicación con la API debe ser server-side. El frontend habla con tu backend, y tu backend habla con Tokko.

6. Monitorea los errores

Lleva un log de las llamadas fallidas. Si empiezas a ver muchos 429 o 5xx, ajusta la frecuencia de tus llamadas.

Cómo lo resuelve TokkoPlugins

Si usas WordPress, no necesitas implementar nada de esto manualmente. TokkoPlugins Pro maneja toda la integración con la API de Tokko de forma automática:

  • Autenticación simplificada: Ingresa tu API Key en el panel de configuración y listo. El plugin valida la conexión al instante y te muestra el estado.
  • Reintentos automáticos: Cada llamada a la API incluye hasta 3 reintentos con backoff exponencial (2s, 4s, 6s), para que las intermitencias transitorias no afecten la sincronización.
  • Manejo inteligente de errores: El plugin identifica errores 401, 403, 429 y 5xx, y te muestra mensajes claros en el panel de administración con diagnósticos del sistema.
  • Timeouts configurados: Cada tipo de operación usa el timeout óptimo: 20s para llamadas generales, 30s para sincronización masiva, 15s para envío de leads.
  • Sincronización incremental: En vez de descargar todo cada vez, el plugin detecta qué cambió desde la última sincronización y solo procesa las diferencias.

Solo ingresa tu API Key, haz clic en «Test Connection», y si ves la palomita verde estás listo para sincronizar.

Probar TokkoPlugins Pro gratis →

Próximos pasos

Esta guía te dio los fundamentos para conectarte a la API de Tokko Broker. En los próximos artículos de esta serie vamos a profundizar en cada endpoint:

Preguntas frecuentes

¿La API de Tokko es REST?

Sí. Usa los métodos HTTP estándar (GET, POST), devuelve JSON, y cada recurso tiene su propio endpoint.

¿Puedo usar la API desde Excel o Power BI?

Sí, puedes hacer llamadas GET desde Power Query usando la URL con tu API Key. Ten en cuenta que la API devuelve JSON, así que vas a necesitar parsear la respuesta.

¿Cuántas llamadas puedo hacer por minuto?

Tokko aplica rate limiting pero no publica los límites exactos. En la práctica, una llamada por segundo funciona bien. Si necesitas descargar mucha data, usa paginación con limit=50 y agrega delays.

¿La API está disponible 24/7?

Generalmente sí, pero tiene intermitencias ocasionales (errores 500/502/503). Cualquier integración seria debe implementar reintentos.

¿Puedo crear propiedades desde la API?

Sí, existe el endpoint Property Importer, pero requiere permisos especiales habilitados por Tokko. Lo cubriremos en un artículo futuro de esta serie.

Este artículo es parte de la serie «Fundamentos de la API de Tokko Broker» de TokkoPlugins. Publicamos guías técnicas semanales para desarrolladores que trabajan con Tokko.

Sincroniza tus propiedades y emprendimientos con la arquitectura nativa de Houzez.