INFOCROSS Partner API: как интегрировать продажу VPN

Контур интеграции

Интеграция VPN API для партнёра состоит из Telegram-интерфейса и доверенного backend. Пользователь общается с вашим Telegram-ботом. Бот передаёт команду backend, а backend обращается к /api/partner/v1 с X-API-Key. Секрет не попадает в Telegram update и не возвращается пользователю.

API для VPN Telegram-бота позволяет получить тарифы, создать invoice, проверить его статус и показать выданные ключи. Актуальный набор методов и payload доступен партнёру в документации после выдачи доступа.

Храните соответствие telegramId, вашего orderId и invoiceId. Не используйте username как постоянный идентификатор. Логи должны скрывать API key, webhook secret и VPN URI.

Минимальный сценарий заказа

1. Backend получает список тарифов и формирует кнопки.
2. Пользователь выбирает тариф и срок.
3. Backend создаёт invoice с уникальным ключом идемпотентности.
4. Бот отправляет платёжную ссылку.
5. Backend проверяет статус по invoiceId или принимает webhook.
6. После payment.paid система выпускает доступ.
7. Backend получает ключи пользователя и показывает защищённую страницу или одноразовую кнопку.

Автоматическая выдача VPN ключей не должна запускаться по нажатию «Я оплатил». Доверяйте подтверждённому статусу провайдера.

Webhooks и состояния

Текущая реализация поддерживает события payment.paid, payment.failed и key.issued, а полный список нужно сверять в выданной документации. Webhook URL должен использовать публичный HTTPS.

Проверяйте HMAC SHA-256 по raw body с timing-safe comparison. Сохраняйте event id или комбинацию type и entity id, чтобы повторная доставка не создала второй заказ. Ответ 2xx отправляйте после устойчивой записи события.

Обрабатывайте порядок событий: payment.paid может прийти раньше key.issued. Пользователю показывайте «платёж принят, ключ создаётся», а не ошибку.

Test mode и проверка отказов

Начните с TEST-ключа. Тестовый invoice проверяет handler и уведомления, но не должен выдавать реальный VPN-доступ. Смоделируйте успешную оплату, отказ, повтор webhook, тайм-аут и недоступность вашего backend.

Проверьте повтор команды пользователя и двойное нажатие кнопки оплаты. Один idempotency key должен вернуть прежний результат, а не новый invoice.

Перед live-запуском настройте мониторинг ошибок API, очереди webhook и времени выдачи. Не выводите payload с секретами в общий журнал.

Защита API-интеграции

Храните API key и webhook secret в менеджере секретов. Ограничьте исходные IP, если эта функция согласована. Ротируйте ключ после утечки и разделяйте test и live credentials.

Проверяйте входные данные пользователя на своём backend. Тариф и сумма должны поступать из доверенного API-ответа, а не из callback_data без серверной сверки.

Webhook endpoint не должен обращаться к произвольному URL из payload. Ограничьте размер body, время запроса и частоту. Админские методы не публикуйте через бот.

Запуск и эксплуатация

Получите доступ через /ru/partners, приложив статистику площадки и описание сценария. После согласования изучите runtime-документацию и ставки. Не копируйте endpoint из старых статей.

Запустите ограниченную группу пользователей. Сверьте invoice, фактические оплаты, выдачу и поддержку. Подготовьте ручной сценарий восстановления заказа по invoiceId.

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

Модель данных партнёрского backend

Храните собственный userId, Telegram ID, orderId, idempotency key, invoiceId, статус платежа и идентификаторы выданных ключей. Не сохраняйте VPN URI в аналитической таблице. Доступ показывайте через защищённый endpoint с авторизацией.

Используйте конечный автомат состояний: draft, invoice_created, payment_pending, paid, provisioning, ready, failed и refunded. Разрешённые переходы защищают от ситуации, когда поздний payment.failed перезаписывает уже подтверждённую оплату.

Операцию выдачи связывайте с invoiceId. Повтор webhook должен находить существующий результат. База данных, а не память процесса, служит источником состояния после перезапуска.

Пользовательский интерфейс ошибок

Показывайте пользователю номер заказа и понятный статус. Pending означает ожидание подтверждения, provisioning означает создание доступа, failed требует новой попытки после проверки причины. Не выводите внутренний stack trace.

Кнопка «Проверить платёж» должна запрашивать существующий invoice. Кнопка «Оплатить снова» создаёт новый только после финального отказа или истечения. Ограничьте частоту нажатий.

При готовом ключе предложите страницу доступа, QR и инструкции по ОС. Не помещайте полный URI в push-уведомление, которое видно на заблокированном экране.

Наблюдаемость и runbook

Собирайте количество API-запросов по endpoint и status code, время создания invoice, задержку paid-to-key и число неуспешных webhook. Метрики не должны содержать Telegram ID, ключи и секреты.

Настройте алерт на рост 401, 429 и 5xx, очередь событий и длительное provisioning. Runbook должен объяснять проверку Partner API, повтор безопасной операции и уведомление пользователя.

Регулярно тестируйте ротацию API key и webhook secret. После ротации старый секрет должен перестать приниматься. Сохраняйте audit trail административных изменений без plaintext credentials.

Retry, rate limit и circuit breaker

Повторяйте GET и безопасные проверки с ограниченным exponential backoff. POST invoice повторяйте только с тем же idempotency key. Уважайте 429 и Retry-After, не создавая нагрузку очередью мгновенных повторов.

После серии 5xx временно остановите новые попытки и покажите пользователю состояние сервиса. Сохраните заказ локально для последующей сверки.

Ограничьте время каждого запроса. Timeout не доказывает, что операция не выполнена, поэтому сначала запросите существующий invoice по сохранённому идентификатору.

Добавьте dead-letter очередь для событий, которые не удалось обработать после допустимых повторов. Оператор должен видеть entity id, тип и обезличенную причину. Ручной replay использует тот же обработчик идемпотентности.

Не повторяйте payment.paid через административный скрипт без сверки invoice. Ошибка такого replay способна выдать второй доступ.