Integración de votos

Metin2-Help registra y valida el voto. El sitio de tu servidor identifica al jugador, concede la recompensa en su propio sistema y confirma el procesamiento. No recibimos credenciales del juego y no cambiamos monedas ni objetos.

Guía para Apache, Nginx, Laravel, WordPress y Cloudflare

El envío, la publicación aprobada, la votación, el widget estándar y la API básica son gratuitos. No hay suscripción.

  1. Registrar el servidor — Una cuenta con sesión completa el formulario y lo envía a revisión o lo guarda como borrador.
  2. Verificar el dominio — Publica el token en /.well-known/metin2-help-verify.txt o en un registro DNS TXT. Un moderador puede confirmarlo a mano.
  3. Obtener la aprobación — Solo un servidor aprobado con la propiedad verificada puede generar una clave de API.
  4. Generar la clave — La clave se muestra una vez. Guárdala en el servidor, no en el navegador de los jugadores.
  5. Instalar el script — El ejemplo de PHP crea una intención y, por separado, lee los votos no reclamados.
  6. Crear la intención — Tu sitio envía el identificador del jugador y recibe una URL con un token opaco. El token caduca en 30 minutos.
  7. Enviar al jugador — El jugador inicia sesión en Metin2-Help y vota. Abrir la URL no es un voto.
  8. Comprobar los votos — Consultas los votos no reclamados con la clave del servidor.
  9. Conceder la recompensa — La concedes en tu propia base de datos o sistema. Metin2-Help no la concede.
  10. Confirmar — Envías los ID de voto procesados. Repetir la misma confirmación no crea un segundo recibo.
  11. Reintentar tras un error — Si la confirmación no llega, el voto sigue sin reclamar y puedes reintentar. La entrega al juego no es exactamente una vez.
  12. Rotar la clave — La rotación revoca la clave antigua al momento. Actualiza el script antes de la siguiente llamada.

API

  • POST /api/v1/servers/{public_id}/vote-intents
  • GET /api/v1/vote-intents/{intent_id}
  • GET /api/v1/servers/{public_id}/votes/unclaimed
  • POST /api/v1/servers/{public_id}/votes/claim
  • GET /api/v1/servers/{public_id}/stats
  • GET /api/v1/servers/{public_id}/integration

¿Qué instalo en mi sitio?

  1. El ID público del servidor, visible en la página de edición.
  2. La clave de API, solo cuando se genera, guardada en tu backend.
  3. El enlace de voto simple, que puede vivir en un botón HTML y no identifica a un jugador.
  4. El flujo de voto con recompensa, que necesita tu backend.
  5. El ejemplo de PHP, que adaptas a la recompensa local.
  6. Los endpoints de la API de abajo.
  7. La consulta de votos no reclamados y la confirmación, después de registrar la recompensa local.

Enlace de voto simple

Se puede poner en un botón HTML. No contiene un id de jugador y no concede una recompensa por sí solo.

Voto con recompensa

  1. Tu sitio identifica al jugador con sesión.
  2. Crea una intención por la API y recibe vote_url.
  3. Redirige al jugador a vote_url. Abrirla no es un voto.
  4. Después del voto, consultas los votos no reclamados.
  5. Concedes la recompensa en tu propio sistema y la registras en local por Vote ID.
  6. Confirmas el procesamiento. Repetir la misma confirmación no crea un segundo registro.

already_claimed solo significa que Metin2-Help registró la confirmación. No demuestra que la recompensa local se haya concedido. Tu diario único de Vote ID es la prueba. Si la recompensa y el diario comparten una base de datos, mantenlos en una transacción. Si no es posible, retoma desde el diario; esto no es una entrega exactamente una vez dentro del juego.

Sistemas al estilo Vote4Coins

El enlace de Vote4Coins en la página de integración del servidor tiene la forma https://metin2-help.com/api/vote/{public_id}/{token}/ID. El token no es la clave de API. Sustituir ID abre la página para esa cuenta, pero no crea una intención de voto y no confirma una recompensa. Si ID no cambia, el voto no se asocia a un jugador. Una recompensa confirmada necesita la conexión avanzada.

Algunos sitios solo aceptan un callback con forma https://tu-sitio/api/vote4coins/callback/INDEX?username=PLAYER&key=SECRET. Esa forma es un ejemplo. No es un endpoint de Metin2-Help ni una clave real.

Metin2-Help no llama automáticamente a un callback arbitrario del propietario. La API actual usa una intención de voto, un voto validado, sondeo y una confirmación de claim.

Un sistema que solo acepta una URL de callback necesita un adaptador en el backend del propietario o soporte explícito del protocolo. Metin2-Help no cambia tu sitio y no accede a la base de datos del juego.

PHP propio: el script de ejemplo puede ejecutarse bajo demanda o desde cron. Laravel: el mismo cliente HTTP en un comando programado. Cron: sondea y confirma después de que el diario local haya registrado la recompensa.

Sin cambiar el núcleo del juego puedes guardar el diario y la recompensa en una base de datos que controlas. La entrega a la cuenta del juego sigue siendo tu código.

Términos distintos

URL de voto. La página que abre un jugador para votar. Un voto simple usa la página pública. Un voto con recompensa usa la vote_url devuelta a tu backend, con un token opaco.

URL de verificación de la API. Un endpoint que tu sitio pregunta para saber si existe un voto. En Metin2-Help es la API con la clave en una cabecera, no una URL que contenga la clave.

