Seller API v1

Старт

За 4 шага можно проверить, что ключ работает:

1. Открой Профиль → Настройки → Безопасность → Seller API
2. Создай ключ. Он начинается с sp_live_ и показывается один раз — сразу сохрани его
3. (По желанию) укажи HTTPS-адрес webhook и включи доставку событий
4. Проверь ключ командой ниже — в ответе должен быть твой профиль

curl -s https://sellpay.fun/api/v1/me \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

Авторизация

Базовый адрес: https://sellpay.fun/api/v1

В каждый запрос добавь заголовок:

Authorization: Bearer sp_live_твой_ключ

Лимит: 60 запросов в минуту на один ключ. Если превысил — ответ 429 и заголовок Retry-After (сколько секунд подождать).

Ошибки

Ответ обычно JSON с полями success: false и error (текст причины).

Чего не делать

• Не вызывай обычные URL сайта вроде /api/orders с cookie браузера — для бота нужен только /api/v1 и ключ.
• Не опрашивай API каждую секунду («поллинг»). Новые заказы и сообщения приходят на webhook.
• PATCH /me/online достаточно раз в несколько минут, не чаще.
• Не клади ключ в публичный GitHub / Discord / скриншоты.
• На webhook отвечай быстро (таймаут ≈ 2.5 с), тяжёлую логику делай после ответа 200.
• Один и тот же eventId обрабатывай один раз (идемпотентность).

Аккаунт

curl -X PATCH https://sellpay.fun/api/v1/me/online \
  -H "Authorization: Bearer sp_live_…" \
  -H "Content-Type: application/json" \
  -d '{"isOnline":true}'

Лоты

Создать и удалить лот можно только на сайте. Через API — список, правка цены/статуса, поднятие и массовые правки.

Поднятие действует на всю игру сразу. Один слот = одна игра (не больше gameSlots). Когда снова можно поднять — смотри canBump и cooldownUntil в bump-status.

Пример тела PUT /lots/auto-bump

{
  "enabled": true,
  "selections": [
    { "game": "Steam" },
    { "game": "Roblox" }
  ]
}

Пример PATCH /lots/:id

{
  "price": 499,
  "status": "active",
  "autoDeliveryContent": "KEY1\nKEY2"
}

{
  "success": true,
  "lot": {
    "id": "lot_1",
    "price": 499,
    "status": "active",
    "autoDeliveryLines": 2
  }
}

Заказы

Параметры GET /orders

Все параметры необязательные. Можно комбинировать. Пример:

curl -s "https://sellpay.fun/api/v1/orders?status=active&limit=20" \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

Статусы заказа

Текст в чат пишешь сам через POST …/messages (поле text). Готовых шаблонов в API нет.

Отзывы

Ответить на отзыв: POST /orders/:id/rating-reply с телом {"reply":"Спасибо!"}.

Чаты

Параметры сообщений (orders и chats)

Баланс

Webhooks

Webhook — это когда SellPay сам стучится на твой сервер при событии (новый заказ, сообщение и т.д.). В настройках укажи URL на https:// и включи доставку.

События: order.paid, order.status, chat.message, webhook.test. Что ответить покупателю — решаешь ты в своём боте.

Заголовки запроса к тебе:

• X-SellPay-Event — тип события
• X-SellPay-Event-Id — уникальный id (не обрабатывай дважды)
• X-SellPay-Delivery-Id — id конкретной доставки
• X-SellPay-Signature — HMAC-SHA256 от сырого body, секрет whsec_…

Ответь 200 за ≈ 2.5 с. Проверка с нашей стороны: POST /api/v1/webhooks/test.

Пример тела order.paid

{
  "event": "order.paid",
  "eventId": "evt_abc123",
  "createdAt": "2026-08-08T12:00:00.000Z",
  "data": {
    "order": {
      "id": "ord_1",
      "orderNumber": 920100,
      "status": "active",
      "chatId": "chat_1",
      "amount": 499,
      "buyerId": "u_2",
      "lot": { "titleRu": "Ключ Steam", "game": "Steam" }
    }
  }
}

Пример тела chat.message

{
  "event": "chat.message",
  "eventId": "evt_…",
  "data": {
    "chatId": "chat_1",
    "fromBuyer": true,
    "peerId": "u_2",
    "openOrderCount": 1,
    "order": {
      "id": "ord_1",
      "orderNumber": 920100,
      "status": "active"
    },
    "message": {
      "id": "msg_1",
      "fromId": "u_2",
      "text": "…",
      "fromBuyer": true
    }
  }
}

Проверка подписи (Node.js)

const sig = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
if (sig !== req.get("x-sellpay-signature")) throw new Error("bad sig");

Проверка подписи (Python)

import hmac, hashlib
sig = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
assert sig == request.headers["X-SellPay-Signature"]

Объекты

Кратко, какие поля чаще всего встречаются в ответах:

order

id, orderNumber, status, lotId, chatId, amount, quantity, buyerId, sellerId, createdAt, paidAt, confirmedAt, lot, buyer

lot

id, game, category, titleRu, price, quantity, status, instantDelivery, autoDeliveryLines, lastBump, images

message

id, chatId, fromId, toId, text, fileUrl, isSystem, isAutoDelivery, fromBuyer, createdAt

Curl builder

Сборка команды curl прямо в браузере. Ключ никуда не отправляется — только подставляется в текст команды у тебя на экране.

curl -s https://sellpay.fun/api/v1/me \
  -H "Authorization: Bearer sp_live_YOUR_KEY"

Changelog

Пока нет изменений.