CiudadHabboGuías para hoteles
Inicio Guías para hoteles
Para tu hotel

API de jugadores en línea

Publica el recuento y el estado de tu hotel en el ranking y en su ficha.

Fuentes de presencia

  • API. Envía un reporte autenticado desde tu emulador o con el kit PHP, preferiblemente cada minuto. Caduca a los diez minutos.
  • Atom CMS. Activa la opción en Integraciones. CiudadHabbo consulta por HTTPS la ruta /api/online-count de tu web cada cinco minutos cuando falta un reporte vigente. Debe responder directamente con {"data":{"onlineCount":42}}.

Un reporte de API vigente tiene prioridad, incluso si indica offline.

Enviar un reporte

curl 'https://ciudadhabbo.com/api/v1/hotels/ID_DEL_HOTEL/presence' -H 'Authorization: Bearer TU_CLAVE_API' \
  -H 'Content-Type: application/json' -d '{"users_online":42,"status":"online"}'

users_online admite enteros de 0 a 65 535. status es opcional y por defecto vale online. Un reporte offline guarda 0.

{
  "success": true,
  "hotel_slug": "ID_DEL_HOTEL",
  "is_online": true,
  "users_online": 42,
  "reported_at": "2026-11-21T18:00:00.000Z",
  "fresh_for_seconds": 600
}

Errores habituales: 401, clave ausente o no válida. 403, hotel sin clave configurada. 404, ficha inexistente o sin publicar. 422, datos inválidos.

Envía la clave de API del hotel como Authorization: Bearer desde tu servidor y guárdala fuera del código público. El límite compartido de las rutas de API es de 60 peticiones por minuto por IP. Si recibes un 429, respeta Retry-After.

Instalar el kit PHP

Necesitas PHP 8.1 o posterior con cURL y, si consultas una base de datos, PDO con el controlador correspondiente.

Descargar script PHP · Descargar configuración de ejemplo

  1. Guarda ambos archivos fuera de la raíz pública del servidor.
  2. Copia la configuración a presencia.ini y completa URL, clave y datos de lectura del emulador.
  3. Prueba con php ciudadhabbo-presencia.php --dry-run. El comando cuenta usuarios sin enviar el resultado.
  4. Ejecuta el script y prográmalo cada minuto en cron.
* * * * * /usr/bin/php /ruta/privada/ciudadhabbo-presencia.php

Comprobar el resultado

En Mis hoteles → Integraciones puedes consultar el último reporte de cada fuente y su vigencia. Si Atom CMS responde con una redirección o un JSON inválido, revisa su configuración o usa el kit PHP.

Ver la API de votos