SwiftShopAPI DOCUMENTATION
v2.0 production OpenAPI Открыть бота
SwiftShopchevron_rightAPI v2
PRODUCTION API DOCUMENTATION

SwiftShop API v2

API для каталога, покупок и управления цифровыми товарами. Здесь собраны примеры запросов, статусы заказов и правила доставки событий.

rocket_launch Быстрый старт description Скачать OpenAPI 3.1
BASE URLhttps://swift-shop.xyz/api/v2
rocket_launch
GETTING STARTED

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

Ключ создаётся в основном боте: Информация → API V2. Ключ используется только на вашем сервере.

1Создайте ключСохраните как секрет
2Запросите каталогНе храните цены локально
3Создайте заказПередайте Idempotency-Key
4Получите результатWebhook или polling
Создание заказа на аккаунт
curl -X POST https://swift-shop.xyz/api/v2/market/accounts/buy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acc-20260825-0001" \
  -d '{
    "category": "physical_new",
    "registration_period": "days_7_14",
    "country": "UA",
    "quantity": 1
  }'
Создание заказа на аккаунт
import uuid
import requests

response = requests.post(
    "https://swift-shop.xyz/api/v2/market/accounts/buy",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "category": "physical_new",
        "registration_period": "days_7_14",
        "country": "UA",
        "quantity": 1,
    },
    timeout=20,
)
response.raise_for_status()
order = response.json()["data"]
Создание заказа на аккаунт
const response = await fetch(
  "https://swift-shop.xyz/api/v2/market/accounts/buy",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      category: "physical_new",
      registration_period: "days_7_14",
      country: "UA",
      quantity: 1,
    }),
  },
);

if (!response.ok) throw new Error(`SwiftShop: ${response.status}`);
const { data: order } = await response.json();
rule
CORE CONTRACT

Правила API

Эти правила действуют одинаково для всех production-маршрутов v2.

keyAuthorization

Bearer <api_key> во всех запросах. Ключ не передаётся в query string.

fingerprintIdempotency

Обязательный Idempotency-Key для покупок, выгрузок и пополнений. TTL — 24 часа.

paymentsMoney

Строка с двумя знаками: "12.50". Валюта всегда возвращается отдельным полем.

scheduleTime

ISO 8601 UTC: 2026-08-25T21:30:00Z. Unix time используется только в подписи webhook.

Pagination

limit от 1 до 100 и opaque cursor. Offset в v2 не используется.

tagIdentifiers

ID являются строками с префиксами: ord_, req_, evt_, dep_.

Успешный envelope

application/json
{
  "ok": true,
  "data": {},
  "meta": { "next_cursor": null, "has_more": false },
  "request_id": "req_01J66CT9Y7MZ3TQ5R8J2H4K6NP"
}
Повтор запроса должен быть безопасным.

Одинаковый ключ и body возвращают первоначальный результат. Одинаковый ключ с другим body возвращает 409 idempotency_conflict.

person
PROFILE

Профиль

Баланс, количество покупок и приобретённых товаров владельца API-ключа.

GET/profileСводка пользователяv2
ПолеТипОписание
idintegerID пользователя SwiftShop
balancemoneyДоступный баланс в USDT
purchasesintegerКоличество завершённых покупок
physical_accountsintegerАккаунты в разделе «Мои аккаунты»
active_proxiesintegerДействующие Proxy
200 OK
{
  "ok": true,
  "data": {
    "id": 123456789,
    "balance": "58.20",
    "purchases": 172,
    "physical_accounts": 31,
    "active_proxies": 4
  },
  "request_id": "req_01J66D1A9Y7V6M2Q0N4X8F3KBP"
}
account_balance_wallet
BILLING

Баланс и пополнения

Баланс, история транзакций и счета Send/xRocket используют общие денежные правила.

GET/balanceБаланс и покупки
GET/transactionsCursor-история операций
GET/deposit-providersДоступные провайдеры
POST/depositsСоздать счёт
GET/deposits/{deposit_id}Статус счёта

Создание счёта

ПолеТипПравило
providerenumsend или xrocket
amountmoneyМинимум "0.10"

В запросе amount — сумма к зачислению. В ответе amount содержит итог к оплате с комиссией провайдера, а credit_amount — сумму, которая поступит на баланс.

201 Created
{
  "ok": true,
  "data": {
    "id": "dep_01J66D...",
    "provider": "send",
    "status": "pending",
    "amount": "10.30",
    "credit_amount": "10.00",
    "currency": "USDT",
    "pay_url": "https://...",
    "expires_at": "2026-08-25T22:15:00Z"
  },
  "request_id": "req_01J66D..."
}
travel_explore
ACCOUNTS · CATALOG

