Отделите публичный каталог от частного приёма
Публичные данные описывают сервис, страну, цену и продолжительность. Они не содержат выделенного номера телефона или кода. Активации принадлежат аккаунту и заказу с отдельным приватным отслеживанием.
Справочник сервисов и стран отделён от коммерческих предложений. Контракт интеграции требует API-каталог с авторитетной ценой и доступностью для заказов.
Каталог и заказ
Существующий контракт определяет GET /catalog/products и GET /catalog/products/:slug. Сервер предоставляет авторитетные данные о цене, длительности и явной доступности; отсутствие на складе остаётся неизвестным.
Заказы отправляют идентификатор продукта с ключом идемпотентности. Сервер проверяет цену и наличие перед резервированием или выделением. Просмотр страницы не запускает чувствительные действия.
Состояния приема
Модуль различает выделение, ожидание, получение, завершение, отмену, истечение срока и сбой. Выделение может быть в ожидании без номера; реальное ожидание и приём требуют номера и срока действия на сервере.
Каждое сообщение имеет стабильный идентификатор, отметку времени и текст. Бэкенд может предоставить извлечённый код; интерфейс не должен угадывать OTP. Публичный каталог не содержит выделенных номеров или приватных кодов.
Авторизованные действия и обновления
GET /activations и GET /activations/:id — приватные запросы на чтение. POST /activations/:id/actions отправляет отмену, завершение или повторную отправку с ключом идемпотентности. Бэкенд объявляет и перепроверяет разрешенные действия.
Приватное чтение использует сессию, язык интерфейса и подходящее кэширование. Интервалы отслеживания следуют контракту; истечение сервера и состояние имеют приоритет над таймером браузера.
Платежи, выделение и секреты провайдера
Счёт-фактура фиксирует актив, сеть, сумму, адрес и срок действия. Подтверждение оплаты и выделение номера — отдельные события. Бэкенд обрабатывает сбои и повторные попытки без двойного выделения.
Ключи провайдера и платёжные секреты остаются на сервере. API авторизует каждое чтение аккаунта, определяет хранение сообщений и сохраняет внутренние идентификаторы провайдера в тайне. Эта страница документирует контракт интеграции и не объявляет о публичном рабочем API.
Ссылка на конечную точку контракта
| Метод | Конечная точка | Роль |
|---|---|---|
GET | /catalog/products | Публичный каталог |
GET | /activations | Активации аккаунта |
GET | /activations/:id | Частное отслеживание приема |
POST | /activations/:id/actions | Авторизованное действие |
Это существующие пути фронтенд-контрактов, а не опубликованные конечные точки. Провайдер, аутентификация и интеграция оплаты ещё не подключены.