Как подключить оптового поставщика к боту или магазину по API
Подпись запросов, ключ идемпотентности, вебхуки и проверка игрока: что нужно, чтобы бот продавал без ручной работы.
Если вы продаёте через Telegram-бота, свой сайт или автоматически на маркетплейсе, выдавать коды вручную — тупик. Подключение оптового поставщика по API делает продажу полностью автоматической: покупатель оплатил — товар выдан. Разберём, из чего состоит надёжная интеграция, на примере API PacketUP HUB.
Что умеет API
GET /v1/products— каталог с вашими ценами: каждый номинал отдельной строкой.GET /v1/balance— баланс, чтобы бот не принимал заказы, когда денег не хватает.POST /v1/orders— заказ: код или пополнение по ID игрока.GET /v1/orders/{id}— статус заказа и выданные коды./v1/webhook— адрес, куда платформа присылает события о заказах.
Полное описание — в документации API и спецификации OpenAPI.
Подпись запросов
Каждый запрос подписывается секретом ключа по HMAC-SHA256: в заголовках передаются ключ (X-Api-Key), время (X-Timestamp) и подпись (X-Signature). Секрет не уходит по сети, а перехваченный запрос нельзя повторить позже. В документации есть готовые примеры подписи на curl, Python, Node.js, Go и PHP.
Храните секрет только на сервере: никогда — в коде бота на стороне клиента или в публичном репозитории.
Ключ идемпотентности: защита от двойных заказов
Сеть может оборваться в момент ответа, и бот не узнает, создан ли заказ. Если он просто повторит запрос, покупатель получит два кода, а вы заплатите дважды. Поэтому каждый заказ отправляйте с заголовком Idempotency-Key — например, номером заказа в вашем боте. Повторный запрос с тем же ключом вернёт тот же заказ, а не создаст новый.
Вебхуки вместо постоянных опросов
Пополнения и некоторые коды выдаются не мгновенно. Вместо того чтобы опрашивать статус каждую секунду, укажите адрес вебхука: платформа сама пришлёт событие order.completed, order.partially_completed, order.failed или order.review. Вебхук подписан — проверяйте подпись, прежде чем выдавать товар покупателю.
Проверка игрока
Для пополнений по ID ошибка в ID стоит денег. Перед оформлением просите покупателя подтвердить ID, а для игр с серверами — ещё и сервер или Zone ID. Подробно — в гайде о пополнении по UID.
Чек-лист перед запуском
- Секрет ключа хранится на сервере, права ключа — минимально нужные.
- Каждый заказ уходит с уникальным
Idempotency-Key. - Бот проверяет баланс и цену перед продажей.
- Подпись вебхука проверяется.
- Коды сохраняются у вас — на случай вопросов покупателя.
Доступ к API открывается в кабинете после подключения. Оставьте заявку, чтобы получить ключ.