# Руководство по быстрому старту Начните работу с Vilna всего за 15 минут. Это руководство проведет вас через настройку мониторинга первого адреса и получение уведомлений через webhook в реальном времени. ## Предварительные требования Перед началом вам понадобится: - Учетная запись Vilna с API ключом - Публично доступный webhook endpoint (или используйте ngrok для тестирования) - Базовые знания REST API ## Шаг 1: Получите API ключ 1. Зарегистрируйтесь для получения учетной записи Vilna 2. Перейдите в Настройки → API Ключи 3. Создайте новый API ключ и сохраните его в безопасном месте ```bash export VILNA_API_KEY="ваш_api_ключ_здесь" ``` ## Шаг 2: Добавьте первый адрес Вы можете импортировать отдельный адрес или использовать расширенный публичный ключ (xpub) для генерации множества адресов. ### Вариант А: Импорт одного адреса ```bash curl -X POST https://api.vilna.io/v1/addresses \ -H "Authorization: Bearer $VILNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123", "blockchain_gid": "eip155:1", "label": "Казначейский кошелек" }' ``` **Ответ:** ```json { "id": "addr_550e8400-e29b-41d4-a716-446655440000", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123", "blockchain_gid": "eip155:1", "label": "Казначейский кошелек", "status": "active", "created_at": "2024-01-15T10:30:00Z" } ``` ### Вариант Б: Импорт расширенного публичного ключа ```bash curl -X POST https://api.vilna.io/v1/xpubs \ -H "Authorization: Bearer $VILNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "xpub": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKp...", "blockchain_gid": "eip155:1", "label": "Депозиты клиентов" }' ``` Затем генерируйте адреса по мере необходимости: ```bash curl -X POST https://api.vilna.io/v1/addresses/generate/xpub/next \ -H "Authorization: Bearer $VILNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "xpub_id": "xpub_660e8400-e29b-41d4-a716-446655440001", "label": "Клиент #001" }' ``` ## Шаг 3: Создайте канал уведомлений Настройте webhook канал для получения уведомлений в реальном времени: ```bash curl -X POST https://api.vilna.io/v1/channels \ -H "Authorization: Bearer $VILNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "webhook", "name": "Мой Webhook", "webhook_url": "https://your-app.com/webhook", "webhook_secret": "сгенерируйте-случайный-32-символьный-секрет" }' ``` **Ответ:** ```json { "id": "chan_770e8400-e29b-41d4-a716-446655440002", "type": "webhook", "name": "Мой Webhook", "webhook_url": "https://your-app.com/webhook", "status": "active", "created_at": "2024-01-15T10:31:00Z" } ``` ## Шаг 4: Создайте подписку Свяжите ваш адрес с webhook каналом: ```bash curl -X POST https://api.vilna.io/v1/subscriptions \ -H "Authorization: Bearer $VILNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel_id": "chan_770e8400-e29b-41d4-a716-446655440002", "address_ids": ["addr_550e8400-e29b-41d4-a716-446655440000"], "event_types": ["transaction.confirmed"], "min_confirmations": 1 }' ``` **Ответ:** ```json { "id": "sub_880e8400-e29b-41d4-a716-446655440003", "channel_id": "chan_770e8400-e29b-41d4-a716-446655440002", "address_ids": ["addr_550e8400-e29b-41d4-a716-446655440000"], "event_types": ["transaction.confirmed"], "min_confirmations": 1, "status": "active", "created_at": "2024-01-15T10:32:00Z" } ``` ## Шаг 5: Реализуйте обработчик webhook Создайте простой обработчик webhook для обработки входящих уведомлений: ### Пример на Node.js ```javascript const express = require('express'); const crypto = require('crypto'); const app = express(); app.use(express.json()); const WEBHOOK_SECRET = 'ваш-webhook-секрет'; app.post('/webhook', (req, res) => { // Проверка подписи const signature = req.headers['x-vilna-signature']; const timestamp = req.headers['x-vilna-timestamp']; const eventId = req.headers['x-vilna-event-id']; const payload = `${timestamp}.${eventId}.${JSON.stringify(req.body)}`; const expectedSignature = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(payload) .digest('hex'); if (signature !== expectedSignature) { return res.status(401).send('Неверная подпись'); } // Обработка события const event = req.body; console.log(`Получено событие ${event.event_type}:`, event.data); switch (event.event_type) { case 'transaction.confirmed': // Обработка подтвержденной транзакции console.log(`Транзакция подтверждена: ${event.data.amount} ${event.data.asset_name}`); // Обновите базу данных, начислите средства пользователю и т.д. break; case 'transaction.pending': // Обработка ожидающей транзакции console.log(`Обнаружена ожидающая транзакция`); break; } // Всегда быстро возвращайте 200 OK res.status(200).send('OK'); }); app.listen(3000, () => { console.log('Обработчик webhook слушает порт 3000'); }); ``` ### Пример на Python ```python from flask import Flask, request import hmac import hashlib import json app = Flask(__name__) WEBHOOK_SECRET = 'ваш-webhook-секрет' @app.route('/webhook', methods=['POST']) def webhook(): # Проверка подписи signature = request.headers.get('X-Vilna-Signature') timestamp = request.headers.get('X-Vilna-Timestamp') event_id = request.headers.get('X-Vilna-Event-Id') payload = f"{timestamp}.{event_id}.{request.data.decode()}" expected_signature = hmac.new( WEBHOOK_SECRET.encode(), payload.encode(), hashlib.sha256 ).hexdigest() if signature != expected_signature: return 'Неверная подпись', 401 # Обработка события event = request.json print(f"Получено событие {event['event_type']}:", event['data']) if event['event_type'] == 'transaction.confirmed': # Обработка подтвержденной транзакции amount = event['data']['amount'] asset = event['data']['asset_name'] print(f"Транзакция подтверждена: {amount} {asset}") # Обновите базу данных, начислите средства пользователю и т.д. # Всегда быстро возвращайте 200 OK return 'OK', 200 if __name__ == '__main__': app.run(port=3000) ``` ## Шаг 6: Протестируйте интеграцию ### Отправьте тестовый webhook Проверьте работу вашего обработчика webhook: ```bash curl -X POST https://api.vilna.io/v1/channels/chan_770e8400-e29b-41d4-a716-446655440002/test \ -H "Authorization: Bearer $VILNA_API_KEY" ``` Вы должны получить тестовое событие на ваш webhook endpoint. ### Проверьте баланс адреса Запросите текущий баланс отслеживаемого адреса: ```bash curl https://api.vilna.io/v1/addresses/addr_550e8400-e29b-41d4-a716-446655440000/balances \ -H "Authorization: Bearer $VILNA_API_KEY" ``` **Ответ:** ```json { "items": [ { "asset_gid": "eip155:1/slip44:60", "asset_name": "ETH", "balance": "5.25", "usd_value": "12562.50", "last_updated": "2024-01-15T10:35:00Z" }, { "asset_gid": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "asset_name": "USDC", "balance": "10000.00", "usd_value": "10000.00", "last_updated": "2024-01-15T10:35:00Z" } ], "meta": { "total": 2, "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f7B123", "blockchain_gid": "eip155:1" } } ``` ## Шаг 7: Чек-лист для продакшена Перед запуском в продакшн убедитесь, что вы: - [ ] **Реализовали проверку подписи** для безопасности webhook - [ ] **Добавили обработку ошибок** для обработки webhook - [ ] **Настроили идемпотентность** используя event_id для предотвращения дублирования - [ ] **Настроили логику повторных попыток** для неудачных API вызовов - [ ] **Добавили мониторинг** для вашего webhook endpoint - [ ] **Протестировали с реальными транзакциями** в тестовой сети - [ ] **Установили подходящие требования к подтверждениям** для вашего случая - [ ] **Реализовали правильное логирование** для отладки - [ ] **Защитили API ключи** используя переменные окружения - [ ] **Настроили резервные каналы уведомлений** для критичных событий ## Распространенные сценарии использования ### Прием платежей ```javascript // Генерация уникального платежного адреса const address = await generateAddress(customerId); // Показать адрес клиенту displayPaymentAddress(address); // Webhook уведомит когда платеж поступит // Обработка в webhook обработчике ``` ### Мониторинг казначейства ```javascript // Добавить все казначейские кошельки const wallets = ['0x123...', '0x456...', '0x789...']; await addAddresses(wallets); // Настроить email уведомления для крупных переводов await createEmailChannel('treasury@company.com'); await createSubscription({ event_types: ['transaction.confirmed'], min_amount: '10000' }); ``` ### Депозиты биржи ```javascript // Импорт xpub HD кошелька const xpub = await importXpub(EXCHANGE_XPUB); // Генерация депозитного адреса для каждого пользователя async function getUserDepositAddress(userId) { const address = await generateFromXpub(xpub.id, `Пользователь ${userId}`); await saveUserAddress(userId, address); return address; } ``` ## Решение проблем ### Не получаете webhooks? 1. **Проверьте публичную доступность webhook URL** ```bash curl -X POST https://your-app.com/webhook \ -H "Content-Type: application/json" \ -d '{"test": true}' ``` 2. **Проверьте активность подписки** ```bash curl https://api.vilna.io/v1/subscriptions \ -H "Authorization: Bearer $VILNA_API_KEY" ``` 3. **Проверьте логи канала на наличие ошибок** ```bash curl https://api.vilna.io/v1/channels/chan_xxx/logs \ -H "Authorization: Bearer $VILNA_API_KEY" ``` ### Локальное тестирование с ngrok ```bash # Установите ngrok npm install -g ngrok # Запустите локальный сервер node webhook-handler.js # В другом терминале откройте его через ngrok ngrok http 3000 # Используйте URL от ngrok при создании канала # https://abc123.ngrok.io/webhook ``` ## Следующие шаги Поздравляем! Вы успешно: - ✅ Добавили адрес для мониторинга - ✅ Создали webhook канал - ✅ Настроили подписку - ✅ Реализовали обработчик webhook - ✅ Протестировали интеграцию Теперь вы можете: - 📖 Изучить [API Справочник](/apis/spec) для всех эндпоинтов - 🔧 Узнать о [Каналах уведомлений](/guides/channels) подробнее - 🏗️ Понять [Как работает Vilna](/guides/architecture-overview) - 💡 Просмотреть [Обзор архитектуры](/guides/architecture-overview) чтобы понять платформу ## Получить помощь - 📚 **Документация**: Доступна в этой документации - 💬 **Поддержка**: Свяжитесь с поддержкой через официальные каналы - 🐛 **Сообщить о проблеме**: [github.com/vilna-io/issues](https://github.com/vilna-io/issues)