Каталог и наличие аккаунтов

Клиент всегда получает категории, страны и цены из API. Жёстко прошивать ассортимент в интеграции не нужно.

GET/market/accounts/optionsКатегории и страны
GET/market/accounts/stockОстатки и цены
verified_userphysical_new

Физический | Новый: days_7_14, month_1, month_3, month_6, year_1…year_13.

visibilityphysical_shadow

Физический | Тень СЗ: month_1, month_6, year_1…year_13.

historydays_7_14

Доступен только для physical_new.

calendar_monthmonth_1+

Месячные и годовые подразделы возвращаются только при наличии аккаунтов.

GET /market/accounts/stock
{
  "ok": true,
  "data": {
    "items": [{
      "category": "physical_new",
      "registration_period": "days_7_14",
      "country": "UA",
      "country_label": "Украина",
      "quantity": 18,
      "unit_price": "6.40",
      "currency": "USDT"
    }]
  },
  "request_id": "req_01J66E..."
}
shopping_cart_checkout
ACCOUNTS · PURCHASE

Покупка аккаунта

Покупка асинхронная: после резервирования средств API подготавливает сессию, проверяет её и добавляет аккаунт пользователю.

POST/market/accounts/buyСоздать заказ202
ПолеТипПравило
categoryenumphysical_new или physical_shadow
registration_periodenumdays_7_14, month_1, month_3, month_6, year_1…year_13
countrystringISO-код из /options
quantityintegerОт 1 до 10, по умолчанию 1
1pendingСредства зарезервированы
arrow_forward
2processingПодготовка и проверка
arrow_forward
3completedАккаунт привязан
Request
{
  "category": "physical_new",
  "registration_period": "days_7_14",
  "country": "UA",
  "quantity": 1
}
202 Accepted
{
  "ok": true,
  "data": {
    "id": "ord_01J66F...",
    "product_type": "account",
    "status": "processing",
    "amount": "6.40",
    "currency": "USDT",
    "quantity": 1,
    "result": null
  },
  "request_id": "req_01J66F..."
}
Инвариант completed.

Сессия авторизована, телефон подтверждён через Telegram, device/language metadata сохранены, аккаунт принадлежит покупателю. Временный Proxy подготовки снимается в течение 2 часов.

Инвариант failed.

Если товар не выдан, резерв освобождается или создаётся компенсирующий refund. Заказ никогда не остаётся списанным без результата или статуса needs_review.

group
ACCOUNTS · LIBRARY

Мои аккаунты

Поставщико-независимая модель аккаунта. Клиент работает с внутренним account_id, а не с номером телефона в URL.

GET/accountsСписок с cursor pagination
GET/accounts/{account_id}Карточка и профиль устройства
ПолеТипОписание
statusenumready, checking, unavailable
phonestringНормализованный номер в E.164
has_two_fabooleanНаличие пароля 2FA
deviceobjectМодель, ОС, версия приложения и языки
created_atdatetimeВремя добавления в библиотеку
Account resource
{
  "id": "1842",
  "phone": "+380965551355",
  "status": "ready",
  "country": "UA",
  "has_two_fa": true,
  "device": {
    "device_model": "Desktop",
    "system_version": "Windows 11",
    "app_version": "6.1.4 x64",
    "lang_code": "en",
    "system_lang_code": "en-us",
    "lang_pack": "tdesktop"
  },
  "created_at": "2026-08-25T21:40:00Z"
}
password
ACCOUNTS · ACTIONS

Получение кода и выгрузка

Длительные действия представлены отдельными ресурсами. Это убирает зависимость от долгого HTTP-соединения.

POST/accounts/{account_id}/code-requestsЗапрос на 5 минут
GET/code-requests/{request_id}Polling результата
POST/accounts/{account_id}/exportsОдноразовая выгрузка
GET/exports/{export_id}/download?token=...Скачать ZIP один раз
waiting

Аккаунт онлайн и ожидает сообщение.

received

Код доступен через polling и webhook.

expired

TTL 5 минут завершён без кода.

failed

Аккаунт не удалось подготовить.

shield_lock
Выгрузка является секретом.

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

workspace_premium
TELEGRAM PREMIUM

Telegram Premium

Покупка всегда начинается с серверной котировки по username. Доступны только три срока.

