PersShopPers Shop
← Партнёрская программа

API для партнёров

Базовый адрес https://persshop.com/api/v1. Всё общение — JSON. Суммы в сомони, две цифры после запятой.

Ключ

Ключ выдаётся после одобрения заявки и выглядит как ps_live_abc123.секрет. Он показывается один раз — храните его на сервере, а не в коде бота, который лежит в общем репозитории. Если ключ утёк, напишите в чат: старый отзовём, выдадим новый.

Authorization: Bearer ps_live_abc123.ваш_секрет

Не больше 120 запросов в минуту на ключ. Сверх лимита — 429 с полем retryAfterSeconds.

Ошибки

У любой ошибки есть машинный code и человеческий error. Разбирайте первый: тексты мы можем переписать, коды — нет.

{ "ok": false, "code": "insufficient_balance", "error": "Недостаточно средств на балансе." }

Ручки

GET /api/v1/catalog

Список активных категорий. Параметры: q — поиск по названию, limit, offset. Цен здесь нет — они зависят от позиции, а не от категории.

GET /api/v1/catalog/{id}

Номиналы и поля заказа. У каждой позиции две цены: priceTjs — ваша, retailPriceTjs — наша розница.
{
  "ok": true,
  "category": {
    "id": "free-fire",
    "kind": "topup",
    "title": "Free Fire",
    "fields": [{ "key": "player_id", "label": "ID игрока", "type": "text" }],
    "offers": [
      { "offerId": "110_diamonds", "title": "110 Diamonds",
        "priceTjs": 8.75, "retailPriceTjs": 9.95 }
    ],
    "steamTopup": null
  }
}

GET /api/v1/balance

Сколько денег на счёте и какая у вас доля наценки. Баланс тот же, что в личном кабинете — пополняется переводом на карту на persshop.com.

POST /api/v1/orders

Оформить и сразу выполнить заказ. Обязателен заголовок Idempotency-Key — свой на каждый заказ, от 8 до 128 символов.
POST /api/v1/orders
Authorization: Bearer ps_live_abc123.секрет
Idempotency-Key: 7f0c1e2a-2c1b-4a55-9f10-3e4d5c6b7a80
Content-Type: application/json

{
  "categoryId": "free-fire",
  "offerId": "110_diamonds",
  "fields": { "player_id": "123456789" }
}
Для пополнения Steam вместо offerId шлите сумму:
{ "categoryId": "steam-topup", "amountUsd": 20, "fields": { "login": "steamlogin" } }
В ответ — заказ со статусом. Для подарочных карт и ключей код лежит в delivery.
{
  "ok": true,
  "order": {
    "id": "0f2c…", "number": 128,
    "categoryId": "free-fire", "offerId": "110_diamonds",
    "priceTjs": 8.75, "status": "fulfilled",
    "delivery": null, "error": null
  }
}

GET /api/v1/orders/{id}

Статус заказа. Принимает и UUID, и короткий номер.

Про Idempotency-Key

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

Что важно знать до интеграции