README

Если вам зачем-то нужна предыдущая версия нашего API, то она описана здесь. Но использовать её мы не рекомендуем, лучше используйте последнюю. Соответственно, код API-клиента из данного репозитория тоже использовать смысла нет, т.к. он для старогй версии API.

Extrareality API v2

С каждым запросом мы отправляем параметр:

datetime (например "2019-05-01 12:00:00")
signature

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

Подпись (signature) формируется следующим образом:

md5($datetime . $secret)

Используемые параметры:

datetime - в формате "Y-m-d H:i:s" (т.е. yyyy-mm-dd hh:mm:ss)
secret - наш общий маленький секрет ;)

Быстрые ссылки к описанию методов

Вы должны предоставить нам 2 URL на вашем сайте, по которому реализован наш API, и на которые мы будет слать запросы:

Бронирование
Расписание

Расписание

Метод: GET

Вы выдаете список всех ваших слотов примерно на месяц вперед, но добавляете в каждый из них поле "extraPrices", которое содержит массив. В нём: ключ - условие, значение - цена.

Каждый слот - это объект, содержащий следующие свойства:

date (Y-m-d)
time (H:i)
is_free - (boolean) true означает доступность для бронирования. Если время игры прошло или слот уже забронирован, то необходимо возвращать false.
extraPrices (массив цен, в котором ключ - это условие, значение - цена).

Также вы можете передавать нам дополнительные параметры, которые мы вернем вам при бронировании (в примере our_time_id).

Пример:

[
   {
       "date": "2016-05-05",
       "time": "18:30",
       "is_free": true,
       "extraPrices": {
           "2 человека": 80,
           "Больше 2 человек": 110
       },
       "our_time_id": 321
   },
   {
       "date": "2016-05-05",
       "time": "20:00",
       "is_free": false,
       "extraPrices": {
           "2 человека": 70,
           "Больше 2 человек": 100
       },
       "our_time_id": 322
   },
]

Бронирование

Метод: POST

На указанный вами URL будут приходить следующие поля:

comment - комментарий от клиента (если есть)
datetime - дата и время игры в формате "Y-m-d H:i:s"
email - может содержать null, так что учитывайте это при в ставке в вашу БД
name - имя клиента
phone - телефон клиента
players_num - количество игроков
price - цена игры
signature - описано в начале документа
source - от нас всегда "extrareality"
uid: уникальный ID брони на нашем сайте

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

В случае успешной обработки запроса вам необходимо вернуть ответ в json:

{"success": true}

В случае неудачи вернуть:

{"success":false, "message": "error message"}

Здесь в поле message текст с причиной ошибки.

Пример:

Запрос

POST https://superquestsite.com/api/quest2/book

name=Иван
    &comment=Комментарий
    &datetime=2019-05-01 20:00:00
    &email=test@tut.by
    &our_time_id=124
    &phone=375291234567
    &price=120,
    &signature=5a4fic756e8...6dd04bc9174,
    &source=extrareality
    &uid=854

Ответ

{"success": true}

или

{"success": false, "message": "Ваше имя не Джеймс Бонд" }

Получить список отзывов

В предыдущих методах запрос исходил от нас, а в этом случае GET-запрос отправляете уже вы. Рекомендуется отправлять его не чаще раза в 30 минут.

Адрес для запроса будет такой: https://extrareality.by/api2/reviews?quest_id=...

Получаются последние отзывы (сортировка по убыванию).

Прочие возможные параметры (помимо quest_id):

newer_than_id - если указан, то отзывы берутся не все подряд, а начиная с этого id отзыва (т.е. при получении списка, можно максимальный id сохранять, а на следующий день получать начиная с него)
quantity - количество отзывов для получения, максимум 100 (если меньше 1, то возьмется 50)
rating_threshold - не ниже какой средней оценки выбирать отзывы (7.5, 8 и т.д.)

Ответ:

Content-Type: application/json

[
    {
        "id": 9,
        "datetime": "2019-07-03 10:00:00",
        "name": "Иннокентий",
        "text": "Квест супер! Свободу попугаям!",
        "rating": 9.4
    },
    {...},
    {...}
]

Получить рейтинг квеста

Отправляете GET-запрос на следующий адрес:

https://extrareality.by/api2/rating?quest_id=...

или если вам нужен результат в JSON:

https://extrareality.by/api2/rating?quest_id=...&json=1

Во втором случае ответ будет примерно следующим:

Content-Type: application/json

{
    "questId": 9,
    "rating": 9.87
}

extrareality / api-helper

Maintainers

Details