GET/market/premium/optionsСроки
POST/market/premium/quotesПроверка получателя и цены
POST/market/premium/buyПокупка по quote_id
90днейpremium_90d
180днейpremium_180d
360днейpremium_360d
POST /market/premium/quotes
{
  "username": "@recipient",
  "days": 180
}
201 Created
{
  "ok": true,
  "data": {
    "id": "quote_01J66H...",
    "username": "recipient",
    "days": 180,
    "price": "24.50",
    "currency": "USDT",
    "expires_at": "2026-08-25T21:55:00Z"
  },
  "request_id": "req_01J66H..."
}
recipient_has_premiumquote_expiredpremium_unavailable
star
TELEGRAM STARS

Telegram Stars

Логика такая же, как у Premium: сначала создайте котировку по username и количеству Stars, затем подтвердите покупку по quote_id.

GET/market/stars/optionsЛимиты и быстрые количества
POST/market/stars/quotesПроверка получателя и цены
POST/market/stars/buyПокупка по quote_id
50Starsminimum
1MStarsmaximum
10минутquote ttl
POST /market/stars/quotes
{
  "username": "@recipient",
  "quantity": 100
}
201 Created
{
  "ok": true,
  "data": {
    "id": "quote_01J66S...",
    "username": "@recipient",
    "quantity": 100,
    "price": "1.80",
    "currency": "USDT",
    "expires_at": "2026-08-25T21:55:00Z"
  },
  "request_id": "req_01J66S..."
}
POST /market/stars/buy
{
  "quote_id": "quote_01J66S..."
}
Completed order result
{
  "username": "@recipient",
  "quantity": 100,
  "delivered_at": "2026-08-25T21:48:00Z"
}
invalid_quantityquote_expiredprovider_wallet_unavailable
language
PROXY API

Proxy

Автоматическая выдача через API поставщика. Выделенные IPv4, общие IPv4 и IPv6 поддерживают HTTP(S) и SOCKS5 одновременно. Страны, сроки и лимиты загружаются из актуального каталога.

GET/market/proxies/optionsКаталог и расчёт стоимости
POST/market/proxies/buyАвтоматическая выдача
GET/proxiesКупленные Proxy
Выделенный IPv4ipv4
Общий IPv4ipv4_shared
Выделенный IPv6ipv6
Количествоquantity: 1..10

GET /market/proxies/options возвращает versions с доступными periods, min_quantity, max_quantity, protocols и currency. Добавьте ?version=ipv4 для списка стран.

Для расчёта итоговой цены: GET /market/proxies/options?version=ipv4&country=RU&days=7&quantity=1. Поле quote.total_price — сумма в USDT с наценкой магазина. При покупке цена проверяется повторно. IPv4: 7, 14, 30, 60, 90 дней; IPv6 также 3 дня. Актуальные значения берите из каталога.

Покупка возвращает 202 и ID заказа. Проверяйте GET /orders/{order_id} или ожидайте webhook. Данные прокси появятся в result.items и GET /proxies. Передавайте Idempotency-Key при покупке. Старые protocol: socks5_ipv4/http_ipv4 принимаются как version: ipv4; прежний лимит 20 заменён лимитом поставщика.

При подтверждённом отказе поставщика средства возвращаются. Таймаут или неопределённый ответ переводит заказ в needs_review; автоматической повторной покупки нет. При частичной выдаче заказ завершается с выданными прокси и возвратом за недостающие; result содержит requested_count, delivered_count, refunded_amount.

Request
{
  "version": "ipv4",
  "country": "DE",
  "quantity": 2,
  "days": 30
}
Order result
{
  "items": [{
    "id": "prx_01J66J...",
    "protocol": "socks5",
    "version": "ipv4",
    "protocols": ["http", "https", "socks5"],
    "country": "DE",
    "host": "203.0.113.10",
    "port": 1080,
    "username": "swift_user",
    "password": "secret",
    "url": "socks5://swift_user:secret@203.0.113.10:1080",
    "status": "active",
    "expires_at": "2026-09-24T22:00:00Z"
  }]
}
inventory_2
PACKS

Паки

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

GET/market/packsКаталог по разделам
GET/market/packs/{pack_id}Карточка
POST/market/packs/{pack_id}/buyПокупка и invite link
PRIVATprivat

Ограниченный раздел.

sales_limit: 5
NEWnew

Недавно добавленные паки.

sales_limit: 5
OLDold

Паки без лимита продаж.

sales_limit: null
NFT / TRADEnft_trade

Материалы для NFT и Trade.

sales_limit: null
Completed order result
{
  "pack_id": 42,
  "title": "Example pack",
  "section": "new",
  "access_url": "https://t.me/+single_use_invite",
  "member_limit": 1
}
link
Выдача фиксируется атомарно.

