Ir a la guía

Documentación 9.6.24

API y credenciales

Usa la autenticación de la integración instalada. El puente es una cola de operaciones, no una interfaz SQL general.

Separar permisos#

Licencias, permisos de usuario y tokens de carga cumplen funciones distintas. Los tokens caducan y solo permiten cargar pruebas, no gestionar el panel.

Gestionar errores#

Evita bucles rápidos ante errores, límites o tiempos de espera. No repitas automáticamente escrituras financieras inciertas. No publiques encabezados de autenticación en URL, cliente o registros.

Relacionar endpoint y permiso#

No existe clave universal. La licencia autentica el puente SaaS; tokens de componentes pueden requerir scopes. Las acciones de navegador requieren rol, permisos y CSRF cuando corresponda. Tokens de carga se limitan a contexto, servidor y solicitud, no administración.

El ejemplo solo muestra cabeceras. El marcador no es válido; el recurso genera el protocolo. Añadirlas a JSON arbitrario no crea tarea. Mantén autorización entre servidores, no en navegador, URLs, analíticas o errores compartidos.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

Distinguir tarea y respuesta HTTP#

El puente acepta POST JSON, no SQL o tablas elegidas libremente. pending o claimed sigue en curso. Revisa resultado final antes de anunciar éxito.

  • 401: verifica clave del servidor correcto y no regenerada.
  • 403 bridge_disabled / subscription_inactive / permission_denied: revisa la tarjeta Tosun Connect del servidor (bridge_disabled indica que la conexión se desactivó allí), suscripción y permisos; repetir no concede acceso.
  • 405 / 415: corrige método y JSON Content-Type; no reenvíes datos malformados constantemente.
  • 429: respeta Retry-After y espera; el puente limita simultaneidad y aumenta retraso al fallar.
  • 503 / timeout: registra hora y referencia sin secretos; investiga conexión.

Probar una operación pequeña#

Usa servidor de pruebas o personaje controlado. Lee una vez, verifica personaje y compara con el juego. Operaciones fijas y páginas no son un dump completo. Guarda referencia para distinguir tarea de repetición.

Registra solo estado, duración y referencia no secreta. Retira tokens y datos personales de reportes públicos. Retesta al cambiar claves, permisos o paquete.

No distribuyas un token administrativo a todo. Usa scopes mínimos y revoca credenciales sin uso. Al cambiar endpoint o permisos vuelve a probar éxito y rechazo, no confíes en una prueba antigua.

  1. Comprueba éxito propio y rechazo de claves erróneas/revocadas.
  2. Personal sin permiso debe ser rechazado; no pruebes sistemas de otros clientes.
  3. Muestra pending, failed, expired y done de forma distinta, sin éxito genérico.
  4. Ante unknown_outcome financiero, verifica saldo vivo y auditoría antes de otra escritura.

Separar solicitudes del navegador y del servidor#

/api/tenant_db_bridge.php autentica al personal mediante sesión. Requiere POST, application/json, _csrf válido y cuenta del tenant actual; limita el cuerpo a 4096 bytes. action puede ser enqueue o result. Enviar una licencia no crea sesión. Poder leer no permite escribir dinero; la operación tiene autorización propia.

/api/server_db_bridge.php intercambia salud, trabajos y resultados desde el servidor de juego. Usa POST JSON y licencia Bearer, con límite de 65536 bytes. Cookies y CSRF no sustituyen este protocolo. Identifique primero la ruta; añadir credenciales de otra ruta no corrige autenticación. No imite el protocolo integrado con JSON arbitrario.

Distinguir aceptación de finalización#

ok=true puede indicar HTTP aceptado sin demostrar que terminó la operación del juego. Siga id, operation y status dentro de request. pending espera; claimed fue tomado por el servidor. done terminó, failed falló y expired venció. Mantenga el contexto de server_id y request_id al consultar resultados.

Revise estado final y error antes de mostrar éxito. Una solicitud pendiente equivalente puede devolver el trabajo existente; no garantiza repeticiones ilimitadas permanentes. Detenga escrituras de dinero ante unknown_outcome. Timeout o resultado inválido no prueban que el saldo no cambió. Compare saldo vivo, objetivo anterior y auditoría de esa operación; no borre pruebas para reintentar.