Callback. Una dirección de tu dominio a la que algún sistema externo llamaría después de un voto. Metin2-Help no llama automáticamente a un callback elegido en otro software.

Postback. El mismo tipo de llamada inversa, a menudo un GET o POST a tu sitio. Una tabla de Vote4Coins puede mostrar su propio postback, no el enlace de voto que introdujiste.

Player ID. El identificador de cuenta del sitio del servidor. En el enlace de Vote4Coins sustituye el segmento ID solo cuando ese sitio hace la sustitución. En la integración avanzada el backend lo envía como player_ref. Metin2-Help no comprueba que exista en el juego.

Username. Puede ser el mismo valor que player_ref si ese es el identificador que usas. Metin2-Help no comprueba que exista en el juego.

Clave de API. El secreto que usa tu backend para autenticarse en Metin2-Help. Se muestra una vez y no va en el HTML.

Secreto de callback. Un secreto del sistema de tu sitio. No es la clave de API de Metin2-Help y no debe enviarse a nosotros.

Vote Intent. El registro temporal que une a un jugador con un voto que todavía no ha ocurrido.

Claim. Tu confirmación de que procesaste el Vote ID. Por sí sola no demuestra que la recompensa haya llegado al juego.

Qué se puede establecer sobre Vote4Coins

El nombre Vote4Coins cubre varias implementaciones con protocolos distintos. No hay un único contrato público que Metin2-Help pueda declarar compatible.

Algunos toplists envían JSON por POST a un callback configurado por el propietario, con un userid, una marca de tiempo y un hash. Otros esperan que el sitio del propietario consulte una API y reciba 0 o 1. Otros generan, en el dominio del propietario, un endpoint de callback por cada registro.

Una tabla que muestra direcciones con forma https://tu-sitio/api/vote4coins/callback/0?username={username}&key=SECRET está, por esa forma, mostrando endpoints de tu sitio. No son los enlaces de voto que se introdujeron y no son endpoints de Metin2-Help. Claves distintas en filas distintas encajan con secretos generados en local, uno por fila.

Esta observación no se comprobó en un panel privado de un sitio, y no se envió ninguna petición a esas direcciones. No la trates como una descripción de cada instalación.

Metin2-Help no llama a esos callbacks. Su propio webhook es aparte, opcional, apagado por defecto, solo HTTPS, y solo a la dirección guardada en el editor del servidor, con una firma HMAC. No sustituye a un postback de Vote4Coins.

Si tu instalación puede llamar a una API HTTPS con una cabecera X-API-Key, adapta el backend al contrato de arriba. Si solo acepta un postback recibido en su propio callback, necesitas un adaptador en tu sitio: el adaptador comprueba el voto con Metin2-Help y solo entonces puede avisar al sistema local. Metin2-Help no hace esa llamada.

Para saber qué puede hacer tu instalación, revisa su documentación: si acepta un cliente HTTP con una cabecera propia, solo una URL de voto, o solo un postback entrante. Sin ese detalle, la integración no se puede dar por funcionando.

¿Qué copio, y dónde?

A. Solo quiero votos de clasificación. Copia el enlace público simple o un widget. No copies la clave de API.

B. Tengo un sitio PHP y puedo cambiar el backend. Pon la clave y el Public ID en la configuración del servidor, y usa el ejemplo de PHP: intención, vote_url, votos no reclamados, recompensa local, claim.

C. Tengo Vote4Coins y puedo llamar a una API propia. Tu backend tiene que adaptarse al contrato de Metin2-Help. No pegues la clave en un campo de callback.

D. Tengo Vote4Coins que solo acepta un postback. Metin2-Help no llama a ese postback. Sin un adaptador en tu sitio, las recompensas automáticas no están disponibles.

E. No puedo cambiar el código del sitio. Puedes pegar el enlace de Vote4Coins en el campo existente. Si el sitio no sustituye ID, el voto no se liga a un jugador. Una recompensa confirmada se queda en la integración avanzada.

El enlace de Vote4Coins y el identificador

El enlace termina en ID. Un sitio que sustituye ID abre la página para esa cuenta, pero no crea una intención de voto. Un sitio que deja ID sin cambiar no asocia a un jugador. El token del enlace no es la clave de API. Una recompensa confirmada se queda en la conexión avanzada: una intención creada por el sitio, un voto confirmado y claim.

Voto simple: el jugador abre la página y vota, sin un ID de jugador asociado.

Voto con recompensa: tu sitio crea la intención, y la recompensa se concede solo en tu lado después de la confirmación.

POST /vote-intents

{
  "player_ref": "Hero.1",
  "idempotency_key": "player-hero-1-try"
}
{
  "intent_id": "0123456789abcdef01234567",
  "vote_url": "https://metin2-help.com/servere/{slug}/vot/{token}",
  "expires_at": "2026-11-14 02:00:00",
  "status": "pending"
}

POST /votes/claim

{ "vote_ids": [120] }
{ "data": [{ "vote_id": 120, "result": "claimed" }] }

401 significa que la clave falta o es incorrecta. 403 significa otro servidor, un servidor no aprobado o una propiedad no verificada. 404 es una intención inexistente. 422 es un identificador no válido. 429 es el límite de peticiones.

El webhook es opcional y permanece apagado hasta que lo actives. La firma es HMAC-SHA256 sobre la marca de tiempo, el nonce y el cuerpo. El sondeo sigue siendo el método de recuperación. No enviamos a direcciones internas.

La promoción de pago no está activa y no cambia el orden de los votos.

Descargar el ejemplo de PHP

Descargar el ejemplo de PHP