API

31 октября 2011

Начиная с версии 2.2 PHP Garant Checker поддерживает проверку и выдачу результатов внешним приложениям с использованием API. Формат вывода — XML. В данном документе мы подробно рассмотрим вывод.

Работа с API

Работа с API чекера осуществляется посредством отправки на сервер GET запроса с двумя обязательными параметрами:

  1. id — SteamID, кастомный ID, либо полная ссылка на учётную запись Steam, которую нужно проверить на принадлежность к спискам;
  2. token — уникальный токен приложения, представляющий собой 16-знаковую строку, содержащую случайную последовательность букв и цифр. Данный токен генерируется админкой сервера по уникальной фразе с добавлением энтропии. Токен предназначен для идентификации приложения и определения его прав.

Пример запроса: http://имя_сайта/api.php?id={ПОЛЬЗОВАТЕЛЬ}&token={ТОКЕН}

Коды ответов сервера

На отправленный GET запрос сервер ответит:

  • 200, mime-type: application/xml — запрос успешно выполнен, авторизация по токену пройдена. В ответе будет присутствовать XML-файл с результатами;
  • 403, mime-type: text/html — произошла ошибка, в доступе отказано. Вы ввели либо неверные параметры, либо недействительный токен, либо срок действия токена завершён, либо он заблокирован, либо сменился IP, на который был выдан токен.

Результат успешной обработки запроса

В результате Вы получите XML файл для дальнейшего использования в Вашем приложении.

Пример успешной проверки:

<?xml version="1.0" encoding="utf-8" ?>
<userprofile>
<qstatus>OK</qstatus>
<steamID><![CDATA[STEAM_0:0:29275917]]></steamID>
<nickname><![CDATA[[ECTeam] KT]]></nickname>
<avatar><![CDATA[http://media.steampowered.com/steamcommunity/public/images/avatars/27/27f4cd666fbd68c460e9c71ec4ed26218f24ce56_full.jpg]]></avatar>
<olstatus><![CDATA[offline]]></olstatus>
<customdescr><![CDATA[Тестовое кастомное описание.]]></customdescr>
<sitestatus>4</sitestatus>
<isbanned>0</isbanned>
<isf2p>0</isf2p>
<permalink><![CDATA[http://steamcommunity.com/profiles/76561198018817562/]]></permalink>
</userprofile>

Теперь рассмотрим все поля и их допустимые значения:

  • userprofile — корневой элемент XML-файла;
  • qstatus — результат проверки. Может принимать значение OK (успешно) или ERROR (ошибка в запросе, либо недействительный URL профиля, либо недоступность серверов Steam);
  • steamID — SteamID проверяемого пользователя в стандартном формате;
  • nickname — ник проверяемого пользователя в Steam;
  • avatar — прямая ссылка на аватар пользователя;
  • olstatus — текущий статус пользователя. Возможны варианты: online, in-game и offline. При использовании кэширования статус всегда отображается как offline;
  • customdescr — содержит кастомное описание для проверяемого пользователя если оно указано в базе данных. Поддерживается HTML-код. При отсутствии поле не выводится;
  • sitestatus — указывает принадлежность пользователя к спискам на сайте. Возможные значения: 0 (владелец), 1 (принадлежит к списку гарантов), 2 (принадлежит к белому списку), 3 (принадлежит к чёрному списку), 4 (не принадлежит ни к одному из списков, простой пользователь);
  • isbanned — отображает статус VAC-банов на аккаунте. Принимает значение 1 при наличии хотя бы одной VAC-забаненной игры, в остальных случаях 0;
  • isf2p — принимает значение 1 при отсутствии на аккаунте купленных игр, в остальных случаях 0;
  • permalink — содержит постоянную (неизменяемую) ссылку на профиль Steam проверяемого пользователя.

Пример ошибки в запросе (введена ссылка на несуществующий профиль Steam):

<?xml version="1.0" encoding="utf-8" ?>
<userprofile>
<qstatus>ERROR</qstatus>
</userprofile>

Получение токена авторизации

Для получения токена авторизации обратитесь к авторам по электронной почте. В своём письме укажите следующие данные:

  • что за проект Вы хотите реализовать? Если проектом является сайт, то укажите его домен;
  • IP-адрес, с которого будут производиться обращения к нашему API (если IP адрес изменится, то Вы должны написать нам для внесения изменений в политиках доступа);
  • другие сведения, которые бы Вы хотели сообщить о своём проекте.

Администрация оставляет за собой право отказать в предоставлении доступа к API, а также блокировать токены доступа без объяснения причин вынесения такого решения.

Комментирование отключено.