Подключение к торговой площадке Lootdog

Краткое описание Lootdog.io
Краткое описание взаимодействия
Термины
Привязка аккаунта
Передача предметов на площадку
Передача предметов с площадки партнеру
Отчеты о продажах

Краткое описание Lootdog.io

Это торговая площадка (или просто площадка), позволяющая пользователям торговать между собой вещами из игр. Пользователь может перенести свои игровые предметы на площадку, продать их и вывести деньги или купить другие предметы и использовать их в игре.

Краткое описание взаимодействия

После интеграции с партнером пользователи смогут выставлять предметы из инвентаря партнера на продажу на площадке и передавать их с площадки в инвентарь пользователя партнера.

Для пользователя партнера появляется кнопка "Продать на lootdog.io", после нажатия которой предмет пропадает из инвентаря партнера и появляется в инвентаре пользователя на площадке в его аккаунте. Если пользователь еще не имеет привязанного аккаунта на площадке, то ему нужно сначала авторизоваться (или зарегистрироваться на торговой площадке) и затем подтвердить привязку аккаунта партнера к аккаунту площадки. После привзяки аккаунта создается секретный токен привязки (секрет пользователя), который известен площадке и игре.

Термины

Предмет - конкретный экземпляр игрового предмета, который принадлежит конкретному пользователю. Если у пользователя, например, несколько танков "Т-34", то это несколько предметов.

Продукт - тип предметов. Пользователи продавая предметы одного продукта конкурируют по цене. В предыдущем примере "Т-34" это продукт, несколько экземпляров (предметов) которого находятся в инвентаре у пользователя.

ИД партнера - секретный идентификатор, который выдается партнеру при подключении к площадке. Используется для работы с API площадки.

Секрет партнера - секретный ключ, который выдается партнеру при подключении к площадке. Используется для работы с API площадки.

Секрет пользователя - секретный ключ, который выдается партнеру при привязке пользователя. Используется для передачи предметов в инвентарь пользователя на площадке.

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

Привязка аккаунта

Привязка аккаунта инициируется партнером перед первой передачей предмета на площадку. Опишем ее по шагам:

  1. Партнер создает JWT токен (созданный на основе секрета партнера), который содержит следующие поля:
    • url - Строка. Адрес, на который будет отправлен пользователь после подтверждения привязки
    • nick - Строка. Имя аккаунта у партнера (чтобы пользователь видел какой именно аккаунт он привязывает)
    • user_id - Строка. Идентификатор пользователя в партнерской системе
  2. Затем партнер перенаправляет браузер пользователя на адрес вида "https://lootdog.io/token?partner_id=<ИД_Партнера>&jwt=<Токен>", с токеном, полученным на предыдущем этапе
  3. Пользователь авторизуется (если необходимо) на площадке и подтверждает привязку аккаунта
  4. После подтверждения площадка перенаправляет браузер пользователя на адрес "<url из 1-го шага>?jwt=<Токен>" (если в url есть другие параметры, будет использован "&").
    Токен подписан партнерским секретом и содержит следующие параметры:
    • token - Строка. Секрет пользователя
    • login - Строка. Имя пользователя на площадке
    • user_id - Строка. Идентификатор пользователя на площадке
    • avatar - Строка. Адрес картинки с аватаром на площадке
  5. После этого привязка считается завершенной и для этого пользователя можно использовать API для передачи предметов. Пользователь может отменить привязку, тогда методы API будут возвращать 404.

Передача предметов на площадку

Для передачи предметов используется серверное API по адресу "https://lootdog.io/api/partner".

Для авторизации доступа к API используется базовая HTTP авторизация (ид партнера: секрет партнера) и список разрешенных IP-адресов.

POST /api/partner/create_item

Передача предмета из инвентаря пользователя партнера в инвентарь пользователя на площадке (в теле запроса передается JSON)

  • token - Строка. Секрет пользователя
  • items - Массив объектов. Список предметов к передаче, со следующими параметрами:
    • product_id - Строка. ИД продукта на стороне партнера (может быть много предметов с одним идентификатором продукта)

    • product_title - Строка. Название продукта
    • product_image - Строка. Адрес с картинкой (300х300 пикселей) продукта квадратной (должны быть доступны по  переданной ссылке без пароля)
    • product_desc - Строка. Описание продукта (можно использовать HTML тэги)
    • product_color (не обязательно) - Строка. hex цвета плашки рарности продукта (например, "#FFB042")
    • game_ext_id - Строка. Идентификатор игры на площадке
    • game_title - Строка. Название игры на площадке
    • item_code - Строка. Пин-код предмета
    • stateСтрока (token|open). Является ли код закрытым/открытым кодом, если token то закрытый код, если open то открытый код.

