Автозакупка через API: ключ, лимиты, возврат

Публичный API покрывает то же, что вы делаете руками: каталог, остатки, баланс и заказы. Отдельного поддомена вида api.boomly.ac нет — база относительная, запросы идут на /api того же домена. Документация с описанием эндпоинтов лежит на сайте в разделе API, там же работает плейграунд.

Плейграунд устроен так же честно, как конвертер форматов: запрос уходит прямо из вашего браузера, ключ на сервере магазина не сохраняется. Это позволяет проверить обращение до того, как вы начнёте писать код.

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

Пользы от него больше, чем кажется. Форму ответа удобнее один раз увидеть глазами, чем восстанавливать по документации: разбор пишется под реальную структуру, а не под её описание, и отладка начинается с рабочего запроса, а не с догадки.

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

• Ключ выпускается в кабинете и там же отзывается.
• Секрет нужен только для подписи; если подпись у ключа не включена, он в запросе не участвует.
• Плейграунд на сайте позволяет отправить запрос с ключом, не сохраняя его на сервере.

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

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

У позиции в ответе каталога два номера, и путать их дорого. Артикул — публичный номер товара: он же стоит в карточке на сайте, его называют поддержке и по нему повторяют закупку. Внутренний идентификатор — служебный номер записи в базе.

Адрес карточки на сайте строится по артикулу. Если скрипт собирает ссылки на позиции — чтобы приложить к обращению или сохранить у себя, — собирать их нужно из артикула. Внутренний номер приведёт на ту же страницу, но уже переадресацией, и в вашей базе останется лишним звеном.

• Артикул — то, что вы называете поддержке вместе с номером заказа.
• Артикул постоянен: по нему подписываются на пополнение позиции в боте магазина.
• Внутренний номер в разговоре с поддержкой бесполезен — это идентификатор записи, а не товара.

Артикул виден и без API: он стоит в карточке позиции и в заказе, и именно его просит поддержка. Таблица закупок, собранная по артикулам, одинаково читается и скриптом, и человеком, который потом пишет в бот.

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

Ограничений два, и они считаются независимо: 120 запросов в минуту на одну ручку и 60 запросов в минуту на ключ. Второй лимит строже первого, и именно он определяет фактический потолок: сколько бы разных эндпоинтов вы ни опрашивали, суммарно с одного ключа проходит шестьдесят запросов в минуту.

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

• 120 запросов в минуту — на один адрес.
• 60 запросов в минуту — на один ключ, и это фактический потолок сценария.
• Лимиты считаются независимо, поэтому ограничивает всегда меньший из двух.

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

Это главное отличие API от остальных способов покупки, и его стоит знать до того, как выбирать канал закупки. Заказы, оплаченные через API с баланса, при неудачной выдаче возвращаются на баланс автоматически. На сайте и в боте такого автовозврата нет: там средства просто не списываются, а при сбое возврат делается через поддержку вручную.

Для разовой покупки разница невелика. Для регулярной автозакупки она принципиальна: сценарий, где скрипт заказывает партии без человека, обязан уметь пережить неудачную выдачу без ручного разбора — и только API это обеспечивает.

• Автовозврат срабатывает при оплате с баланса по API, а не при любой оплате.
• Баланс списывается сразу, поэтому выдача идёт без ожидания подтверждения перевода.
• Пополнить баланс можно теми же способами, что и оплатить заказ: USDT в семи сетях, CryptoBot или рубли по СБП.

Разница между каналами сводится к одному вопросу: кто разбирает сбой. При покупке по API его разбирает сам магазин и возвращает деньги на баланс, на сайте и в боте — поддержка вручную. Для потока заказов это разница между работающим ночью скриптом и утренним разбором.

Приёмка в скрипте выглядит иначе, чем руками, но правило то же: сразу после ответа сверить число выданных строк с заказанным объёмом, а состав полей — с меткой комплекта позиции. Тридцать минут идут одинаково, кто бы ни оформлял заказ.

Автовозврат при этом не заменяет приёмку. Он закрывает случай, когда выдача не состоялась вовсе, а не случай, когда позиция пришла и не соответствует описанию. Второе по-прежнему решается в тридцатиминутном окне и через поддержку — с номером заказа и артикулом.