paper-scroll

vrts paperscroll
Help

Apiary Powered Documentation

Sign in with Apiary account.

paper-scroll

Introduction

Здесь представлен список доступных секций и методов API игры Paper Scroll.

Любые вопросы о работе API вы можете задать в нашем сообществе для разработчиков ВКонтакте или специальной беседе.

Для отправки запросов вам необходимо создать магазин внутри приложения и получить к нему ключ доступа по ссылке vk.com/app7420483#create_merchant

SDK

Информацию о готовых SDK можно найти по ссылкам:
Node.JS: github.com/KotRikD/paper-scroll-sdk-node
Python: github.com/KotRikD/paper-scroll-sdk-py
PHP: github.com/nikitos42050/paper-scroll-sdk-php

Генерация ссылок

Приложение поддерживает быстрые ссылки, открывающие окно перевода вашему магазину.

Ссылка состоит из нескольких параметров: vk.com/app7420483#m{merchant_id}_{amount}_{payload}_{is_locked}

  • merchant_id: Идентификатор вашего магазина

  • amount: Предлагаемая сумма перевода в тыс. долях рулонов

  • payload: Полезная нагрузка в переводе

  • is_locked: Флаг, запрещающий редактирование предложенной суммы

Пример такой ссылки: vk.com/app7420483#m1_1000000_50_0
Или самый короткий вариант: vk.com/app7420483#m1

Получение уведомлений

С помощью метода webhooks.create вы можете настроить отправку уведомлений о событиях в игре на собственный сервер. Данные отправляются методом POST в формате application/json.

На данный момент поддерживаются события: transfer_new.

Пример отправляемого события:

{
    "event": "transfer_new",
    "object": {
        "transfer_id": 37356,
        "external_id": 37357,
        "owner_id": -1,
        "peer_id": 100772411,
        "is_initiator": false,
        "payload": 100,
        "type": "transfer",
        "object_type": "balance",
        "object_type_id": 0,
        "message": "",
        "amount": 1000,
        "create_date": 1590134400
    },
    "secret": "yQ7Z1LDDG83Q8r8Ym9Yu2aXzBc51T06Q"
}

Событие считается успешно отправленным, если ответ сервера содержит HTTP код 200 OK.

Отправка запросов

Данные запросов и ответов передаются в формате JSON в кодировке UTF-8.
Базовый адрес для отправки запросов: https://paper-scroll.ru/api/{method}

К каждому отправляемому запросу необходимо добавлять заголовок Authorization с типом Basic и base64-закодированной строкой merchant_id:access_token (не пропустите двоеточие между двумя строками).

Например: Authorization: Basic MjozNTJlYTIyMTZlZDEzYmZhMDlhNTk0ZQ==

Лимиты

С использованием одного ключа доступа можно отправить не больше 3 запросов в секунду.

Также для каждого IP адреса имеется лимит на 10 запросов в секунду.

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

Ошибки API всегда возвращаются с HTTP кодом 400 Bad Request и имеют общий формат:

{
    "error": {
        "error_code": 1,
        "error_msg": "Internal error",
        "error_text": "Внутренняя ошибка сервиса, повторите запрос позже"
    }
}

Основной список ошибок, возвращаемых для всех методов:

  • #1 - Internal error (Внутренняя ошибка сервиса)

  • #2 - Authorize error (Неверно передан ключ доступа)

  • #3 - Access error (Ошибка доступа к секции/методу)

  • #4 - Flood limit (Превышен лимит на частоту обращений)

  • #5 - Unknown method (Не определена секция/метод API)

  • #6 - Invalid params
    (Неверно переданы параметры к запросу.
    Возвращается, если для метода не опредлены собственные типы ошибок.)

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

Reference

Merchants

/merchants.get

Возвращает информацию о магазинах по их идентификаторам

Request
object
  • merchant_ids

    ID магазинов, не больше 100 элементов.
    По умолчанию — идентификатор текущего магазина.

    array, optional[number]