Списание, увеличение счётчика продаж и создание invite link выполняются как одна бизнес-операция. Повтор по тому же Idempotency-Key возвращает исходную ссылку.

receipt_long
UNIFIED ORDERS

Единая модель заказов

Все товары возвращают одинаковую оболочку заказа. Различается только объект result.

GET/ordersИстория и фильтры
GET/orders/{order_id}Polling состояния
pending

Запрос принят, средства резервируются.

processing

Провайдер или worker выполняет выдачу.

completed

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

failed

Выдача завершилась ошибкой.

refunded

Средства полностью возвращены.

needs_review

Нужна ручная проверка без повторного списания.

pendingarrow_forwardprocessingarrow_forwardcompleted или failedarrow_forwardrefunded
lock_clock
Терминальные статусы неизменяемы.

completed и refunded не могут вернуться в processing. Исправления оформляются отдельной компенсирующей транзакцией с audit trail.

webhook
EVENT DELIVERY

Webhooks

Webhook — основной способ получения результата. Polling остаётся доступным и использует те же ресурсы.

GETPUTDEL/webhookНастройки
POST/webhook/testТестовая доставка
POST/webhook/rotate-secretНовый секрет
security
Webhook URL проходит SSRF-проверку.

Разрешён только публичный HTTPS endpoint. localhost, credentials в URL, private/link-local адреса и redirect запрещены; DNS проверяется при сохранении и перед доставкой.

События

order.processingЗаказ перешёл в обработку
order.completedТовар выдан
order.failedВыдача завершилась ошибкой
order.refundedСредства возвращены
account.code.receivedПолучен Telegram-код
account.code.expiredЗапрос кода истёк
account.code.failedПодготовка аккаунта не удалась
deposit.completedПополнение зачислено
Headers
Content-Type: application/json
User-Agent: SwiftShop-Webhook/2.0
X-Swift-Event-ID: evt_01J66K...
X-Swift-Event: order.completed
X-Swift-Timestamp: 1787695200
X-Swift-Signature: v1=<hex_hmac_sha256>
Signature material
signed_payload = timestamp + "." + raw_body
signature = HMAC_SHA256(secret, signed_payload)

# Требования получателя:
# 1. Окно timestamp ≤ 5 минут
# 2. Constant-time compare
# 3. Дедупликация по event_id
# 4. HTTP 2xx после фиксации

Retry schedule

30 сек2 мин10 мин30 мин2 ч6 ч24 ч

Повторы выполняются при timeout, network error, 408, 409, 425, 429 и 5xx. Ответ 410 Gone отключает webhook. Redirect не используется.

Event envelope
{
  "event_id": "evt_01J66K...",
  "event": "order.completed",
  "api_version": "2.0",
  "created_at": "2026-08-25T22:00:00Z",
  "data": {
    "order": {
      "id": "ord_01J66F...",
      "product_type": "account",
      "status": "completed",
      "amount": "4.20",
      "currency": "USDT"
    }
  }
}
error
ERROR MODEL

Ошибки

Код ошибки предназначен для логики клиента, message — для журналов и отладки. Клиент не должен парсить текст message.

Error envelope
{
  "ok": false,
  "error": {
    "code": "out_of_stock",
    "message": "Товар по выбранным параметрам закончился",
    "details": { "country": "UA" }
  },
  "request_id": "req_01J66M..."
}
HTTPКодКогда возвращается
400invalid_jsonJSON не читается или тело не является объектом
401unauthorizedКлюч отсутствует, отозван или неверен
402insufficient_balanceНедостаточно доступного баланса
404*_not_foundРесурс не найден или не принадлежит ключу
409not_availableТовар закончился после получения каталога
409idempotency_conflictКлюч уже использован с другим body
409quote_expiredСрок котировки истёк
409request_in_progressОперация с этим Idempotency-Key ещё выполняется
422invalid_*Поле не прошло проверку формата или диапазона
429rate_limitedПревышен лимит запросов
503provider_unavailableВнешняя выдача временно недоступна
speed
TRAFFIC POLICY

Rate limits

Лимиты действуют для сочетания API-ключа и IP-адреса, отдельно для каждого маршрута. Ответы содержат состояние текущего окна.

ГруппаЛимитМаршруты
Чтение120 / минПрофиль, списки, заказы и polling
Каталог аккаунтов60 / минOptions и актуальные остатки
Покупки20 / минАккаунты, Premium, Stars, Proxy и паки
Коды60 / минСоздание code-request
Выгрузки20 / минПодготовка архивов сессии
Пополнения20 / минСоздание счетов
Webhook test5 / 5 минТест и ротация секрета
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-After