Коннекторы платформы Cloud

Name: Mockarty
Author: Mockarty

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

У каждого коннектора есть ревизия и неизменяемая версия учётных данных. Для изменения нужны недавняя step-up-проверка, текущая ревизия и стабильный ключ идемпотентности. При параллельном изменении сервер возвращает конфликт: перечитайте список коннекторов и проверьте новую ревизию перед повтором.

Значения секретов имеют контракт write-only. API, операторский интерфейс, вывод CLI, аудит и модели ответов SDK возвращают только безопасные метаданные: secret_configured, secret_fields и secret_revoked. Само значение учётных данных не возвращается.

Устаревшие настройки CLOUD_API_SMTP_* и CLOUD_API_COMMERCIAL_PROVIDERS_JSON больше не являются runtime-authority. После обновления процесс завершает запуск с явной ошибкой, если они остались непустыми, а не молча игнорирует учётные данные. Настройте и проверьте соответствующий коннектор через операторский API или CLI, затем удалите устаревшие переменные и перезапустите Cloud. На время перехода CLOUD_API_COMMERCIAL_PROVIDER_TIMEOUT_MS продолжает задавать таймаут обращения к платёжному провайдеру.

Поддерживаемые коннекторы

Коннектор	Ключ коннектора	Открытые настройки	Поля write-only
Исходящая почта	`smtp default`	`host`, `port`, `username`, `implicit_tls`	`password`
Яндекс ID	`oauth yandex`	`client_id`	`client_secret`
VK ID	`oauth vk`	`client_id`	`client_secret`
GitHub	`oauth github`	`client_id`	`client_secret`
ЮKassa	`payment yookassa main`	настройки аккаунта, рынка, валюты, канала и режима	`secret_key`, `webhook_hmac`
Stripe	`payment stripe main`	настройки аккаунта, рынка, валюты, канала и режима	`secret_key`, `webhook_secret`
АТОЛ Онлайн	`fiscal atol main`	реквизиты чека, налоги, аккаунт, рынок, валюта, канал и режим	`login`, `password`
Внутренние доски поддержки	`saas mockarty internal`	`base_url`, `namespace`, `project_id`, `issue_type`	`api_token`

Назначение внутренней доски поддержки

Настройте этот коннектор в операторском UI. Для развёрнутого назначения base_url должен быть HTTPS-хостом без пути, query, fragment, встроенных credentials и сырого IP-адреса. В локальной Compose-топологии разрешён только фиксированный внутренний адрес http://mockarty-saas-runtime-lb:5770. В namespace укажите выделенный внутренний тенант поддержки, в project_id — точный UUID проекта, а в issue_type — bug, task или story.

API-токен имеет контракт write-only; ограничьте его созданием и чтением задач только в этом внутреннем проекте. При изменении base_url, namespace или project_id токен нужно ввести заново: Cloud никогда не перенаправляет ранее сохранённые write-only credentials на новую authority. Сохранение новой версии коннектора не переносит уже поставленные в очередь маршруты: каждый маршрут остаётся привязан к точной неизменяемой версии credentials, выбранной при создании. Отзыв этой версии fail-closed останавливает её ожидающую работу.

Настройка через CLI

Передавайте через --secret-env только имя переменной окружения: сырое значение не попадает в аргументы процесса. Переменная должна быть задана в окружении CLI.

export MOCKARTY_SMTP_PASSWORD='replace-in-your-secure-shell'
mockarty cloud-connectors configure smtp default \
  --config host=smtp.example.internal \
  --config port=465 \
  --config username=mailer \
  --config implicit_tls=true \
  --secret-env password=MOCKARTY_SMTP_PASSWORD \
  --expected-revision 1 \
  --enabled \
  --idempotency-key smtp-config-20260830-1

До и после изменения просмотрите безопасные метаданные:

mockarty cloud-connectors list

У каждого коннектора, который можно проверить безопасно, есть действие «Проверить подключение» в кабинете (Оператор → Коннекторы) и та же команда в CLI. Проверка только читает: она никогда не создаёт платёж, возврат или чек.

SMTP отправляет одно тестовое письмо — только на подтверждённый адрес текущего оператора.
YooKassa читает запись магазина (GET /me) с сохранёнными идентификатором магазина и секретным ключом.
Stripe читает баланс аккаунта (GET /balance) с сохранённым секретным ключом.
АТОЛ Онлайн запрашивает API-токен (POST /getToken) с сохранёнными логином и паролем для настроенной группы касс.

mockarty cloud-connectors test smtp default --idempotency-key smtp-test-20260830-1
mockarty cloud-connectors test payment yookassa main --idempotency-key yookassa-probe-20260830-1
mockarty cloud-connectors test fiscal atol main --idempotency-key atol-probe-20260830-1

Ответ называет следующий шаг, а не повторяет текст провайдера: provider_ok (учётные данные работают), provider_rejected_credentials (провайдер ответил и отверг их — проверьте идентификаторы и секрет), provider_unreachable (провайдер не ответил — проверьте базовый адрес и исходящий доступ в сеть). Коннектору не обязательно быть основным, чтобы его проверить: только что введённый тестовый аккаунт можно проверить до того, как сделать его основным. Результат записывается на версию коннектора и показывается как статус последней проверки.

Скомпрометированную неизменяемую версию можно отозвать по version_id из безопасных метаданных:

mockarty cloud-connectors revoke VERSION_ID --idempotency-key connector-revoke-20260830-1

Отзыв работает fail-closed: runtime-адаптеры больше не могут использовать отозванную версию. Перед повторным включением доставки или платежей настройте и проверьте новую версию.

Сохранённая конфигурация или успешный HTTP-ответ не доказывают работу внешнего провайдера. Перед production-использованием выполните проверку подключения, а затем один полный тестовый платёж (и, для АТОЛ, один тестовый чек) в песочнице самого провайдера. OAuth-провайдеры проверяются входом через них.