Поля продукта используются для заполнения карточки продукта и это происходит один раз при передаче первого предмета с таким продуктом. Для редактирования уже созданного продукта необходимо обратиться к администрации площадки.

Этот запрос можно повторять несколько раз. Если предмет с таким секретным кодом уже был передан на площадку, то он не задублируется, а будет проигнорирован.

Предполагаемый метод обработки ошибок (например если ответ был не получен или из-за недоступности API площадки) таков: повторять тот же запрос пока в ответ не придет код ответа 200.

Формат запроса

curl -u <parner_id>:<partner_secret> -X POST -H "Content-Type: application/json" \
-d '{"token": "<user_token>", "items": [{"product_id": "1", "product_title": "title product_1", "product_image": "https://lootdog.io/img/icons/user-large@2x.png", "product_desc": "some long description", "game_ext_id": "aw", "item_code": "token_from_operator"}]}' \
https://lootdog.io/api/partner/create_items

Формат ответа:

{}

Передача предметов с площадки партнеру

Для решения этой задачи есть два способа

Открытый пин-код

В этом случае, когда пользователь хочет активировать предмет у партнера, он нажимает на площадке кнопку "Открыть ПИН". После этого пользователь получает item_code (полученный в методе create_items) и может его активировать его у партнера. Для этого в клиенте и на сайте у партнера необходимо реализовать страницу, на которой можно посмотреть что за предмет содержится в коде и возможность перенести его в инвентарь для авторизованного пользователя.

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

В случае открытых пин-кодов пользователи после открытия могут передавать пин-код друг другу и активировать пин-код можно будет на любом аккаунте.

Закрытый пин-код

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

Для этого партнеру необходимо реализовать метод API для активации кодов вида "<адрес api партнера>/token/return" со следующими параметрами:

  • tid - Строка. Идентификатор операции
  • uid - Строка. Идентификатор пользователя у партнера
  • token - Строка. Пин-код, который нужно активировать (добавить в инвентарь)
  • sig - Строка. Подпись запроса (механизм получения подписи описан ниже)

Для получения подписи запроса необходимо подписать алгоритмом HMAC идентификатор транзакции, а в качестве ключа использовать секрет партнера.

Данные для секрета партнера: "partner_secret_1"

{
    "tid": "ld-test-transaction-1",
    "sig": "255b34ea31dc0c364987afd0906fce67",
    "uid": "12345678",
    "token": "oogh0IphahKei3kee7"
}

Пример запроса:

curl -u <parner_id>:<partner_secret> -X POST -H "Content-Type: application/json" \
-d '{"tid": "ld-test-transaction-1", "uid": "12345678", "token": "oogh0IphahKei3kee7", "sig": "255b34ea31dc0c364987afd0906fce67"}' \
https://partnersite.com/token/return

Формат ответа:

Успешно:

{"status":"ok"}

Ошибка:

"status":"error", "message":"Invalid token"

Запрос можно повторять несколько раз, с одинаковым идентификатором транзакции и она должна вернуть тот же результат.

Структура ответа:

  • status - результат выполнения ("ok" или "error")
  • message - уточнение статуса (Например,  "Invalid token")

Любой код ответа, отличный от 200 будет воспринят как внутренняя ошибка сервиса и будет предпринята попытка повторить транзакцию через некоторое время. При возврате 200 и status равным "error" будет означать что код не может быть активирован и пользователь увидит ошибку о невозможности активации

Отчеты о продажах

Партнеру доступно получение отчетов о сделках по его товарам в формате CSV через API.  В запросе используется базовая HTTP авторизация (ид партнера: секрет партнера). 

GET /api/partner/report

Параметры:

  • start_date - дата начала отбора в формате "20180926" 
  • end_date - (необязательно, по умолчанию - сегодня) дата конца отбора в формате "20180926" 
  • with_products - (необязательно, по умолчанию - Ложь). Булево, выполнять ли разбивку по продуктам

Показатели:

  • date - дата
  • product (если выбран) - название и идентификатор продукта, если он выбран в параметрах
  • quantity - количество сделок
  • sum - сумма сделок (с комиссией, по цене покупателя)

Формат запроса:

curl -u <parner_id>:<partner_secret> https://lootdog.io/api/partner/report?start_date=20181001&end_date=20181005

Пример ответа:

date;quantity;sum
20181001;1350;157671.35
20181002;1180;135491.17
20181003;1278;143158.41
20181004;1300;148315.64
20181005;1551;171154.01