API de votos
Añade un botón de voto a tu web o conecta tu CMS para recompensar a tus jugadores.
Botón para tu web
Cuando tu hotel esté aceptado, abre Botón y banners para votar desde Mis hoteles. Copia el HTML del botón y pégalo en tu web. Cualquier visitante puede confirmar un voto para el ranking en CiudadHabbo.
Si quieres identificar al jugador para darle un premio, genera un enlace con la API desde el servidor de tu hotel.
Elige cómo entregar las recompensas
Con Pingback, CiudadHabbo notifica a tu hotel. Con Consulta, tu servidor pide los votos por lotes. Elige un método para los premios y guarda cada vote_id como clave única.
Para empezar, aprueba tu ficha y abre Mis hoteles → Integraciones. La clave de API autentica las peticiones hacia CiudadHabbo. El secreto de pingback autentica las notificaciones que recibe tu hotel.
Enlaces para votar como jugador
Con el jugador identificado en tu CMS, genera un enlace desde el servidor. El enlace dura una hora. El jugador confirma el voto en CiudadHabbo.
curl 'https://ciudadhabbo.com/api/v1/hotels/ID_DEL_HOTEL/vote-link' -H 'Authorization: Bearer TU_CLAVE_API' \
-H 'Content-Type: application/json' -d '{"player":"Jugador"}'La respuesta JSON incluye url y expires_in (3600 segundos). El identificador acepta de 1 a 40 letras, números o caracteres _.:@-.
Los votos desde un banner normal cuentan en el ranking. Si llegan sin jugador vinculado, hotel_username vale null.
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.
Recibir votos por pingback
Configura un endpoint HTTPS en el dominio exacto de tu ficha, copia el secreto y pulsa Probar pingback. El panel muestra el resultado HTTP. El receptor recibe el secreto en Authorization: Bearer y en el cuerpo JSON.
{
"vote_id": "ID_ESTABLE_DEL_VOTO",
"token": "TOKEN_DEL_EVENTO",
"hotel_slug": "ID_DEL_HOTEL",
"hotel_name": "Mi hotel",
"hotel_username": "Jugador",
"voted_at": "2026-11-21T18:00:00.000Z",
"secret": "TU_SECRETO_PINGBACK"
}- Lee el JSON y compara el secreto en tiempo constante, por ejemplo con
hash_equalsen PHP. Enmascara el secreto en los registros. - Si llega
test: trueohotel_username: null, devuelve 2xx sin conceder premios. - Si llega un jugador, registra el
vote_idy concede el premio en una sola transacción de tu base de datos. Devuelve 2xx también para los votos ya procesados.
El destino debe resolver a una IPv4 pública, presentar un certificado válido y responder directamente en 10 segundos, sin redirecciones. Tras un fallo se reintenta a los 30 segundos, 2 minutos y 5 minutos desde el intento anterior. El panel conserva los resultados recientes.
Consultar los votos desde tu servidor
Consulta cada uno a cinco minutos. La API devuelve hasta 100 votos identificados y válidos de los últimos 30 días. Guarda next_cursor después de procesar el lote y vuelve a usarlo en after.
curl 'https://ciudadhabbo.com/api/v1/hotels/ID_DEL_HOTEL/rewards?after=0' -H 'Authorization: Bearer TU_CLAVE_API'La respuesta contiene rewards y next_cursor. Cada voto incluye vote_id, sequence, hotel_username y voted_at en UTC.
También están disponibles /votes/report y /votes/search dentro de la ruta del hotel. Puedes enviar player y una fecha ISO en since. Usa un cursor distinto para cada filtro o consulta siempre el lote completo.
