Developers

Votos com recompensa ​

Os votos ficam no IdleBazaar. Quando quiser recompensar um jogador (ao entrar no jogo, ou num botão "resgatar voto"), o servidor do jogo consulta a nossa API com a chave gerada na página de integração, no cabeçalho X-Api-Key.

URL base: https://api.idlebazaar.com/v1/public/games/GAME_ID

Para testar sem mexer nos dados reais, use o ambiente de teste: https://sandbox.api.idlebazaar.com.

Como funciona ​

  1. Gere a chave na página de integração do jogo e guarde-a só no servidor. Gerar outra invalida a anterior.
  2. Consulte quantos votos pendentes (unclaimed) o jogador tem, se só quiser mostrar a informação.
  3. Para entregar a recompensa, chame o resgate: ele marca os votos como resgatados e devolve quantos foram (claimed). Dê uma recompensa para cada voto devolvido.
  4. O resgate é atômico: chamadas repetidas ou ao mesmo tempo nunca devolvem o mesmo voto duas vezes.
  5. O identificador do jogador é digitado por quem vota; não prova que a conta é dele.

Chave só no servidor

Use a chave apenas no servidor do jogo, nunca no navegador ou no app do jogador.

Consultar votos do jogador ​

GET /player-votes?player=PLAYER_ID

ParâmetroOndeDescrição
X-Api-KeycabeçalhoChave de votos do jogo (ibv_…).
playerqueryIdentificador do jogador no seu jogo, até 100 caracteres.
sh
curl "https://api.idlebazaar.com/v1/public/games/GAME_ID/player-votes?player=PLAYER_ID" \
  -H "X-Api-Key: ibv_…"
js
const res = await fetch(`${API}/player-votes?player=${encodeURIComponent(playerId)}`, {
  headers: { 'X-Api-Key': KEY },
})
const votes = await res.json()
php
<?php
$ch = curl_init("$api/player-votes?player=" . urlencode($playerId));
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["X-Api-Key: $key"],
    CURLOPT_RETURNTRANSFER => true,
]);
$votes = json_decode(curl_exec($ch), true);
python
votes = requests.get(f"{API}/player-votes", params={"player": player_id},
                     headers={"X-Api-Key": KEY}, timeout=5).json()

Resposta 200

json
{
  "player": "PLAYER_ID",
  "total": 12,
  "unclaimed": 1,
  "last_vote_at": "2026-01-01T12:00:00.000Z",
  "next_vote_at": "2026-01-02T12:00:00.000Z"
}
CampoDescrição
totalVotos do jogador neste jogo, resgatados ou não.
unclaimedVotos ainda não resgatados.
last_vote_atData do último voto, ou null.
next_vote_atQuando ele pode votar de novo, ou null se já pode.
Experimente no sandboxGET /player-votes
curl "https://sandbox.api.idlebazaar.com/v1/public/games/GAME_ID/player-votes?player=PLAYER_ID" \
  -H "X-Api-Key: SUA_CHAVE"
A requisição é enviada ao sandbox sandbox.api.idlebazaar.com. A chave não é guardada.

Resgatar votos pendentes ​

POST /player-votes/claim

Corpo JSON com o campo player. Marca os votos pendentes como resgatados e devolve quantos foram.

sh
curl -X POST "https://api.idlebazaar.com/v1/public/games/GAME_ID/player-votes/claim" \
  -H "X-Api-Key: ibv_…" \
  -H "Content-Type: application/json" \
  -d '{ "player": "PLAYER_ID" }'
js
const API = 'https://api.idlebazaar.com/v1/public/games/' + process.env.IDLEBAZAAR_GAME_ID
const KEY = process.env.IDLEBAZAAR_VOTE_KEY

// Chame no servidor do jogo, por exemplo ao entrar ou num botão "resgatar voto".
async function claimVoteRewards(player) {
  const res = await fetch(API + '/player-votes/claim', {
    method: 'POST',
    headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ player: player.externalId }),
  })
  if (!res.ok) throw new Error('IdleBazaar ' + res.status)
  const { claimed } = await res.json()
  for (let i = 0; i < claimed; i++) await game.giveVoteReward(player)
}
php
<?php
$ch = curl_init("$api/player-votes/claim");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-Api-Key: $key", 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['player' => $playerId]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
for ($i = 0; $i < $result['claimed']; $i++) {
    $game->giveVoteReward($playerId);
}
python
res = requests.post(f"{API}/player-votes/claim", json={"player": player_id},
                    headers={"X-Api-Key": KEY}, timeout=5)
res.raise_for_status()
for _ in range(res.json()["claimed"]):
    game.give_vote_reward(player_id)

Os IDs de jogos e votos são Snowflake enviados como strings decimais. Preserve o texto completo; não converta para Number em JavaScript. O PLAYER_ID continua sendo o identificador definido pelo seu jogo.

Resposta 200

json
{
  "player": "PLAYER_ID",
  "claimed": 1,
  "votes": [{ "id": "107374182400000001", "voted_at": "2026-01-01T12:00:00.000Z" }]
}
Experimente no sandboxPOST /player-votes/claim
curl -X POST "https://sandbox.api.idlebazaar.com/v1/public/games/GAME_ID/player-votes/claim" \
  -H "X-Api-Key: SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"player":"PLAYER_ID"}'
A requisição é enviada ao sandbox sandbox.api.idlebazaar.com. A chave não é guardada.

Com a chave ativa, a página de voto passa a exigir o identificador do jogador. Respostas de erro estão em Erros.

Para o jogador votar já identificado, divulgue o link com o parâmetro player. É esse valor que você consulta e resgata na API.

https://idlebazaar.com/vote/GAME_ID?player=PLAYER_ID