Sellor Plugin SDK

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

pip install sellor-plugin-sdk

sellor-plugin init thanks-bot      # шаблон плагина
cd thanks-bot
sellor-plugin doctor .             # проверка манифеста и схемы настроек
sellor-plugin pack .               # сборка thanks-bot-1.0.0.slpkg

export SELLOR_SDK_TOKEN=sdk_…      # выдаётся в кабинете разработчика
sellor-plugin publish . --upload

Если PyPI недоступен, SDK 1.0.0 ставится с зеркала: pip install https://sellor.net/sdk/sellor_plugin_sdk-1.0.0-py3-none-any.whl. Исходники — отдельным архивом.

SDK-токен нужен только для загрузки пакета. Он не устанавливает плагин и не даёт доступа к данным продавцов.

Структура плагина

thanks-bot/
├─ sellor.plugin.json   # манифест: права, события, схема настроек, цена
├─ main.py                   # точка входа, объявленная в runner.entrypoint
├─ requirements.txt          # опционально, только чистый Python
└─ README.md

Манифест

{
  "schema": "sellor.plugin/v1",
  "slug": "thanks-bot",
  "name": "Спасибо за покупку",
  "version": "1.0.0",
  "summary": "Пишет покупателю после выполненного заказа.",
  "description": "Полное описание для страницы плагина.",
  "category": "Заказы",
  "accent": "amber",
  "icon": "star",
  "marketplaces": ["FunPay", "Playerok"],
  "permissions": ["orders:read", "chats:send", "logs:write"],
  "events": ["order.completed"],
  "runner": { "mode": "managed", "entrypoint": "main.py", "python": ">=3.11" },
  "settings": [
    { "key": "reply", "label": "Текст ответа", "type": "textarea",
      "default": "Спасибо за отзыв!", "required": true }
  ],
  "support": { "contact": "@your_handle", "refund": "Возврат в течение 14 дней." },
  "pricing": { "model": "subscription", "amountCents": 30000, "periodDays": 30, "trialDays": 3 },
  "sdk": "2026-07-26"
}

• slug — латиница, цифры и дефис. Вместе с витриной образует адрес плагина.
• version — SemVer. Повторно загрузить ту же версию нельзя.
• runner.mode — managed (внутри Sellor Connector) или standalone (свой сервер).
• pricing.model — free, one_time или subscription; минимальная платная цена 10 ₽.
• support.contact обязателен: покупатель должен знать, куда писать.

Схема настроек

Схема из манифеста рендерится дважды: на публичной странице плагина в блоке «Как выглядит в Sellor» и в панели продавца при установке. Значения приходят в рантайм уже приведёнными к типам — валидировать их повторно не нужно.

Права

Права запрашиваются в манифесте и показываются покупателю до установки. Broker API проверяет их на каждом вызове. Доверенные права включаются только после ручного ревью.

События

События появляются, когда Sellor Connector присылает свежий снимок аккаунта. Каждое событие уникально по ключу дедупликации — повторной доставки одного и того же сообщения или заказа не будет. Событие живёт 6 часов.

Событие со статусом «готовится» пока не порождается платформой: коннектор не собирает эти данные. Манифест с таким событием загрузку не пройдёт — плагин просто молчал бы у покупателя.

Python-рантайм

from sellor_sdk import Plugin

plugin = Plugin()


@plugin.on("order.completed")
async def thank_buyer(ctx, event):
    order = event.payload["order"]
    if not order.get("chatId"):
        raise ctx.skip("у заказа нет диалога")
    if await ctx.storage.seen(f"thanked:{order['id']}"):
        raise ctx.skip("уже благодарили за этот заказ")

    await ctx.chat.send(
        account_id=event.account_id,
        chat_id=order["chatId"],
        text=ctx.render(ctx.config["reply"], buyer=order["buyer"]),
    )
    await ctx.log.info(f"поблагодарили за заказ {order['id']}")


if __name__ == "__main__":
    plugin.run()

• ctx.config — значения настроек установки, уже приведённые к типам.
• ctx.storage — get/set/delete, состояние между запусками.
• ctx.secrets.get(key) — секреты установки, требует secrets:read.
• ctx.orders / ctx.lots / ctx.chats / ctx.balance — чтение рабочих данных.
• ctx.skip(reason) — подтвердить событие без действия, чтобы оно не пришло снова.

Broker API

Все запросы идут с заголовком Authorization: Bearer blk_…. Токен привязан к одной установке; продавец может ротировать его в панели в любой момент.

Публикация

1. Откройте витрину разработчика в панели Sellor и выпустите SDK-токен — он показывается один раз.
2. Соберите пакет: sellor-plugin pack .. Контрольная сумма считается по содержимому.
3. Загрузите: sellor-plugin publish . --upload. Версия попадает в очередь ревью.
4. Ревью проверяет права, схему настроек, секреты, разницу пакета и правила поддержки и возврата.
5. После одобрения плагин появляется в публичном каталоге, а обновления уходят покупателям.

Уже опубликованный плагин продолжает работать на прежней версии, пока новая не пройдёт ревью — обновление не может внезапно сломать покупателям автоматизацию.