Документация 9.6.24

API и учётные данные

Используйте протокол установленной интеграции. Мост — очередь операций, а не общий SQL-интерфейс.

Разделяйте права#

Лицензии, права пользователя и токены загрузки имеют разные назначения. Токены истекают и разрешают только загрузку доказательств, не управление панелью.

Обработка ошибок#

Не создавайте частые циклы повторов при ошибках и лимитах. Не повторяйте автоматически финансовую запись с неизвестным результатом. Не публикуйте заголовки авторизации в URL, клиенте или логах.

Сопоставляйте endpoint и права#

Общего ключа для всего нет. Лицензия авторизует SaaS-мост; токены компонентов могут требовать scopes. Браузерные действия требуют роль, права и CSRF где нужно. Загрузка доказательств ограничена контекстом, сервером и запросом, без административного доступа.

Пример — только заголовки. Значение условное, тело протокола создаёт ресурс. Произвольный JSON не становится заданием. Авторизацию держите между серверами, не в браузере, URL, аналитике и общих ошибках.

Authorization: Bearer YOUR_SERVER_LICENSE
Content-Type: application/json

Отличайте HTTP от результата задания#

Мост принимает POST JSON, не свободный SQL или имя таблицы. pending/claimed ещё выполняется. До сообщения об успехе проверьте конечный результат.

401: правильная лицензия сервера, не заменённая.
403 bridge_disabled / subscription_inactive / permission_denied: карточка Tosun Connect сервера (bridge_disabled — соединение там отключено), подписка, права; повтор не даёт доступ.
405 / 415: исправьте метод и JSON Content-Type, не повторяйте неверный JSON постоянно.
429: соблюдайте Retry-After и паузу; мост ограничивает параллельность и увеличивает задержку ошибок.
503 / timeout: сохраните время и очищенную ссылку задания, проверьте сеть.

Тест небольшой операцией#

Используйте тестовый сервер или персонажа. Прочитайте один раз, сверяйте персонажа и данные с игрой. Ограниченные операции и страницы не являются полным дампом. Храните reference для различения повторов.

Логируйте только статус, длительность и несекретный reference. Удаляйте токены и персональные данные из общих отчётов. После изменения ключей, прав или пакета повторяйте проверки.

Не раздавайте общий административный токен всем интеграциям. Минимальные scopes, отзыв неиспользуемых данных. При изменении endpoint или прав проверяйте и успех, и отказ, не старый успешный лог.

Проверьте свой успех и отказ неверных/отозванных ключей.
Персонал без права должен получать отказ; не тестируйте чужих клиентов.
Показывайте pending, failed, expired и done отдельно, не общий успех.
При денежном unknown_outcome сверяйте живой баланс и аудит до новой записи.

Разделяйте браузерный запрос и серверный протокол#

/api/tenant_db_bridge.php авторизует сотрудника через сессию. Нужны POST, application/json, действующий _csrf и аккаунт текущего tenant; предел тела 4096 байт. action принимает enqueue или result. Лицензия не создаёт браузерную сессию. Право читать не разрешает запись денег; операция проверяется отдельно.

/api/server_db_bridge.php обменивается состоянием, заданиями и результатами игрового сервера. Использует POST JSON и лицензию Bearer с пределом 65536 байт. Cookie и CSRF не заменяют протокол. Сначала определите маршрут; чужие для него данные не исправят авторизацию. Не имитируйте встроенный протокол произвольным JSON.

Отличайте принятие от завершения#

ok=true может подтверждать принятие HTTP без завершения действия в игре. Проверяйте id, operation и status внутри request. pending ожидает; claimed получен сервером. done завершён, failed не выполнен, expired просрочен. Сохраняйте тот же контекст server_id и request_id при чтении результата.

Проверьте конечный статус и error до сообщения об успехе. Одинаковый ожидающий запрос может вернуть существующее задание; это не постоянная гарантия неограниченных повторов. При unknown_outcome остановите запись денег. Timeout или неверный результат не доказывают отсутствие изменения. Проверьте живой баланс, прежнюю цель и аудит; не удаляйте свидетельства для повторения.

Готовьте короткий очищенный отчёт#

Для 405 проверьте метод; 415 — JSON Content-Type; 400 — JSON и разрешённые поля. В браузере 401 относится к сессии, 419 — CSRF; откройте страницу обычной навигацией. Для 404 проверьте контекст без чужих клиентских данных. При 429 дождитесь текущих заданий.

Для 503 или неопределённого сетевого результата запишите время, endpoint, HTTP-статус, операцию и несекретную ссылку. Пример является заметкой поддержки, не телом запроса. Исключите cookies, Authorization, _csrf, лицензии и данные игроков. Исправьте нужный этап вместо частых повторов; сначала проверьте одно контролируемое чтение.

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

Прочитайте страницу игроков двумя проверенными JSON-запросами#

Пример читает первую страницу игроков из браузера, в котором уже выполнен вход в панель вашей учётной записи. Сервер 123 и идентификатор запроса вымышлены: подставьте свой сервер и request.id из ответа enqueue. Вместо CURRENT_PAGE_CSRF используйте действительное значение текущей страницы. Это не лицензия сервера; не копируйте его в обращение в поддержку. Нужны POST на тот же источник, application/json и браузерная сессия. Для чтения требуется servers.manage или players.view; в деморежиме только для чтения enqueue отклоняется.

Первое тело передаёт только пустой cursor; операция возвращает не более 25 записей на страницу. Не добавляйте limit, SQL, название таблицы, строку подключения или параметры денег. При pending проверяйте тот же запрос вторым телом, а не ставьте в очередь новый. После done читайте request.result.items. Если request.result.has_more равен true, используйте request.result.next_cursor при следующем осознанном запросе страницы. Пустой список оценивайте вместе со статусом успешного завершения. В шаблонах нет работающих секретных данных. Ограничьте первую проверку одним чтением на своём тестовом сервере; пример не предназначен для выдачи административного доступа публичным расширениям браузера.

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

Отделяйте сетевой тайм-аут от срока выполнения задания#

Допустим, enqueue принят в 14:03:10, request.id сохранён, но последующий вызов result потерял соединение. Отдельный HTTP-запрос панели может прерваться через 12 секунд; задание в очереди истекает через 120 секунд после создания. Прерывание браузерного запроса не отменяет серверное задание. Не представляйте «ответ не пришёл» как результат expired или failed. Сохраните известный идентификатор и после восстановления связи запросите result с тем же server_id. Обычная панель проверяет ожидающий результат раз в три секунды; не добавляйте непрерывный цикл опроса.

Если чтение players.list завершилось expired с request_expired, запишите ошибку, восстановите соединение и затем начните новое осознанное чтение. Для player.money.set истечение после claimed или некорректный результат могут дать unknown_outcome: это не доказывает, что баланс не изменился. Остановите новые записи и проверьте текущий баланс и существующую операцию. Результаты не хранятся бесконечно; просроченные записи позже удаляются ограниченной очисткой. Если запись уже не найдена, не выясняйте её исход новой денежной операцией. Для поддержки сохраняйте только несекретную ссылку на запрос, время, operation и последний известный статус.

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