Response
object
  • response

    Список запрошенных магазинов

    array

/merchants.edit

Редактирует информацию о текущем магазине

Request
object
  • name

    Новое название магазина

    string, optional
  • group_id

    ID сообщества ВКонтакте, к которому будет привязан магазин

    number, optional
  • avatar

    Ссылка на новое изображение магазина.
    Должно быть загружено на сервер ВКонтакте и иметь адрес формата https://**.userapi.com/******.jpg?size...

    string, optional
Response
object
  • response

    Результат выполнения запроса

    boolean
    true

Users

/users.get

Возвращает информацию о пользователях по их идентификаторам

Request
object
  • user_ids

    ID пользователей, не больше 100 элементов.
    Если профиль пользователя ещё не был создан в приложении, то объекта с его данными в ответе не будет.

    array, required[number]
Response
object
  • response

    Список запрошенных профилей пользователей

    array

/users.getBalances

Возвращает информацию о балансах пользователей по их идентификаторам

Request
object
  • user_ids

    ID пользователей, не больше 250 элементов

    array, required[number]
Response
object
  • response

    Список запрошенных балансов пользователей.
    Если профиль пользователя ещё не был создан в приложении, то объекта с его данными в ответе не будет.

    array

Transfers

/transfers.create

Запускает выполнение нового перевода

Request
object
  • peer_id

    ID получателя перевода

    number, required
  • object_type

    Тип переводимых предметов

    enum, required
  • object_type_id

    При object_type = disinfectants или items содержит ID предмета
    При object_type = balance всегда имеет значение 0

    number, optional
  • message

    Комментарий к переводу

    string, optional
  • amount

    Переводимая сумма в тыс. долях при object_type = balance
    В остальных случаях - количество переводимых предметов

    number, required
Response
object
  • response

    Объект созданного перевода

    object

/transfers.get

Возвращает список переводов по их идентификаторам

Request
object
  • transfer_ids

    ID переводов, не больше 100 элементов.
    Если перевод не пренадлежит текущему пользователю или ещё не создан, то объекта с его данными в ответе не будет.

    array, required[number]
Response
object
  • response

    Список запрошенных переводов

    array

/transfers.getHistory

Возвращает список последних переводов

Request
object
  • offset

    Смещение относительно первого найденного перевода

    number, optional
    0
  • limit

    Количество возвращаемых переводов, не больше 250 элементов

    number, optional
    100
Response
object
  • response

    Список запрошенных переводов

    array

Storage

/storage.getDisinfectants

Возвращает информацию об имеющихся средствах защиты в инвентаре

Response
object
  • response

    Список средств защиты

    array

/storage.getItems

Возвращает информацию об имеющихся предметах в инвентаре

Response
object
  • response

    Список предметов

    array

Webhooks

/webhooks.get

Возвращает информацию о текущем установленном сервере или ошибку при его отсутствии

Response
object
  • response

    Объект сервера

    object

/webhooks.create

Настраивает Webhook для отправки уведомлений о событиях

Request
object
  • url

    URL для отправки уведомлений

    string, required
  • events

    Типы отправляемых событий на сервер

    array, required[string]
Response
object
  • response

    Объект созданного сервера

    object

/webhooks.delete

Удялает текущий используемый сервер

Response
object
  • response

    Результат выполнения запроса

    boolean
    true

/webhooks.getLogs

Возвращает информацию о последних 20 ошибках при отправке событий

Response
object
  • response

    Результат выполнения запроса

    array[string]

Data Structures

Merchant
object
  • merchant_id

    ID магазина

    number, required
    1
  • owner_id

    ID владельца магазина

    number, required
    595626484
  • group_id

    ID сообщества ВКонтакте, к которому привязан магазин

    number, required
    194441652
  • name

    Название магазина

    string, required
    Мой магазин
  • avatar

    Изображение магазина

    string, required
    https://sun1-85.userapi.com/impg/HPw6qemyal_zaoxYkAtpGpjY13SZGJwMJ_JHnw/MhJs9KUPE6c.jpg
  • balance

    Баланс магазина в тыс. долях рулонов

    number, required
    250000
  • create_date

    Дата создания магазина

    number, required
    1590134400
