Интеграция Reseller API: от ключа до первого заказа

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

Ключ и база

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

API=https://hexpay.live/api/reseller
curl -H "Authorization: Bearer $KEY" $API/balance

Лимит около шестидесяти запросов в минуту. На превышении приходит 429 с заголовком Retry-After, его значение и надо ждать, а не повторять запрос немедленно.

Каталог

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

Товары различаются и по тому, как считается количество. У звёзд это число звёзд от 50 до 1 000 000, у пополнения Steam это сумма в рублях, у подписок количество не передаётся вовсе. Проверяйте поле с описанием количества в каталоге, а не предполагайте.

Проверка получателя

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

Заказ в две фазы

# 1. фиксируем цену, депозит не тронут
curl -X POST $API/order/create \
  -H "Authorization: Bearer $KEY" \
  -d '{"custom_id":"a3f1","product":"stars",
       "quantity":500,"username":"durov"}'

# 2. списываем депозит и уходим в доставку
curl -X POST $API/order/pay \
  -H "Authorization: Bearer $KEY" \
  -d '{"custom_id":"a3f1"}'

Между этими двумя запросами у вас на руках зафиксированная цена, которую можно показать клиенту. Держится она до момента истечения заказа, дальше он отменяется сам.

Опрос статуса

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

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

Деньги считайте в целых

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

Ошибки

По коду ответа сразу видно, чинить у себя или ждать платформу: 400 это валидация, 401 ключ, 402 не хватило депозита, 404 не найден, 409 заказ нельзя оплатить, 429 лимит, 503 товар недоступен. Отдельно приходит код причины провала доставки: неверный получатель, кончилась позиция, товар отключён, отказ поставщика.

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

Порядок работ

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