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 que é o Sistema de Verificação de Votos?

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

O que é o Vote4Buff?

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

Múltiplos pacotes de bónus: Até 3 pacotes configuráveis que os jogadores podem escolher

Recompensas por item: Entrega automática de itens após um voto bem-sucedido

UI em tempo real: Temporizadores em contagem decrescente e acompanhamento de efeitos dentro do jogo

Comunicação via WebSocket: Verificação instantânea sem recarregar páginas

Multi-idioma: Suporte para 11 idiomas (EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ)

Recompensas personalizáveis: Configure bónus, duração e custos

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

Requisitos

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++

Login obrigatório

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):

C++

// 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:

C++

// 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
        // Add more bonuses if wanted
    },

    { // 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 APPLY disponíveis

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:

C++

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:

C++

// 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

Antes de começar

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

1

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_ID e s_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

2

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.

3

Recompilar o game core

Compile o game server com as novas modificações.

make clean && make

Instalação no cliente

4

Ficheiros de UI em Python

Na pasta Client/root/:

Copie uivote4buff.py para a pasta root/ do seu cliente
Modifique os seguintes ficheiros conforme indicado:
- __constInfo.py
- __game.py
- __interfaceModule.py
- __uiAffectShower.py

5

Gráficos e scripts de UI

Copie a pasta Client/ui/game/vote4buff/ para ui/game/ do seu pack
Copie Client/uiscript/vote4buffwindow.py para a pasta uiscript

6

Ficheiros de idioma

Adicione as strings de locale para os idiomas suportados a partir de Client/locale/:

Anexe o conteúdo de __locale_game.txt ao seu locale_game.txt
Anexe o conteúdo de __locale_interface.txt ao seu locale_interface.txt

Idiomas disponíveis: EN, DE, ES, PL, TR, RO, IT, PT, HU, GR, CZ

7

Modificações no cliente C++

Em Source/Client/UserInterface/:

Copie M2WebSocket.cpp e M2WebSocket.h para a pasta UserInterface
Aplique as modificações dos ficheiros com prefixo __ aos seus ficheiros existentes
Certifique-se de que libcurl.dll está na pasta do cliente (32 bits incluído, transfira a versão 64 bits se necessário)

8

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

9

Recompilar o cliente

Recompile o executável do cliente com as novas modificações.

10

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

Instalação concluída!

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

Recebem recompensas no jogo por votarem

Interface de votação fácil de usar

Exibição clara do tempo restante para votar

Sistema garantido de entrega das recompensas

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!

1

Jogador clica no botão de voto

A partir do seu site ou da interface do jogo

2

Redirecionamento para a página de voto

O jogador é encaminhado para a página de votação do seu servidor na toplist

3

Jogador vota

Completa o CAPTCHA e envia o voto

4

Verificação na API

O seu servidor consulta a API para confirmar o voto

5

Recompensar jogador

O servidor entrega a recompensa dentro do jogo

Primeiros passos - Guia rápido

Escolha o método de integração que melhor se adapta às suas necessidades:

RECOMENDADO

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

Começar com Vote4Buff

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

Usar API básica

Passos gerais de configuração

1

Registe o seu servidor

Crie uma conta e adicione o seu servidor à nossa toplist em https://metin2-toplist.net/servers/create

2

Obtenha as suas credenciais API

No painel do servidor encontrará o ID e a chave API exclusivos necessários para autenticação.

3

Escolha o método de integração

Transfira o Vote4Buff para uma solução pronta ou use a nossa API para integração personalizada.

4

Teste e publique

Teste o sistema de votação exaustivamente e depois publique no servidor oficial.

Endpoint da API (para implementações personalizadas)

Nota

Se estiver a usar o Sistema Vote4Buff (recomendado), esta API já está integrada! Esta secção é para quem deseja uma implementação própria.

GET

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

*É necessário fornecer ip ou account_id (ou ambos)

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:

Resposta de sucesso

{
    "success": true,
    "voted": true,
    "last_vote": "2025-11-11T14:30:00Z",
    "next_vote_in": 0,
    "message": "Vote verified successfully"
}

Resposta quando não existe voto

{
    "success": true,
    "voted": false,
    "message": "No recent vote found"
}

Resposta de erro

{
    "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

Implementação com cURL 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);
}

// Usage Example
$apiToken = 'YOUR_API_TOKEN_HERE';
$playerIP = $_SERVER['REMOTE_ADDR']; // Or get from your game server

$result = checkVote($apiToken, $playerIP);

if ($result['success'] && $result['voted']) {
    // Player has voted! Give reward
    echo "Vote verified! Rewarding player...";
    giveReward($playerName); // Your reward function
} else {
    echo "No valid vote found. Please vote first!";
}
?>

Exemplo em Python

Implementação com Requests em Python

import requests
import json

def check_vote(api_token, player_ip):
    """
    Check if a player has voted for the server
    """
    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)}'}

# Usage Example
api_token = 'YOUR_API_TOKEN_HERE'
player_ip = '123.456.789.012'

result = check_vote(api_token, player_ip)

if result.get('success') and result.get('voted'):
    print("Vote verified! Rewarding player...")
    # Give reward to player
else:
    print("No valid vote found. Please vote first!")

Exemplo em C++ (para servidores)

Implementação com libcurl em C++

#include <curl/curl.h>
#include <string>
#include <sstream>

// Callback function for cURL
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;
    CURLcode res;
    std::string readBuffer;

    curl = curl_easy_init();
    if(curl) {
        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);

        res = curl_easy_perform(curl);
        curl_easy_cleanup(curl);

        if(res == CURLE_OK) {
            // Parse JSON response (you'll need a JSON library like nlohmann/json)
            // Check if readBuffer contains "\"voted\":true"
            return readBuffer.find("\"voted\":true") != std::string::npos;
        }
    }
    return false;
}

// Usage in your game server
void OnPlayerRequestReward(const std::string& playerName, const std::string& playerIP) {
    std::string apiToken = "YOUR_API_TOKEN_HERE";

    if(CheckVote(apiToken, playerIP)) {
        // Give reward to player
        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

Implementação com Fetch em 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 error! status: ${response.status}`);
        }

        return await response.json();
    } catch (error) {
        console.error('API request failed:', error);
        return { success: false, message: error.message };
    }
}

const apiToken = 'YOUR_API_TOKEN_HERE';
const playerIP = '123.456.789.012';

checkVote(apiToken, playerIP).then(result => {
    if (result.success && result.voted) {
        console.log('Vote verified! Rewarding player...');
        // Give reward to player
    } else {
        console.log('No valid vote found. Please vote first!');
    }
});

Guia de integração

Boas práticas de segurança

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 voted for 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

Jogador: escreve /vote no jogo

↓

Servidor: abre o navegador na página de voto

↓

Jogador: vota na toplist

↓

Jogador: escreve /claim ou clica em "Recolher recompensa"

↓

Servidor: chama a API com o IP do jogador

↓

API: devolve voted=true

↓

Servidor: envia a recompensa ao jogador

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.

Suporte e recursos

Suporte por email

Obtenha ajuda por email

Contactar suporte

Comunidade Discord

Junte-se à nossa comunidade

Entrar no Discord

Dica profissional

Teste a integração com uma conta de testes antes de publicar. Garanta que cobre todos os cenários e erros.

Links rápidos

Navegação rápida