PlayerokAPI

Лёгкая асинхронная библиотека для работы с API маркетплейса Playerok.

Неофициальная библиотека. Проект не связан с Playerok и не поддерживается площадкой.

Что это

Клиент к Playerok по образцу FunPayAPI: пакет-папка, который можно поставить из PyPI или положить рядом с ботом. Внутри — асинхронный клиент, типизированные модели и слушатель событий. Из зависимостей только httpx и websockets.

Площадка живёт на трёх транспортах, и библиотека использует все:

Где у площадки есть REST — библиотека идёт в REST. Админские и внутренние ручки сознательно не реализованы: только то, чем пользуется обычный клиент.

Установка

pip install PlayerokAPI

Быстрый старт

import asyncio
from PlayerokAPI import Account


async def main() -> None:
    async with Account(token="ваш_token_из_cookie") as acc:
        me = await acc.get_me()
        print(me.username, me.balance.available)

        chats = await acc.chats.search(filter={"unread": True}, first=10)
        for chat in chats:
            print(chat.id, chat.last_message.text if chat.last_message else "")


asyncio.run(main())

Часть API публичная и работает без токена:

async with Account() as acc:
    for item in await acc.items.top(page_size=5):
        print(item.price, item.name)

События

import asyncio
from PlayerokAPI import Account, EventType, MessageEvent


async def main() -> None:
    async with Account(token="...") as acc:
        me = await acc.get_me()
        listener = acc.listener(events=[EventType.NEW_MESSAGE])

        @listener.on(EventType.NEW_MESSAGE)
        async def on_message(event: MessageEvent) -> None:
            message = event.message
            if message.is_system or message.author_id == me.id:
                return
            await acc.send_message(message.chat_id, "Привет!")

        await listener.run()


asyncio.run(main())

Типы событий: NEW_MESSAGE, MESSAGE_EDITED, MESSAGE_DELETED, NEW_CHAT, CHAT_UPDATED, CHAT_READ, NEW_DEAL, DEAL_UPDATED, ITEM_CREATED, ITEM_UPDATED, ITEM_REMOVED, NEW_TRANSACTION, BALANCE_UPDATED.

Падение обработчика логируется и не роняет ни цикл, ни соседние обработчики. Если WebSocket в вашем окружении недоступен, есть поллинг с тем же интерфейсом:

async for event in acc.polling(interval=5.0).events():
    print(event.type)

Разделы API

Пополнение баланса

providers = await acc.payments.providers()
for provider in providers:
    print(provider.id, provider.name, provider.fee, provider.incoming)

url = await acc.payments.create_payment_url(
    1000,
    "SBP",
    payment_method="RUB",
    email="mail@example.com",
)
print(url)  # платёжная страница провайдера

Результат придёт событием NEW_TRANSACTION.

Где взять токен

DevTools → Application → Cookies → https://playerok.com → значение cookie token.

Либо через код на почту:

async with Account() as acc:
    await acc.auth.send_otp("mail@example.com")
    result = await acc.auth.confirm_otp("mail@example.com", "123456")
    print(acc.token)  # при включённой 2FA сначала acc.auth.confirm_second_factor(...)

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

Всё наследуется от PlayerokError:

from PlayerokAPI import HTTPError, PlayerokError, RateLimitError, UnauthorizedError

try:
    await acc.items.get(slug="nope")
except UnauthorizedError:
    ...  # токен протух
except RateLimitError as exc:
    ...  # exc.retry_after
except HTTPError as exc:
    print(exc.status_code, exc.message)
except PlayerokError:
    ...

Сетевые сбои, 429 и 5xx на идемпотентных методах повторяются автоматически. POST после 5xx не повторяется — чтобы не создать вторую покупку.

Документация

Полное руководство и справочник API — playerokapi.readthedocs.io.

Собрать локально:

pip install -e ".[docs]"
sphinx-build -b html docs docs/_build/html

Примеры

• examples/catalog.py — публичный каталог без токена
• examples/profile.py — профиль, баланс, продажи
• examples/autoresponder.py — автоответчик в чатах
• examples/events.py — поток событий, WebSocket и поллинг

Структура пакета

PlayerokAPI/
├── account.py        фасад Account — точка входа
├── types.py          модели данных
├── enums.py          перечисления из схемы
├── exceptions.py     иерархия ошибок
├── common/           конфигурация, эндпоинты, утилиты
├── transport/        HTTP, REST, GraphQL, WebSocket
├── methods/          модули API: auth, viewer, items, chats, deals, …
└── updater/          события, слушатель, поллинг

Разработка

git clone https://github.com/th1ks/PlayerokAPI
cd PlayerokAPI
pip install -e ".[dev]"
ruff check . && mypy PlayerokAPI && pytest

Тесты сетевые запросы не делают — всё на respx.

Ветки: main — релизы, develop — интеграционная, фичи — feat/*, правки — fix/*. Пулл-реквесты идут в develop.

Лицензия

MIT