Получите каталог и установите предел цены
Начните с GET /api/auth/me для проверки аккаунта и баланса. GET /api/catalog/services и GET /api/catalog/countries возвращают идентификаторы выбора. Актуальные предложения доступны через GET /api/catalog/prices?service=tg: замените tg нужным кодом. Дополнительный параметр country ограничивает результат выбранной страной.
POST /api/orders принимает service, country, max_price_micros и idempotency_key. Значение country отправляйте строкой. Предел суммы задаётся целым числом микродолларов: 1 000 000 единиц равен 1 USD. Используйте price_micros из предложения. При превышении лимита обновите цену и получите согласие на новую сумму.
Повторяйте ту же покупку, а не создавайте новую
Создавайте уникальный idempotency_key для каждой запланированной покупки и сохраняйте его до отправки запроса. Если ответ прерван, повторяйте ту же операцию с тем же ключом. Новый ключ при сетевом повторе может привести ко второй покупке.
Проверяйте статус ответа: HTTP 200 не всегда означает, что номер уже назначен. Заказ может находиться в покупке, ожидании, состоянии получения кода, ошибки или проверки. Проверка иногда означает неизвестный результат поставщика и сохранение зарезервированной суммы. Не подменяйте такой заказ автоматической новой покупкой.
Запрашивайте состояние существующего заказа
GET /api/orders показывает список, GET /api/orders/{id} читает отдельный заказ, а POST /api/orders/{id}/refresh запрашивает обновление статуса. Соблюдайте ограничения частоты и используйте опрос с интервалами и увеличением задержки при ошибках. После использования кода подходящую активацию можно завершить через POST /api/orders/{id}/finish.
POST /api/orders/{id}/cancel применяет те же условия ожидания и отсутствия кода, что и сайт. Запрос отмены или тайм-аут не доказывает возврат. Сверяйте итоговый заказ и записи GET /api/wallet/transactions.
Защищайте ключ как доступ к аккаунту
Не помещайте ключи во frontend JavaScript, открытые репозитории, URL или снимки экрана. Отзовите ключ в разделе разработчика, если он раскрыт или больше не используется. Не сохраняйте заголовки авторизации и полные сообщения с кодами в журналах без необходимости.
Обрабатывайте недостаток баланса, отсутствие номеров, изменения цены, ограничения частоты и неопределённые результаты поставщика отдельно. Проверьте интеграцию небольшим осознанным сценарием, храните идентификаторы заказов в своих записях и сверяйтесь с интерактивной документацией перед запуском.