Tokko Broker es el CRM inmobiliario más usado en Argentina para agencias de bienes raíces. Si desarrollás sitios para inmobiliarias, en algún momento vas a necesitar integrar su API para mostrar el listado de propiedades en el sitio web del cliente. Esta guía cubre la integración completa en PHP vanilla — sin frameworks — y cómo usar Claude Code con Cerebro MCP para auditar la seguridad y calidad de la integración.

Autenticación en la API de Tokko

La API de Tokko usa autenticación por API key. La key se obtiene desde el panel del cliente en Tokko Broker y se pasa como parámetro en cada request:

// La API key NO va en headers sino como query param
$api_key = getenv('TOKKO_API_KEY'); // nunca hardcodear en el código
$base_url = 'https://www.tokkobroker.com/api/v1';

Guardá la key en el .env del proyecto, nunca en el código fuente. Si usás git, asegurate de que .env esté en .gitignore.

Listar propiedades

El endpoint principal es /property/. Un wrapper PHP básico:

function tokko_get_properties(int $limit = 20, int $offset = 0, array $filters = []): array
{
    $api_key  = getenv('TOKKO_API_KEY');
    $base_url = 'https://www.tokkobroker.com/api/v1';

    $params = array_merge([
        'key'    => $api_key,
        'limit'  => $limit,
        'offset' => $offset,
        'format' => 'json',
    ], $filters);

    $url = $base_url . '/property/?' . http_build_query($params);

    $ctx = stream_context_create([
        'http' => [
            'timeout' => 10,
            'header'  => "User-Agent: MiSitioInmobiliario/1.0\r\n",
        ],
    ]);

    $response = @file_get_contents($url, false, $ctx);

    if ($response === false) {
        error_log('Tokko API error: ' . $url);
        return [];
    }

    $data = json_decode($response, true);
    return $data['objects'] ?? [];
}

Filtros disponibles

Los parámetros de filtrado más usados:

// Solo propiedades en venta
$propiedades = tokko_get_properties(20, 0, [
    'operation_types' => '1',   // 1 = venta, 2 = alquiler, 3 = alquiler temporario
]);

// Filtrar por tipo de propiedad
$departamentos = tokko_get_properties(20, 0, [
    'property_types' => '2',    // 2 = departamento
    'operation_types' => '1',
]);

// Con precio mínimo y máximo en USD
$rango = tokko_get_properties(20, 0, [
    'price_from' => 50000,
    'price_to'   => 200000,
    'currency'   => 'USD',
]);

Obtener detalle de una propiedad

function tokko_get_property(int $id): ?array
{
    $api_key  = getenv('TOKKO_API_KEY');
    $base_url = 'https://www.tokkobroker.com/api/v1';

    $url = $base_url . '/property/' . (int)$id . '/?key=' . urlencode($api_key) . '&format=json';

    $ctx = stream_context_create(['http' => ['timeout' => 10]]);
    $response = @file_get_contents($url, false, $ctx);

    if ($response === false) {
        return null;
    }

    return json_decode($response, true);
}

Notá el casteo (int)$id — es importante para evitar inyección en la URL si el ID viene de un parámetro GET.

Caché de respuestas — obligatorio en producción

La API de Tokko tiene rate limiting. En producción, cachear las respuestas es obligatorio — si no, cada pageview del sitio hace un request a Tokko y podés quedar bloqueado:

function tokko_get_properties_cached(int $limit = 20, int $offset = 0, array $filters = []): array
{
    $cache_key  = 'tokko_' . md5(serialize([$limit, $offset, $filters]));
    $cache_file = sys_get_temp_dir() . '/' . $cache_key . '.json';
    $cache_ttl  = 900; // 15 minutos

    if (file_exists($cache_file) && (time() - filemtime($cache_file)) < $cache_ttl) {
        return json_decode(file_get_contents($cache_file), true) ?? [];
    }

    $data = tokko_get_properties($limit, $offset, $filters);

    file_put_contents($cache_file, json_encode($data));

    return $data;
}

Renderizar en el template PHP

<?php
$propiedades = tokko_get_properties_cached(12, 0, ['operation_types' => '1']);
?>

<div class="propiedades-grid">
<?php foreach ($propiedades as $prop): ?>
  <article class="prop-card">
    <?php if (!empty($prop['photos'][0]['image'])): ?>
    <img src="<?= e($prop['photos'][0]['image']) ?>"
         alt="<?= e($prop['address']) ?>"
         loading="lazy">
    <?php endif; ?>
    <div class="prop-info">
      <h3><?= e($prop['address']) ?></h3>
      <p class="prop-precio">
        USD <?= number_format((float)($prop['operations'][0]['prices'][0]['price'] ?? 0)) ?>
      </p>
      <p><?= e($prop['suite_amount']) ?> amb · <?= e($prop['total_surface']) ?> m²</p>
    </div>
  </article>
<?php endforeach; ?>
</div>

Auditar la integración con Claude Code + Cerebro MCP

Una vez implementada la integración, es el momento de auditarla. Con Cerebro MCP activo, abrís una sesión de Claude Code en el directorio del proyecto y pedís:

"Auditá esta integración con Tokko: revisá seguridad, manejo de errores y performance"

Claude llama a get_context("security-audit") y aplica el checklist sobre los archivos. Los puntos que típicamente aparecen en integraciones con APIs externas:

  • API key expuesta en código o logs — ¿está en .env y excluida de git?
  • Output de datos de Tokko sin escapar — cualquier string de la API que se renderice en HTML debe pasar por e()
  • Timeout en las requests — sin timeout, una API lenta puede colgar el proceso PHP entero
  • Manejo de errores — ¿qué muestra el usuario si la API de Tokko está caída?
  • Cache invalidation — ¿cómo se actualiza el caché cuando hay una propiedad nueva?

La ventaja de hacer esta auditoría con Claude + Cerebro es que aplica el checklist al código real de tu proyecto, no a un ejemplo genérico. Si tenés una función e() ya definida en tu bootstrap.php, Claude lo detecta y valida que la estés usando correctamente — no te dice "deberías usar htmlspecialchars" como si no lo supieras.