SwiftShopchevron_rightAPI update

API V2 UPDATE NOTE

SwiftShop API v2: что изменилось

API v2 — это не косметическое обновление старого DEV API v1, а переработанный production-контракт для каталога, покупок, пополнений, webhooks и управления купленными товарами.

menu_book Документация API bolt Кратко

/api/v2Новый production Base URL

CatalogКатегории, страны и цены из API

OrdersЕдиная модель покупки

WebhooksСобытия заказов и пополнений

link

BASE URL

Новый URL и назначение API

Раньше DEV API был заточен под несколько задач: баланс, наличие российских аккаунтов, покупка категории «Физический | Новый» и получение Telegram-кода. V2 стал backend API магазина.

Было https://swift-shop.xyz/api/v1/*

Специализированный API для ограниченного набора сценариев.

Стало https://swift-shop.xyz/api/v2/*

Production API для каталога, заказов, товаров, пополнений и событий.

Авторизация не изменилась.

Во всех запросах используется Authorization: Bearer <api_key>. Ключ создаётся в Telegram-боте в разделе Информация → API.

travel_explore

ACCOUNTS

Каталог аккаунтов полностью переработан

В v2 клиент получает ассортимент динамически: доступные категории, периоды регистрации, страны, остатки и цены возвращаются самим API.

GET/market/accounts/optionsКатегории, сроки и страны

GET/market/accounts/stockОстатки и цены

POST/market/accounts/buyЕдиная покупка, quantity 1-10

verified_userphysical_new

days_7_14, month_1, month_6, year_1…year_7.

visibilityphysical_shadow

month_1, month_6, year_1…year_7.

passwordCode Requests

Код запрашивается по ID аккаунта: POST /accounts/{account_id}/code-requests.

archiveExports

Одноразовая выгрузка Telegram-сессии: POST /accounts/{account_id}/exports.

shopping_bag

PRODUCTS

Добавлены новые товарные разделы

API больше не построен вокруг одной операции покупки аккаунта. Premium, Stars, Proxy и паки теперь живут в общем контракте и сходятся в Orders.

workspace_premiumTelegram Premium

/market/premium/options, quote по username и покупка по quote_id. Сроки: 90, 180, 360 дней.

starTelegram Stars

Та же quote-логика: проверка получателя, актуальная цена и покупка по quote_id.

languageProxy

socks5_ipv4 и http_ipv4, выдача host, port, username, password и статуса ресурса.

inventory_2Паки

Каталог паков, карточка, лимиты продаж и одноразовая ссылка на Telegram-ресурс после покупки.

receipt_long

ORDERS

Появилась единая система заказов

Любая покупка теперь представляется объектом Order: аккаунт, Premium, Stars, Proxy или пак. Клиенту не нужно делать отдельную модель состояния для каждого товара.

GET/ordersИстория и фильтры

GET/orders/{order_id}Polling состояния

pending

Запрос принят.

processing

Worker выполняет выдачу.

completed

Результат доступен.

failed

Выдача не удалась.

refunded

Средства возвращены.

needs_review

Нужна проверка.

Идемпотентность обязательна для чувствительных операций.

Передавайте Idempotency-Key для покупок, пополнений и выгрузок. Ключ хранится 24 часа и защищает от двойной покупки при timeout или retry.

webhook

WEBHOOKS

Webhooks стали общей системой событий

В v1 webhook в основном обслуживал Telegram-коды. В v2 он покрывает жизненный цикл заказов и пополнений.

Сохранены события кодов

account.code.received, account.code.expired, account.code.failed, webhook.test.

Добавлены события магазина

order.processing, order.completed, order.failed, order.refunded, deposit.completed, deposit.expired.

GETPUTDEL/webhookНастройки

POST/webhook/testТестовая доставка

POST/webhook/rotate-secretНовый секрет

rule

CONTRACT

Ответы API стандартизированы

Успешные ответы используют envelope ok + data + request_id. Ошибки возвращают объект error с машинным кодом, сообщением и деталями.

Error envelope

{
  "ok": false,
  "error": {
    "code": "out_of_stock",
    "message": "Requested item is unavailable",
    "details": {}
  },
  "request_id": "req_..."
}

payments

MoneyДенежные значения возвращаются строками с двумя знаками: "42.50". Валюта явно указана как USDT.

PaginationСписки используют limit, cursor, next_cursor и has_more. Offset не используется.

done_all

SUMMARY

Кратко

DEV API v1 был специализированным API для цепочки «баланс → российские аккаунты → покупка → Telegram-код». API v2 стал единым контрактом для всего ассортимента SwiftShop.

Баланс → RU аккаунты → Покупка → Telegram-код

arrow_forward

Профиль → Пополнения → Каталог → Orders → Webhooks → История

Открыть документацию API Скачать OpenAPI