PHP Garant Checker начиная с версии 2.2 поддерживает проверку и выдачу результатов внешним приложениям с использованием API. Формат вывода — XML. В данном документе мы подробно рассмотрим вывод.
Текущая версия API: 3.0.
Работа с API
Работа с API чекера осуществляется посредством отправки на сервер GET запроса с двумя (если требуется вызвать функцию API) или тремя обязательными параметрами (если выполняется проверка пользователя или его друзей):
- action — имя функции, которую необходимо вызвать. Каждая функция имеет свой набор обязательных параметров;
- token — уникальный токен приложения, представляющий собой 16-знаковую строку, содержащую случайную последовательность букв и цифр. Данный токен генерируется админкой сервера по уникальной фразе с добавлением энтропии. Токен предназначен для идентификации приложения и определения его прав;
- id — SteamID, кастомный ID, либо полная ссылка на учётную запись Steam, которую нужно проверить на принадлежность к спискам.
Пример запроса:
http://имя_сайта/api.php?action={ФУНКЦИЯ}&token={ТОКЕН}&id={ID/URL}
Доступные функции API
- check — проверить пользователя по базе данных;
- friends — проверить всех друзей пользователя;
- info — вывод информации о токене доступа и версии API;
- test — проверить валидность токена доступа.
Коды ответов сервера
На отправленный GET запрос сервер ответит:
- 200, mime-type: application/xml — запрос успешно выполнен, авторизация по токену пройдена. В ответе будет присутствовать XML-файл с результатами;
- 403, mime-type: text/html — произошла ошибка, в доступе отказано. Вы ввели либо неверные параметры, либо недействительный токен, либо срок действия токена завершён, либо он заблокирован, либо сменился IP, на который был выдан токен.
Проверка пользователя по базе данных
Для проверки пользователя по базе данных выполните запрос:
http://имя_сайта/api.php?action=check&token={ТОКЕН}&id={ID/URL}
В результате Вы получите XML файл для дальнейшего использования в Вашем приложении. Пример успешной проверки пользователя (функция check):
<?xml version="1.0" encoding="utf-8" ?> <userprofile> <qstatus>OK</qstatus> <steamID><![CDATA[STEAM_0:0:29275917]]></steamID> <steamID64><![CDATA[76561198018817562]]></steamID64> <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> <istrbanned>0</istrbanned> <permalink><![CDATA[http://steamcommunity.com/profiles/76561198018817562/]]></permalink> </userprofile>
Теперь рассмотрим все поля и их допустимые значения:
- userprofile — корневой элемент XML-файла;
- qstatus — результат проверки. Может принимать значение OK (успешно) или ERROR (ошибка в запросе, либо недействительный URL профиля, либо недоступность серверов Steam);
- steamID — SteamID проверяемого пользователя в стандартном формате;
- steamID64 — SteamID проверяемого пользователя;
- nickname — ник проверяемого пользователя в Steam;
- avatar — прямая ссылка на аватар пользователя;
- olstatus — текущий статус пользователя. Возможны варианты: online, in-game и offline. При использовании кэширования статус всегда отображается как offline;
- customdescr — содержит кастомное описание для проверяемого пользователя если оно указано в базе данных. Поддерживается HTML-код. Выводится всегда;
- sitestatus— указывает принадлежность пользователя к спискам на сайте. Возможные значения:
- 1 — принадлежит к списку гарантов;
- 2 — принадлежит к белому списку;
- 3 — принадлежит к чёрному списку;
- 4 — не принадлежит ни к одному из списков, простой пользователь;
- 5 — находится в чёрном списке аукциона;
- 6 — является сотрудником сайта;
- 7 — премиум-пользователь (донатор);
- 8 — находится в списке ненадёжных;
- isbanned — отображает статус VAC-банов на аккаунте. Принимает значение 1 при наличии хотя бы одной VAC-забаненной игры, в остальных случаях 0;
- isf2p — принимает значение 1 при отсутствии на аккаунте купленных игр, в остальных случаях 0;
- istrbanned — возвращает 0 при отсутствии блокировок торговли (трейда), 1 — торговля отключена на длительный срок или пожизненно, 2 — испытательный срок.
- permalink — содержит постоянную (неизменяемую) ссылку на профиль Steam проверяемого пользователя.
Пример ошибки в запросе (введена ссылка на несуществующий профиль Steam):
<?xml version="1.0" encoding="utf-8" ?> <userprofile> <qstatus>ERROR</qstatus> </userprofile>
Получение и проверка списка друзей
Для проверки всех друзей пользователя вызовите функцию friends. Пример:
http://имя_сайта/api.php?action=friends&token={ТОКЕН}&id={STEAMID64}
В случае успеха сервер выдаст XML такого вида (функция friends):
<friends> <friend> <steamid><![CDATA[STEAM_0:0:16969344]]></steamid> <friend_since><![CDATA[1279542989]]></friend_since> <steamid64><![CDATA[76561197994204416]]></steamid64> <sitestatus>4</sitestatus> <customdescr><![CDATA[Тестовое описание!]]></customdescr> </friend> </friends>
Рассмотрим поля:
- steamid — SteamID проверяемого пользователя в стандартном формате;
- friend_since — дата добавления в друзья в Unix-формате или 0 если точная дата неизвестна;
- steamid64 — SteamID проверяемого пользователя;
- sitestatus— указывает принадлежность пользователя к спискам на сайте. Возможные значения:
- 1 — принадлежит к списку гарантов;
- 2 — принадлежит к белому списку;
- 3 — принадлежит к чёрному списку;
- 4 — не принадлежит ни к одному из списков, простой пользователь;
- 5 — находится в чёрном списке аукциона;
- 6 — является сотрудником сайта;
- 7 — премиум-пользователь (донатор);
- 8 — находится в списке ненадёжных;
- customdescr — содержит кастомное описание для проверяемого пользователя если оно указано в базе данных. Поддерживается HTML-код. Поле выводится всегда.
В случае возникновения критической ошибки или отсутствии необходимых прав доступа будет выдан код ответа 403 Forbidden.
Получение информации о токене доступа
Для вывода информации о токене доступа вызовите функцию info. Пример:
http://имя_сайта/api.php?action=info&token={ТОКЕН}
Пример успешного вывода (функция info):
<info> <apiversion><![CDATA[3.0.0.0]]></apiversion> <mcliversion><![CDATA[0.8.1.360]]></mcliversion> <ip><![CDATA[192.168.76.2]]></ip> <expires><![CDATA[1356998400]]></expires> <nickname><![CDATA[KT]]></nickname> </info>
Рассмотрим поля более подробно:
- apiversion — указывает полную версию API;
- mcliversion — указывает минимально допустимую версию оффлайн-чекера, которой разрешено работать с данной версией API;
- ip — разрешённые для данного токена IP-адреса или ANY, если разрешены любые IP;
- expires — срок действия токена доступа (ДО указанной даты). Формат — UnixTime;
- nickname — никнейм (или форумный логин) владельца токена.
Проверка валидности токена доступа
Для проверки вызовите функцию test. Пример:
http://имя_сайта/api.php?action=test&token={ТОКЕН}
Результат успешного тестирования (функция test):
<test> <result><![CDATA[PASSED]]></result> </test>
Получение токена авторизации
Для получения токена авторизации обратитесь к авторам по электронной почте. В своём письме укажите следующие данные:
- что за проект Вы хотите реализовать? Если проектом является сайт, то укажите его домен;
- IP-адрес, с которого будут производиться обращения к нашему API (если IP адрес изменится, то Вы должны написать нам для внесения изменений в политиках доступа);
- другие сведения, которые бы Вы хотели сообщить о своём проекте.
Администрация оставляет за собой право отказать в предоставлении доступа к API, а также блокировать токены доступа без объяснения причин вынесения такого решения.