Documentação da API
Sistema de verificação de votos Metin2
Recompensas de voto fáceis, gratuitas e fiáveis para o seu servidor privado Metin2
O nosso Sistema de Verificação de Votos é uma solução moderna e inovadora criada especificamente para servidores privados de Metin2. Fornece uma forma envolvente de os jogadores votarem nos seus servidores favoritos enquanto recebem benefícios no jogo.
O sistema é fácil de implementar e altamente fiável, tornando-o uma excelente escolha para proprietários que procuram aumentar o envolvimento dos jogadores e a visibilidade do servidor.
O nosso objetivo é criar uma situação vantajosa para todos — os jogadores são recompensados pela sua lealdade com benefícios no jogo, enquanto os servidores beneficiam de maior visibilidade e envolvimento.
Sistema Vote4Buff (Recomendado)
Sistema completo de votação e recompensas no jogo com interface personalizada
Vote4Buff é a nossa solução premium tudo-em-um para votação, que inclui uma interface deslumbrante no jogo, comunicação por WebSocket e integração completa com o servidor. Os jogadores podem votar, escolher entre múltiplos pacotes de bónus e receber recompensas instantaneamente sem sair do jogo!
Arquitetura do sistema
O sistema Vote4Buff é composto por três componentes principais:
Lado do cliente
- Sistema de UI em Python (uivote4buff.py)
- Recursos e gráficos personalizados
- Integração C++ via WebSocket
- Suporte para 11 idiomas
Lado do servidor
- Integração da API em C++
- Gestão de pacotes de bónus
- Sistema de recompensas por item
- Monitorização em tempo real dos efeitos
A nossa plataforma
- API de verificação de votos
- Monitorização baseada em conta
- Proteção contra batota
- Estado de votos em tempo real
Funcionalidades principais
Perfeito para: Proprietários que desejam uma solução profissional pronta a usar sem gastar semanas em desenvolvimento personalizado. Basta configurar os pacotes de bónus, integrar os ficheiros e está pronto a funcionar!
Transferir ficheiros Vote4Buff
Obtenha todos os ficheiros necessários para integração no cliente e no servidor
Vote4Buff foi desenhado para a base de código martysama0134 v5.8. Se estiver a usar uma fonte diferente, poderão ser necessárias adaptações.
Conteúdo do pacote
Ficheiros de cliente
- Ficheiros de UI em Python (uivote4buff.py)
- Modificações nos ficheiros do jogo
- Recursos e gráficos da interface
- Ficheiros de locale em 11 idiomas
- Implementação de WebSocket em C++
- Ficheiros de script da interface
Inclui libcurl.dll (versão 32 bits incluída, 64 bits disponível)
Ficheiros de servidor
- Configuração de char.h
- Modificações ao sistema de efeitos
- Integração de comandos de chat
- Camada de comunicação com a API
- Sistema de gestão de bónus
Inclui todas as modificações necessárias no código-fonte C++
Por favor, inicie sessão para transferir os ficheiros Vote4Buff.
Guia de configuração
Configure os pacotes de bónus, as recompensas por item e as definições da API
Toda a configuração do Vote4Buff é feita no ficheiro char.h do seu servidor. Veja em baixo exemplos detalhados de cada opção.
Passo 1: Credenciais API
Comece por configurar o ID do seu servidor e a chave API (disponíveis no seu painel):
// API SETTINGS from Metin2 Server List
static const std::string s_VOTE4BUFF_SERVER_ID = "YOUR_SERVER_ID"; // From dashboard
static const std::string s_VOTE4BUFF_API_TOKEN = "YOUR_API_TOKEN"; // From dashboard
static const int s_VOTE4BUFF_DURATION = 86400; // seconds (1 day) DO NOT MODIFY THIS !!!
Passo 2: Configurar pacotes de bónus
Pode definir até 3 pacotes de bónus para os jogadores escolherem. Cada pacote pode conter vários bónus:
// Bonuses must be set with its APPLY_ declaration.
// You can add as many bonuses as you want per slot.
static std::vector<std::vector<std::pair<int, int>>> s_VOTE4BUFF_BONUSES =
{
{ // Bonus Pool 1: PvP Focused
{ APPLY_ATTBONUS_HUMAN, 5 }, // +5% vs Players
{ APPLY_DEF_GRADE_BONUS, 50 }, // +50 Defense
},
{ // Bonus Pool 2: PvE Focused
{ APPLY_ATTBONUS_MONSTER, 5 }, // +5% vs Monsters
{ APPLY_ATTBONUS_INSECT, 5 }, // +5% vs Insects
{ APPLY_HP_REGEN, 10 }, // +10 HP Regen
},
{ // Bonus Pool 3: Farm Focused
{ APPLY_ITEM_DROP_BONUS, 10 }, // +10% Drop Rate
{ APPLY_EXP_DOUBLE_BONUS, 10 }, // +10% EXP
{ APPLY_GOLD_FIND, 15 }, // +15% Gold
},
};
Tipos de bónus comuns: APPLY_ATTBONUS_HUMAN, APPLY_ATTBONUS_MONSTER, APPLY_DEF_GRADE_BONUS, APPLY_ITEM_DROP_BONUS, APPLY_EXP_DOUBLE_BONUS, APPLY_GOLD_FIND, APPLY_MAX_HP, APPLY_MAX_SP, APPLY_HP_REGEN, APPLY_SP_REGEN, APPLY_CRITICAL_PCT, APPLY_PENETRATE_PCT e muitos mais!
Passo 3: Recompensas por item (Opcional)
Configure os itens que os jogadores recebem automaticamente após votar:
static std::vector<std::pair<DWORD, int>> s_VOTE4BUFF_ITEM_REWARDS =
{
// Leave empty if you don't want to give any items as rewards
// Format: { vnum, count }
{ 27007, 5 }, // 5x Red Potion (XXL)
{ 50084, 1 }, // 1x Gold Bar
{ 71027, 10 }, // 10x Dragon Coin
};
Passo 4: Definições de mudança de bónus
Controle o tempo de espera e o custo quando os jogadores quiserem alternar entre pacotes de bónus:
// Cooldown when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_COOLDOWN = 300; // seconds (5 minutes)
// Price when changing bonus (does not apply when choosing right after voting)
static const int s_VOTE4BUFF_CHANGE_BONUS_PRICE = 15000; // yang (0 = free)
Nota: Depois de votar, os jogadores podem escolher um pacote de bónus gratuitamente. O tempo de espera e o custo só se aplicam quando pretendem mudar de pacote mais tarde sem voltar a votar.
Guia de instalação
Instruções passo a passo para integrar o Vote4Buff
Certifique-se de que tem cópias de segurança dos ficheiros do cliente e do servidor! Convenção de nomes: ficheiros com o prefixo __ requerem alterações, ficheiros sem prefixo podem ser copiados diretamente.
Instalação no servidor
Configurar char.h
Abra Source/Server/__char.h do pacote transferido.
- Localize
class CBuffOnAttributes;e adicione o código de configuração acima (ver secção Configuração) - Defina
s_VOTE4BUFF_SERVER_IDes_VOTE4BUFF_API_TOKEN - Configure os seus pacotes de bónus e recompensas por item
- Localize
bool DragonSoul_RefineWindow_CanRefine();e adicione as declarações de métodos públicos
Aplicar modificações no servidor
Integre os ficheiros do lado do servidor incluídos no pacote:
__affect.h- Atualize o seu affect.h existente com as alterações fornecidas__chat_affect.cpp- Adicione a gestão de efeitos do Vote4Buff__cmd_general.cpp- Adicione o processamento dos comandos__desc_client.cpp- Modificações no descritor de cliente
Nota: ficheiros com o prefixo __ indicam que deve fundir as alterações com os seus ficheiros atuais.
Recompilar o game core
Compile o game server com as novas modificações.
make clean && make Instalação no cliente
Ficheiros de UI em Python
Na pasta Client/root/:
- Copie
uivote4buff.pypara a pastaroot/do seu cliente - Modifique os seguintes ficheiros conforme indicado:
__constInfo.py__game.py__interfaceModule.py__uiAffectShower.py
Gráficos e scripts de UI
- Copie a pasta
Client/ui/game/vote4buff/paraui/game/do seu pack - Copie
Client/uiscript/vote4buffwindow.pypara a pasta uiscript
Ficheiros de idioma
Adicione as strings de locale para os idiomas suportados a partir de Client/locale/:
- Anexe o conteúdo de
__locale_game.txtao seulocale_game.txt - Anexe o conteúdo de
__locale_interface.txtao seulocale_interface.txt
Idiomas disponíveis: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ
Modificações no cliente C++
Em Source/Client/UserInterface/:
- Copie
M2WebSocket.cppeM2WebSocket.hpara a pasta UserInterface - Aplique as modificações dos ficheiros com prefixo
__aos seus ficheiros existentes - Certifique-se de que
libcurl.dllestá na pasta do cliente (32 bits incluído, transfira a versão 64 bits se necessário)
Adicionar botão de UI (Opcional)
O Vote4Buff não adiciona um botão por defeito. Tem de chamar ToggleVote4Buff() a partir de algum ponto da sua UI. Por exemplo:
- Adicionar um botão ao SystemDialog
- Associá-lo a uma tecla de atalho
- Adicionar ao menu de atalhos
Ou utilize a classe Vote4BuffButton incluída, que cria um ícone arrastável
Recompilar o cliente
Recompile o executável do cliente com as novas modificações.
Testes
Teste a integração:
- Inicie sessão no servidor
- Abra a janela Vote4Buff
- Vote na nossa plataforma: https://metin2-toplist.net/vote/en/YOUR_SERVER_ID-server-name/YOUR_ACCOUNT_ID
- Regresse ao jogo e confirme o voto
- Selecione um pacote de bónus e verifique se os efeitos foram aplicados
- Verifique se recebeu as recompensas por item
Os seus jogadores podem agora votar e receber recompensas automaticamente. A interface do Vote4Buff mostra quando podem votar, permite escolher pacotes de bónus e apresenta contadores regressivos para os efeitos ativos.
Vantagens para administradores
Promoção gratuita
A maioria dos novos jogadores descobre servidores através de toplists — é uma ferramenta essencial de marketing
Configuração simples
Documentação detalhada e guias passo a passo tornam tudo simples
Sem necessidade de código
Integração REST simples e direta
Performance otimizada
A verificação do voto no lado do cliente reduz o impacto no servidor
Altamente fiável
Sistema comprovado com prevenção de fraude integrada
Verificação de voto
Confirme que os jogadores realmente votaram antes de entregar recompensas
Vantagens para jogadores
Como funciona o sistema?
O fluxo é simples e intuitivo para os jogadores. Melhor ainda: a verificação é feita via API, garantindo que apenas votos legítimos são aceites!
Primeiros passos - Guia rápido
Escolha o método de integração que melhor se adapta às suas necessidades:
Sistema Vote4Buff
Solução completa com interface personalizada, comunicação WebSocket e recompensas automáticas.
- Interface completa no jogo
- Múltiplos pacotes de bónus
- Recompensas automáticas por item
- Temporizadores em tempo real
- Suporte a 11 idiomas
Integração API personalizada
Construa a sua própria implementação com a nossa API REST para total flexibilidade e controlo.
- Personalização total
- Design de UI próprio
- Lógica de recompensa personalizada
- Base por IP ou por conta
Passos gerais de configuração
Registe o seu servidor
Crie uma conta e adicione o seu servidor à nossa toplist em https://metin2-toplist.net/servers/create
Obtenha as suas credenciais API
No painel do servidor encontrará o ID e a chave API exclusivos necessários para autenticação.
Escolha o método de integração
Transfira o Vote4Buff para uma solução pronta ou use a nossa API para integração personalizada.
Teste e publique
Teste o sistema de votação exaustivamente e depois publique no servidor oficial.
Endpoint da API (para implementações personalizadas)
Se estiver a usar o Sistema Vote4Buff (recomendado), esta API já está integrada! Esta secção é para quem deseja uma implementação própria.
https://metin2-toplist.net/api/check-vote
Parâmetros obrigatórios
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
api_token |
string | Sim | Token API único do seu servidor |
ip |
string | Opcional* | Endereço IP do jogador (IPv4 ou IPv6) |
account_id |
string | Opcional* | ID ou username do jogador para monitorização mais precisa |
Para melhores resultados, use <code>account_id</code> para uma monitorização precisa. O método <code>ip</code> pode ser menos fiável se os jogadores usarem VPNs ou jogarem de locais diferentes.
Formato da URL de voto
Direcione os jogadores a votar usando esta estrutura de URL:
https://metin2-toplist.net/vote.{lang}/{server_id}-{server_slug}/{account_id}
Exemplos:
https://metin2-toplist.net/vote.en/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.de/123-awesome-server/PlayerName
https://metin2-toplist.net/vote.tr/123-awesome-server/PlayerName
Idiomas suportados: en, de, es, pl, tr, ro, it, pt, hu, gr, cz
Formato da resposta
A API responde em JSON com a seguinte estrutura:
{
"success": true,
"voted": true,
"last_vote": "2025-11-11T14:30:00Z",
"next_vote_in": 0,
"message": "Vote verified successfully"
}
{
"success": true,
"voted": false,
"message": "No recent vote found"
}
{
"success": false,
"message": "Invalid API token"
}
Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
success |
boolean | Indica se o pedido foi bem-sucedido |
voted |
boolean | Indica se foi encontrado um voto válido (apenas quando success=true) |
last_vote |
string | Timestamp ISO 8601 do último voto (quando voted=true) |
next_vote_in |
integer | Segundos até que um novo voto seja permitido (quando voted=true) |
message |
string | Mensagem legível que descreve o resultado |
Exemplos de código
Exemplo em PHP
<?php
function checkVote($apiToken, $playerIP) {
$url = "https://metin2-toplist.net/api/check-vote";
$params = http_build_query([
'api_token' => $apiToken,
'ip' => $playerIP
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . '?' . $params);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode !== 200) {
return ['success' => false, 'message' => 'API request failed'];
}
return json_decode($response, true);
}
$result = checkVote('YOUR_API_TOKEN', $_SERVER['REMOTE_ADDR']);
if ($result['success'] && $result['voted']) {
echo "Vote verified! Rewarding player...";
}
?>
Exemplo em Python
import requests
def check_vote(api_token, player_ip):
url = "https://metin2-toplist.net/api/check-vote"
params = {'api_token': api_token, 'ip': player_ip}
try:
response = requests.get(url, params=params, timeout=10)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
return {'success': False, 'message': f'API request failed: {str(e)}'}
result = check_vote('YOUR_API_TOKEN', '123.456.789.012')
if result.get('success') and result.get('voted'):
print("Vote verified! Rewarding player...")
Exemplo em C++ (para servidores)
#include <curl/curl.h>
#include <string>
#include <sstream>
static size_t WriteCallback(void* contents, size_t size, size_t nmemb, void* userp) {
((std::string*)userp)->append((char*)contents, size * nmemb);
return size * nmemb;
}
bool CheckVote(const std::string& apiToken, const std::string& playerIP) {
CURL* curl = curl_easy_init();
if (!curl) return false;
std::string readBuffer;
std::ostringstream url;
url << "https://metin2-toplist.net/api/check-vote"
<< "?api_token=" << apiToken
<< "&ip=" << playerIP;
curl_easy_setopt(curl, CURLOPT_URL, url.str().c_str());
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
curl_easy_setopt(curl, CURLOPT_WRITEDATA, &readBuffer);
curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L);
curl_easy_setopt(curl, CURLOPT_TIMEOUT, 10L);
CURLcode res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
return (res == CURLE_OK) && (readBuffer.find("\"voted\":true") != std::string::npos);
}
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
if (CheckVote("YOUR_API_TOKEN", playerIP)) {
GiveItemToPlayer(playerName, REWARD_ITEM_VNUM, REWARD_COUNT);
SendNotice("Vote verified! You received your reward!");
} else {
SendNotice("No valid vote found. Please vote first!");
}
}
Exemplo em JavaScript/Node.js
async function checkVote(apiToken, playerIP) {
const url = new URL('https://metin2-toplist.net/api/check-vote');
url.searchParams.append('api_token', apiToken);
url.searchParams.append('ip', playerIP);
try {
const response = await fetch(url, {
method: 'GET',
headers: { 'Accept': 'application/json' }
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return await response.json();
} catch (error) {
return { success: false, message: error.message };
}
}
checkVote('YOUR_API_TOKEN', '123.456.789.012').then(result => {
if (result.success && result.voted) {
console.log('Vote verified! Rewarding player...');
}
});
Guia de integração
Guarde a sua chave API em segurança e nunca a exponha em código cliente. As chamadas à API devem ser feitas a partir do backend.
Passo 1: Criar botão/comando de voto
Adicione um botão no site ou um comando no jogo que redirecione os jogadores para a página de votos em https://metin2-toplist.net/servers/YOUR-SERVER-SLUG.
Passo 2: Implementar verificação dos votos
Quando o jogador solicitar a recompensa (no site ou no jogo), verifique se ele votou:
- Obtenha o endereço IP do jogador
- Faça o pedido à API check-vote
- Analise a resposta JSON
- Se
votedfor true, entregue a recompensa - Registe que a recompensa foi dada para evitar duplicações
Passo 3: Tratar recompensas
Boas práticas para o processamento das recompensas:
- Monitorize recompensas: Guarde na sua base de dados os votos já recompensados para evitar duplicidade
- Cooldown do voto: Respeite o intervalo de 24 horas entre votos
- Gestão de erros: Trate erros da API de forma amigável
- Registos: Registe todas as verificações de votos para diagnóstico e análise
Fluxo de trabalho de exemplo
Resolução de problemas
Erro "Invalid API token"
Solução: Verifique se está a usar a chave correta do painel. Certifique-se de que não existem espaços extra.
Voto não detetado após o jogador votar
Causas possíveis:
- Jogador usa VPN/Proxy (IP não corresponde)
- O voto ainda não foi processado (aguarde 30 segundos)
- Envio de endereço IP incorreto para a API
- Jogador votou noutro servidor
Timeout ou erros de ligação à API
Solução: Certifique-se de que o seu servidor pode fazer pedidos HTTPS externos. Verifique a firewall e implemente nova tentativa com backoff exponencial.
Jogadores recebem recompensas várias vezes
Solução: Implemente controlo local de votos recompensados. Guarde o timestamp e garanta que cada voto é premiado apenas uma vez.
Endereços IPv6 não funcionam
Solução: Envie o endereço IPv6 completo. A nossa API suporta IPv4 e IPv6.
Public Server Listing API (v1)
List, submit, and claim Metin2 servers programmatically. Perfect for other toplists, server management tools, or custom integrations.
https://metin2-toplist.net/api/v1
Rate Limits
| Endpoint | Method | Limit | Auth |
|---|---|---|---|
/api/v1/servers | GET | 60/min | — |
/api/v1/servers/{slug} | GET | 60/min | — |
/api/v1/servers | POST | 3/hour | — |
/api/v1/servers/claim | POST | 10/hour | ✅ |
List Servers
Retrieve a paginated list of active, launched servers. Supports filtering by category and language.
| Parameter | Type | Default | Description |
|---|---|---|---|
category | string | — | Filter by category: oldschool, newschool, fun, pvp, pvm, pve |
language | string | — | Filter by language code: EN, DE, TR, etc. |
sort | string | votes | Sort order: votes, newest, name |
page | integer | 1 | Page number |
per_page | integer | 25 | Results per page (max 50) |
curl -H "Accept: application/json" \
"https://metin2-toplist.net/api/v1/servers?category=pvp&language=EN&per_page=10"
Submit a New Server
Submit a new server listing via the API. The server enters a moderation queue and must be approved before it appears publicly.
All API-submitted servers start as inactive and require manual approval. This prevents spam and ensures listing quality.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Server name (max 255 chars, must be unique) |
description | string | ✅ | Server description (min 20, max 5000 chars) |
website_url | string | — | Server website URL |
discord_url | string | — | Discord invite URL |
languages | array | ✅ | Language codes, e.g. ["EN", "DE"] (min 1, max 5) |
category | string | — | One of: oldschool, newschool, fun, pvp, pvm, pve |
launch_date | string | — | Future launch date (YYYY-MM-DD) |
owner_email | string | — | Contact email (optional, not shown publicly) |
curl -X POST "https://metin2-toplist.net/api/v1/servers" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"name": "Dragon Kingdom",
"description": "A classic PvP experience with custom dungeons and weekly events.",
"languages": ["EN", "DE"],
"category": "pvp",
"website_url": "https://dragon-kingdom.com",
"discord_url": "https://discord.gg/example"
}'
{
"success": true,
"message": "Server submitted successfully!",
"data": {
"id": 42,
"slug": "dragon-kingdom",
"status": "pending_review"
},
"claim_token": "a1b2c3d4...80 characters",
"note": "Save this token! Use it to claim your listing."
}
Claim Token System
When you submit a server, you receive a unique 80-character claim token. This token lets you link the listing to your account later.
The claim token is shown only once in the API response. Save it immediately — we store only the hash.
Submit
POST your server to /api/v1/servers and save the claim_token from the response.
Register
Create an account and paste the token in the optional "Claim Token" field.
Manage
Your server is now linked to your account with full dashboard access.
Error Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Server created (pending review) |
401 | Authentication required (claim endpoint) |
404 | Server not found / invalid claim token |
409 | Server already claimed |
410 | Claim token expired |
422 | Validation error / spam rejected |
429 | Rate limit exceeded |
Integration Examples
$response = file_get_contents('https://metin2-toplist.net/api/v1/servers?per_page=10');
$data = json_decode($response, true);
foreach ($data['data'] as $server) {
echo $server['name'] . ' — ' . $server['vote_count'] . ' votes' . PHP_EOL;
}
const res = await fetch('https://metin2-toplist.net/api/v1/servers?category=pvp');
const { data, meta } = await res.json();
data.forEach(server => {
console.log(`${server.name}: ${server.vote_count} votes`);
});
import requests
resp = requests.get('https://metin2-toplist.net/api/v1/servers', params={
'language': 'DE',
'sort': 'newest',
'per_page': 20
})
servers = resp.json()['data']
for s in servers:
print(f"{s['name']} — {s['vote_count']} votes")
Suporte e recursos
Teste a integração com uma conta de testes antes de publicar. Garanta que cobre todos os cenários e erros.