Crear un informe pequeño y limpio#

Para 405 revise método; para 415, JSON Content-Type; para 400, JSON válido y campos permitidos. En navegador, 401 requiere revisar sesión y 419 validar CSRF; vuelva a abrir desde navegación normal. Para 404 compruebe contexto sin probar datos de otro cliente. Espere trabajos activos ante 429.

Para 503 o red incierta, anote hora, endpoint, estado HTTP, operación y referencia no secreta. El ejemplo es una nota de soporte, no cuerpo de solicitud. Excluya cookies, Authorization, _csrf, licencias y datos de jugadores. Corrija la etapa responsable en vez de repetir rápidamente; valide primero con una lectura controlada.

Endpoint: /api/tenant_db_bridge.php
Method: POST
HTTP status: 419
Error: csrf_failed
Operation: players.list
Reference: YOUR_REQUEST_REFERENCE
Time: YOUR_ERROR_TIME

Leer una página de jugadores con dos cuerpos JSON verificados#

Este ejemplo lee la primera página de jugadores desde un navegador que ya tiene una sesión iniciada en el panel de tu cuenta. El servidor 123 y el ID de solicitud son ficticios: usa tu servidor y request.id de la respuesta de enqueue. Sustituye CURRENT_PAGE_CSRF por el valor válido de la página actual. No es una licencia del servidor y no debe copiarse en una nota de soporte. Se necesita un POST al mismo origen, application/json y la sesión del navegador. La lectura exige servers.manage o players.view; enqueue se rechaza en la demo de solo lectura.

El primer cuerpo envía únicamente un cursor vacío; esta operación puede devolver como máximo 25 registros por página. No añadas limit, SQL, nombres de tablas, cadenas de conexión ni parámetros de dinero. Si la respuesta inicial indica pending, consulta ese trabajo con el segundo cuerpo en lugar de crear otro. Cuando esté done, lee request.result.items. Si request.result.has_more es true, usa request.result.next_cursor en la siguiente solicitud de página deliberada. Interpreta una lista vacía junto con su estado de finalización correcta. Estas plantillas no incluyen credenciales válidas. Limita la primera prueba a una lectura en tu servidor de pruebas; no las uses para dar acceso administrativo a extensiones públicas del navegador.

POST /api/tenant_db_bridge.php
Content-Type: application/json

Enqueue:
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "enqueue",
  "operation": "players.list",
  "params": {"cursor": ""}
}

Result (use request.id from the enqueue response):
{
  "_csrf": "CURRENT_PAGE_CSRF",
  "server_id": 123,
  "action": "result",
  "request_id": "00112233445566778899aabbccddeeff"
}

Separar el tiempo de espera HTTP del plazo del trabajo#

Supón que enqueue se acepta a las 14:03:10 y guardas request.id, pero una consulta posterior de result pierde la conexión. Una petición HTTP del panel puede detenerse a los doce segundos; el trabajo en cola vence 120 segundos después de crearse. Cancelar la petición del navegador no cancela ese trabajo en el servidor. No presentes “no hubo respuesta” como un resultado expired o failed. Conserva el ID conocido y consulta result con el mismo server_id cuando vuelva la conexión. El panel normalmente comprueba los resultados pendientes cada tres segundos; no añadas un bucle de consultas continuas.

Si la lectura players.list termina en expired con request_expired, registra el fallo, corrige la conectividad y después inicia una nueva lectura deliberada. En player.money.set, el vencimiento después de claimed o un resultado inválido pueden producir unknown_outcome: eso no demuestra que el saldo no haya cambiado. Detén las escrituras y revisa el saldo actual y el registro de la operación existente. Los resultados no son un archivo ilimitado; los registros vencidos se eliminan posteriormente mediante limpieza acotada. Si ya no encuentras el registro, no adivines el resultado enviando otro cambio de dinero. Para soporte guarda solo una referencia no secreta, la hora, operation y el último estado conocido.

Illustrative observations; not an API request body:
14:03:10  enqueue accepted; save request.id
14:03:22  HTTP timeout; job outcome is not established
Later     result with the same server_id + request_id

Read:  expired + request_expired -> investigate before a new read
Write: expired + unknown_outcome -> stop writes and reconcile