User
object
  • user_id

    ID пользователя

    number, required
    595626484
  • first_name

    Имя пользователя

    string, required
    Pi
  • last_name

    Фамилия пользователя

    string, required
    Emerollo
  • avatar

    URL квадратной фотографии пользователя размером 50x50 или 100x100 пикселей

    string, required
    https://**.userapi.com/******.jpg?size...
  • avatar_max

    URL квадратной фотографии пользователя размером 200x200 или 400x400 пикселей

    string, required
    https://**.userapi.com/******.jpg?size...
  • balance

    Баланс пользователя в тыс. долях рулонов

    number, required
    100000
  • improvements_sum

    Сумма улучшений в тыс. долях рулонов

    number, required
    1000
  • bonuses_sum

    Сумма бонусов в тыс. долях

    number, required
    250
UserBalance
object
  • user_id

    ID пользователя

    number, required
    595626484
  • balance

    Баланс пользователя в тыс. долях рулонов

    number, required
    100000
Transfer
object
  • transfer_id

    ID перевода

    number, required
    37356
  • external_id

    ID перевода для получателя

    number, required
    37357
  • owner_id

    ID инициатора перевода

    number, required
    595626484
  • peer_id

    ID получателя перевода

    number, required
    100772411
  • is_initiator

    Является ли текущий пользователь инициатором

    boolean, required
    true
  • payload

    Полезная нагрузка при переводе от пользователя магазину

    number, required
    0
  • type

    Тип перевода

    enum, required
  • object_type

    Тип переводимых предметов

    enum, required
  • object_type_id

    При object_type = disinfectants или items содержит ID предмета
    При object_type = balance всегда имеет значение 0

    number, required
    0
  • message

    Комментарий к переводу

    string, required
    0
  • amount

    Переводимая сумма в тыс. долях при object_type = balance
    В остальных случаях - количество переводимых предметов

    number, required
    1000
  • create_date

    Дата отправки перевода

    number, required
    1590134400
Disinfectant
object
  • type_id

    ID типа средства защиты

    number, required
    1
  • name

    Название средства защиты

    string, required
    Маска
  • protection

    Тип защиты (infection или steal)

    string, required
    infection
  • cost

    Стоимость предмета в тыс. долях рулонов

    number, required
    1000000
  • life_time

    Время действия средства защиты в секундах

    number, required
    14400
  • chance_reduction

    Количество снижаемых процентов для вероятности возникновения события

    number, required
    30
  • current_count

    Текущее количество средств защиты в инвентаре

    number, required
    2
Item
object
  • type_id

    ID типа предмета

    number, required
    1
  • name

    Название предмета

    string, required
    Тест на вирус
  • description

    Описание предмета

    string, required
    Позволяет точно узнать свой статус заболевания
  • cost

    Стоимость предмета в тыс. долях рулонов

    number, required
    5000000
  • current_count

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

    number, required
    3
Webhook
object
  • webhook_id

    ID сервера

    number, required
    1
  • merchant_id

    ID магазина, которым используется сервер

    number, required
    1
  • events

    Типы отправляемых событий на сервер

    array, required[string]
  • secret

    Секретный ключ, отправляемый вместе с запросами

    string, required
    yQ7Z1LDDG83Q8r8Ym9Yu2aXzBc51T06Q
  • create_date

    Дата создания сервера

    number, required
    1590134400
Error
object
  • error_code

    Код ошибки

    string, required
    1
  • error_msg

    Название типа ошибки

    string, required
    Example error
  • error_text

    Подробное описание проблемы

    string, required
    Error message example