# CryptoBot Billing Setup

Этот документ описывает запуск и поддержку оплаты подписок через CryptoBot в LinkSnap.

## 1) Подготовить ключ шифрования настроек billing

В окружении приложения должен быть задан:

```env
BILLING_SETTINGS_ENCRYPTION_KEY="<64 hex chars>"
```

Требования:

- ровно 64 hex-символа
- используется для AES-256-GCM шифрования API-токена CryptoBot, сохранённого в базе

Пример генерации:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## 2) Включить CryptoBot в админке

1. Открой `Admin -> Платёжная система CryptoBot`.
2. Вставь API token в поле `API токен CryptoBot`.
3. При необходимости задай:
- сеть CryptoBot: `mainnet` (обычная) или `testnet` (тестовая)
- `accepted assets` (пусто или `all` = все доступные)
- срок жизни инвойса в секундах
- флаги комментариев и анонимной оплаты
4. Включи переключатель `Включить платёжную систему`.
5. Нажми `Сохранить настройки`.

Важно: продовый токен не хранится в `.env`, он хранится в базе в зашифрованном виде.
Важно: токен должен соответствовать выбранной сети (mainnet/testnet).

## 3) Скопировать webhook URL и настроить его в CryptoBot

В блоке настроек провайдера есть поле `Webhook URL` и кнопка `Копировать`.

Ожидаемый формат:

```text
https://<domain>/api/billing/providers/cryptobot/webhook/<secret>
```

Этот URL нужно указать в настройках webhook у CryptoBot.

Важно: нельзя указывать только домен (например, `https://shortix.space`).
Нужен полный путь до webhook endpoint с секретом.

## 4) Проверить подключение (`getMe`)

После сохранения токена нажми `Проверить подключение`.

Результат успешной проверки:

- обновляется `lastCheckedAt`
- в диагностике появляются `appId`, `appName`, `appUsername`

Если проверка не проходит, исправь токен и повтори сохранение/проверку.

## 5) Ротация токена

Порядок ротации без простоя:

1. Выпусти новый API token в CryptoBot.
2. Обнови токен в админке LinkSnap и сохрани настройки.
3. Нажми `Проверить подключение` и убедись, что `getMe` проходит.
4. Проверь создание нового инвойса через checkout.
5. Отзови старый token в CryptoBot.

## 6) Проверка доставки webhook

Проверить можно так:

1. Создать тестовый checkout на платный тариф.
2. Оплатить инвойс.
3. Убедиться, что в админке обновился `lastWebhookAt`, а ошибок нет.
4. Убедиться, что у пользователя в профиле активировался платный тариф.

Сервер дополнительно проверяет:

- заголовок `crypto-pay-api-signature` (HMAC-SHA-256 по raw JSON body)
- свежесть поля `request_date`

Дополнительно:

- при повторной доставке одного и того же события дубликат должен игнорироваться
- при неизвестном инвойсе webhook не должен падать, событие фиксируется как `IGNORED`