API de Votos — Guía de Integración

¿Qué es el Pingback?

Con el sistema de Pingback, HabboLibre envía automáticamente los datos del voto a tu servidor justo después de que un usuario vota. Tu servidor solo necesita recibir el POST y dar la recompensa. No necesitas llamar a ningún endpoint.

¿Por qué Pingback?

Tu servidor no necesita hacer requests a HabboLibre
Funciona automáticamente — configura y olvida
Reintentos automáticos si tu servidor no responde (3 intentos)
Incluye un secreto compartido para verificar autenticidad

¿Cómo funciona?

1Un usuario hace clic en "Votar" en la página de tu hotel.
2HabboLibre registra el voto en el ranking.
3HabboLibre envía automáticamente un POST a tu Pingback URL con los datos del voto.
4Tu servidor verifica el secret, identifica al usuario y le da la recompensa.
5Si tu servidor no responde, HabboLibre reintenta 3 veces (30s, 2min, 5min).

Configuración

1Ve a Dashboard → Mis Hoteles → Editar tu hotel.
2Configura el campo URL de Pingback con la URL de tu servidor (ej: https://mihotel.com/api/vote-reward).
3Copia tu Pingback Secret (se genera automáticamente) y guárdalo en tu servidor.
4Haz clic en "Probar Pingback" para verificar que tu servidor recibe los datos.

Datos que recibe tu servidor

HabboLibre envía un POST con JSON a tu pingback_url:

{
  "vote_id": 1234,
  "token": "abc123...def456",
  "hotel_slug": "mi-hotel",
  "hotel_name": "Mi Hotel",
  "username": "Player123",
  "user_id": 42,
  "ip": "203.0.113.50",
  "voted_at": "2026-03-17T15:30:00.000Z",
  "secret": "tu_pingback_secret_aqui"
}

Campo	Tipo	Descripción
vote_id	int	ID único del voto
token	string	Token del voto (64 caracteres)
hotel_slug	string	Slug de tu hotel
hotel_name	string	Nombre de tu hotel
username	string\|null	Nombre del votante (null si es anónimo)
user_id	int\|null	ID del votante en HabboLibre
ip	string	IP del votante
voted_at	ISO 8601	Fecha y hora del voto
secret	string	Tu pingback secret — verifica siempre
test	bool	Solo presente en pingbacks de prueba

¿Qué debe responder tu servidor?

Tu servidor debe responder con un código HTTP 2xx (200, 201, 202, 203 o 204) para indicar que recibió el voto correctamente. Si responde con otro código, HabboLibre reintentará hasta 3 veces.

Exitoso

HTTP 200 OK

Reintento

HTTP 500, 502, 503, timeout

Ejemplos de Código

PHP (Laravel / Vanilla)

// Endpoint: POST /api/vote-reward
$data = json_decode(file_get_contents('php://input'), true);

// 1. Verificar el secreto
$mySecret = 'TU_PINGBACK_SECRET_AQUI';
if ($data['secret'] !== $mySecret) {
    http_response_code(403);
    exit('Invalid secret');
}

// 2. Ignorar votos de prueba (opcional)
if (!empty($data['test'])) {
    http_response_code(200);
    exit('Test OK');
}

// 3. Dar recompensa al usuario
$username = $data['username'];
if ($username) {
    giveReward($username, 'vote_reward');
}

http_response_code(200);
echo 'OK';

Node.js (Express)

app.post('/api/vote-reward', (req, res) => {
  const { secret, username, test } = req.body;

  // 1. Verificar el secreto
  if (secret !== process.env.PINGBACK_SECRET) {
    return res.status(403).json({ error: 'Invalid secret' });
  }

  // 2. Ignorar votos de prueba
  if (test) return res.json({ ok: true });

  // 3. Dar recompensa
  if (username) {
    giveReward(username, 'vote_reward');
  }

  res.json({ ok: true });
});

Python (Flask)

@app.route('/api/vote-reward', methods=['POST'])
def vote_reward():
    data = request.get_json()

    # 1. Verificar el secreto
    if data.get('secret') != MY_PINGBACK_SECRET:
        return 'Invalid secret', 403

    # 2. Ignorar votos de prueba
    if data.get('test'):
        return 'Test OK'

    # 3. Dar recompensa
    username = data.get('username')
    if username:
        give_reward(username, 'vote_reward')

    return 'OK'

Seguridad

Siempre verifica el secret — Compara el campo secret con tu pingback secret almacenado. Si no coincide, rechaza el request.
Usa HTTPS — Tu pingback_url debe usar HTTPS para proteger los datos en tránsito.
Verifica duplicados — Guarda los vote_id procesados para evitar dar recompensas dobles.
Tokens expiran en 24h — Los votos no verificados después de 24 horas son inválidos.