От каталога
до выдачи товара.

1. Создайте личный ключ

   В боте откройте «Профиль → API ключ → Создать мой API ключ».

2. Подготовьте окружение

   Сохраните ключ на своём сервере в API_KEY. В BASE_URL укажите адрес этого сайта без завершающего слеша.

3. Проверьте баланс

   Выполните запрос ниже или подключитесь на странице API тест. Просмотр баланса и каталога бесплатный.

curl "$BASE_URL/api/v1/me?currency=RUB" \
  -H "Authorization: Bearer $API_KEY"

Передавайте ключ в заголовке каждого запроса. Он даёт доступ только к балансу и заказам своего владельца.

Authorization: Bearer YOUR_API_KEY

Также поддерживается заголовок X-API-Key. Ключи в адресной строке не принимаются.

Ответ содержит Telegram ID, логин, баланс и лимит запросов. Баланс общий с ботом; пополнить его можно в профиле.

{
  "id": 42,
  "name": "Example product",
  "price_kopeks": 19900,
  "price": "199.00",
  "currency": "RUB",
  "stock": 12,
  "stock_unlimited": false,
  "available": true,
  "category": {
    "id": 3,
    "name": "Subscriptions"
  },
  "wholesale_tiers": [
    {
      "min_quantity": 5,
      "unit_price_kopeks": 17900,
      "unit_price": "179.00",
      "currency": "RUB"
    }
  ]
}

Периодически обновляйте каталог с учётом лимита запросов — изменения не отправляются автоматически. Для stock_unlimited=true остаток равен null, товар не заканчивается. Услуги с дополнительными параметрами оформляются в боте.

Добавьте currency=RUB или currency=USD к запросам баланса, каталога, заказов и операций. По умолчанию — RUB. Язык и валюта выбираются независимо; отдельный долларовый счёт не создаётся.

{
  "currency": "USD",
  "settlement_currency": "RUB",
  "exchange_rate": {
    "base": "USD",
    "quote": "RUB",
    "rate": "80",
    "updated_at": "2026-09-20T12:00:00.000Z"
  },
  "items": [
    {
      "id": 42,
      "price_kopeks": 19900,
      "price": "2.49",
      "currency": "USD"
    }
  ]
}

Цену определяет сервер. max_total_kopeks ограничивает расходы, но не задаёт стоимость. Поля price, currency и exchange_rate в теле заказа не принимаются. Валюта ответа не меняет списание.

История в USD использует курс текущего ответа. Для снимка на момент запроса сохраните ответ вместе с курсом. Если курс недоступен, USD-запрос вернёт 503 exchange_rate_unavailable до создания заказа; повторите его в RUB с тем же ключом операции.

В ответе приходит выбранная через lang языковая версия в двух форматах — без внутренних команд магазина.

{
  "description": "Product description\nGuide (https://example.com/guide)",
  "description_html": "<strong>Product description</strong><br><a href=\"https://example.com/guide\" rel=\"noopener noreferrer\">Guide</a>"
}

Данные выдачи delivery_data передаются без преобразований. Сохраняйте их целиком, включая переносы строк.

Один запрос создаёт заказ на один товар в количестве от 1 до 100. Это платная операция с баланса владельца ключа. Сохраните ключ операции и параметры до отправки.

curl -X POST "$BASE_URL/api/v1/orders?currency=RUB" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: store-order-1042" \
  -d '{
    "product_id": 42,
    "quantity": 1,
    "max_total_kopeks": 19900,
    "client_order_id": "1042"
  }'

Выдавайте данные покупателю только при status=delivered. Поле data.delivery_data содержит полный результат: текст, несколько строк или JSON в виде строки.

Тестовый товар доступен всем API-клиентам. Найдите is_test=true в каталоге и используйте полученный id. Наличие неограниченно: stock=null, stock_unlimited=true, available=true; api_only=true.

1. Отправьте обычный POST /orders с ID тестового товара, quantity=1 и max_total_kopeks=100.
2. Дождитесь delivered и сохраните delivery_data. При повторе используйте прежний Idempotency-Key.

На сайте готовый сценарий: подтверждение суммы, проверка результата, копирование и скачивание выдачи. API ключ остаётся в памяти вкладки; для восстановления сохраняется только идентификатор операции.

Если ответ не пришёл, повторите исходный POST с тем же Idempotency-Key и параметрами. Новый ключ создаёт новую покупку; изменение параметров прежнего ключа вернёт 409 idempotency_conflict. Выбор другой валюты ответа не создаёт новый заказ.

Если ID уже известен, проверяйте этот заказ через GET не чаще одного раза в 5 секунд.

API-заказы владельца ключа. Фильтр client_order_id находит заказ по вашей метке. Список не содержит выдачу — запросите заказ по ID.

Все операции по вашему балансу. amount_kopeks со знаком: плюс — зачисление, минус — списание или резерв. Тип purchase_hold меняется на purchase после выдачи; purchase_refund — возврат.

В обоих списках limit — от 1 до 100. Поле has_more показывает, есть ли следующая страница. Для валюты используйте currency=RUB или currency=USD.

{
  "ok": false,
  "error": {
    "code": "insufficient_balance",
    "message": "Your available balance is too low."
  }
}

Обрабатывайте error.code, а не текст message. Ответ с ошибкой покупки может содержать data с заказом. При сетевой ошибке или 5xx сохраняйте прежний ключ операции.