Сменили базовый URL, а дальше что: чек-лист переезда бота на handler_api.php
Если ваш бот уже работает с API в стиле sms-activate, переезд на наш handler_api.php начинается с одной строки в конфиге: базового адреса. Эндпоинт один, запросы идут методом GET на путь /stubs/handler_api.php, названия методов привычные. Сложности прячутся в допущениях, зашитых в старую интеграцию: таймауты, частота опроса, ID стран, логика возвратов. Ниже чек-лист, который мы советуем пройти на отдельном ключе, пока боевой трафик идёт по старой схеме.
Какие методы совпадают
Наш sms-activate-совместимый API закрывает основной цикл бота getPrices → getNumber → getStatus → setStatus и справочные вызовы вокруг него:
- getBalance: баланс аккаунта, к которому привязан ключ;
- getCountries и getServicesList: справочники стран и сервисов;
- getPrices: цены по сервисам и странам;
- getNumber: покупка номера под сервис;
- getStatus: статус активации и код;
- setStatus: 3 запросить ещё код, 6 завершить активацию, 8 отменить.
Если бот вызывает другие методы или шлёт в setStatus другие значения, найдите эти места в коде до переезда и проверьте на стенде, что бот делает с ответом.
Что проверить в логике бота
- Коды стран и сервисов. Не переносите ID из старого конфига вслепую: выгрузите getCountries и getServicesList и сверьте с тем, что зашито в боте.
- Таймер ожидания кода. Срок активации задаётся для каждого сервиса отдельно, сейчас это час. С одной константой на все сервисы бот либо бросит активацию раньше срока, либо продолжит опрашивать уже закрытую. Держите таймер по каждому сервису и сверьте сроки на стенде.
- Отмена. setStatus=8 не проходит в первую минуту после покупки. Если бот отменяет заказ сразу при сбое, добавьте повтор через 60 секунд.
- Бюджет запросов. Лимит: 600 запросов в минуту на ключ. Код бот забирает опросом getStatus, и основную часть лимита съедает именно он. Тридцать активаций с опросом раз в секунду дают 1800 запросов в минуту, втрое больше допустимого. Те же тридцать с опросом раз в пять секунд дают 360, и остаётся запас на getPrices и getBalance.
- Возвраты. Если код не пришёл до конца срока, деньги возвращаются сами, при отмене до кода тоже. Возврат идёт только на внутренний баланс аккаунта, не на карту и не на кошелёк. После получения SMS услуга считается оказанной, возврата по такому заказу нет. Если у вас есть свой учёт денег по заказам, сверьте его с этими правилами.
- Повторный код. После setStatus=3 бот возвращается к опросу getStatus, а не закрывает активацию.
- Валюта. Цены и баланс считаются в долларах США. Рублёвые пороги цены в конфиге бота пересчитайте.
- Одновременные заказы. Их лимит зависит от репутации аккаунта. В кабинете видны действующий лимит, занятость и доля заказов с кодом за 7 дней. Бот, который берёт номера «про запас» и потом массово отменяет их, тянет эту долю вниз.
softId для владельцев софта
Если вы распространяете свой софт, его можно подключить к партнёрской программе. Заявка проходит ручную модерацию, обычно до суток, после одобрения вы получаете software_id. Софт передаёт его в параметре softId при покупке номера, а владельцу начисляется 5% от цены каждой активации его пользователей, без лимита. Пользователи платят со своих аккаунтов, цена для них не меняется. Параметр необязательный: без него API работает так же.
Ключи и прогон на стенде
В разделе API кабинета можно выпустить несколько именованных ключей. Строку ключа мы показываем один раз и храним только её отпечаток, поэтому кладите ключ в хранилище секретов сразу после выпуска. Если ключ потерян, выпустите новый, а старый отзовите. Лимит считается на ключ, так что стендовые тесты не отнимают запросы у боевого бота.
Порядок прогона:
- getBalance: ключ принят, баланс виден. Для шагов с 3 по 5 на балансе нужна сумма хотя бы на две активации.
- getPrices: по нужной паре «сервис + страна» есть цена.
- getNumber: номер выдан, бот сохранил ID активации.
- getStatus: бот опрашивает с боевой частотой и укладывается в лимит.
- Второй номер: купите его, выждите минуту и отправьте setStatus=8. Сумма заказа должна вернуться на баланс.
У каждого ключа в кабинете видна дата последнего использования. После переключения по ней видно, что запросы идут с боевого ключа, а стендовый затих и его можно отозвать.
Начните с раздела API в кабинете: выпустите ключ с именем вроде «стенд», прогоните на нём getBalance → getPrices → getNumber по своим сервисам и странам и только после этого меняйте адрес и ключ в боевом конфиге.