HTTP API и интеграция

Платформа VirtuOZ предоставляет версионированный JSON API с префиксом /api/v1/… в духе требований к платёжным и эскроу-сервисам: явные контракты, аутентифицированные сессии и проверяемые операции. Замените YOUR_HOST на хост вашего стенда. Источник истины по маршрутам — код сервера; подмножество операций описано в OpenAPI.

Поддержка, хелпдеск и автоматизация

По вопросам интеграции, промышленного доступа, сценариев с webhooks или автоматизации под ваш стек обращайтесь в хелпдеск: создайте обращение в справочном центре или напишите на support@evopay.biz. Авторизованные клиенты могут создавать тикеты через POST /api/v1/helpdesk/tickets.

Мы готовы автоматизировать интеграцию в ваши учётные системы, ERP или маркетплейсы: поможем с песочницей, тестовыми данными, обработкой ошибок и, при необходимости, согласованием комплаенс-профиля (AML/KYC) перед запуском.

Документация и обнаружение

• Интерактив: /docs (Swagger UI), если включено в конфигурации.
• Схема: GET /api/v1/openapi.json. UI на /docs подгружает тот же OpenAPI через /api/v1/openapi-ui.json, когда документация доступна.
• Здоровье: GET /health, GET /readiness, GET /api/v1/status; GET /metrics — Prometheus (часто ограничен на периметре).

Соглашения

• Транспорт: HTTPS/TLS в промышленной среде.
• Формат: Content-Type: application/json, кроме загрузки доказательств по спору (multipart).
• Аутентификация: после POST /api/v1/auth/login — access JWT в cookie и/или Authorization: Bearer …; обновление — POST /api/v1/auth/refresh.
• Авторизация: RBAC; отказы оформляются структурированным JSON.
• Идемпотентность: для чувствительных операций может использоваться Idempotency-Key — см. OpenAPI.

Операционные и потоковые

Метод	Путь	Комментарий
GET	/health	Liveness.
GET	/readiness	Readiness зависимостей.
GET	/metrics	Метрики Prometheus.
GET	/api/v1/status	Статус API (JSON).
GET	/api/v1/openapi.json	OpenAPI.
GET	/api/v1/notifications/stream	SSE-уведомления (политика доступа — по развёртыванию).

Аутентификация и сессии

Метод	Путь	Комментарий
POST	/api/v1/auth/register	Регистрация.
POST	/api/v1/auth/login	Вход.
POST	/api/v1/auth/refresh	Обновление токена.
POST	/api/v1/auth/logout	Выход из текущей сессии.
POST	/api/v1/auth/logout-all	Завершить все сессии.
GET	/api/v1/auth/sessions	Список сессий.
POST	/api/v1/auth/sessions/{session_id}/revoke	Отозвать сессию.
POST	/api/v1/auth/mfa/enroll	Включение TOTP.
POST	/api/v1/auth/mfa/verify	Проверка TOTP.
POST	/api/v1/auth/mfa/disable	Отключение TOTP.
POST	/api/v1/auth/rbac-cache/invalidate	Сброс кэша RBAC.
POST	/api/v1/auth/i18n/reload	Перезагрузка локалей (подписанный запрос оператора).
POST	/api/v1/auth/readiness-policy/reload	Перезагрузка readiness policy (подписанный запрос).

Профиль и кошелёк

Метод	Путь	Комментарий
GET	/api/v1/me	Профиль.
GET	/api/v1/wallet/balances	Остатки.
GET	/api/v1/wallet/activity	Движения (параметры пагинации в query).

Эскроу и споры

Метод	Путь	Комментарий
POST	/api/v1/escrow	Создать контракт.
GET	/api/v1/escrow/contracts	Список контрактов.
GET	/api/v1/escrow/contracts/{escrow_id}	Детали.
GET	/api/v1/escrow/contracts/{escrow_id}/history	История.
POST	/api/v1/escrow/{escrow_id}/fund	Финансирование.
POST	/api/v1/escrow/{escrow_id}/release	Выплата.
POST	/api/v1/escrow/{escrow_id}/dispute	Спор.
POST	/api/v1/escrow/{escrow_id}/dispute/evidence	Загрузка доказательств.
GET	/api/v1/escrow/{escrow_id}/dispute/evidence	Список файлов.
GET	/api/v1/escrow/{escrow_id}/dispute/evidence/{file_id}	Скачивание.
POST	/api/v1/escrow/{escrow_id}/dispute/evidence/{file_id}/delete	Удаление файла.
POST	/api/v1/escrow/{escrow_id}/dispute/resolve	Разрешение спора.
POST	/api/v1/escrow/{escrow_id}/dispute/reject	Отклонение спора.

Комплаенс

Метод	Путь	Комментарий
POST	/api/v1/compliance/reports	Создать отчёт.
GET	/api/v1/compliance/reports/{jurisdiction}	Список по юрисдикции.
POST	/api/v1/compliance/travel-rule	Travel Rule.
GET	/api/v1/compliance/travel-rule/recent	Недавние переводы.

Опубликованный контент (чтение)

Метод	Путь	Комментарий
GET	/api/v1/cms/legal/{slug}	Юридический документ.
GET	/api/v1/cms/help	Список статей справки.
GET	/api/v1/cms/help/{slug}	Статья справки.
GET	/api/v1/cms/landing/{slug}	Лендинг.

Шаблоны писем (превью и тест)

Метод	Путь	Комментарий
POST	/api/v1/cms/email/{slug}/preview	Превью (привилегированно).
POST	/api/v1/cms/email/{slug}/test-send	Тестовая отправка.

Хелпдеск

Метод	Путь	Комментарий
POST	/api/v1/helpdesk/tickets	Создать тикет.
GET	/api/v1/helpdesk/tickets	Список (в рамках прав вызывающего).
GET	/api/v1/helpdesk/tickets/{ticket_id}	Карточка тикета.
POST	/api/v1/helpdesk/tickets/{ticket_id}/internal-notes	Внутренняя заметка (персонал).
POST	/api/v1/helpdesk/tickets/{ticket_id}/context-links	Контекстная ссылка (персонал).

Платформенные утилиты

Метод	Путь	Комментарий
POST	/api/v1/platform/storage/shard-path	Превью шардирования хранилища.
POST	/api/v1/platform/cms/workflow/next-status	Превью перехода CMS workflow.
POST	/api/v1/platform/helpdesk/sla	Превью SLA.
POST	/api/v1/platform/i18n/message	Превью i18n сообщения.

Крипто-кастоди (платформа)

Метод	Путь	Комментарий
POST	/api/v1/platform/crypto/scanner/ingest	Ingest сканера.
POST	/api/v1/platform/crypto/address/allocate	Выделить адрес пополнения.
POST	/api/v1/platform/crypto/withdrawals/request	Заявка на вывод.
POST	/api/v1/platform/crypto/withdrawals/{withdrawal_id}/sign	Подпись вывода.
POST	/api/v1/platform/crypto/withdrawals/{withdrawal_id}/rollback	Откат вывода.

Администрирование (RBAC)

Префиксы для операторской автоматизации. Требуются административные роли; ключи нельзя встраивать в клиенты конечных пользователей.

Префикс / шаблон	Возможности
/api/v1/admin/events/replay/{aggregate_type}/{aggregate_id}	POST — replay проекций.
/api/v1/admin/events/export/{aggregate_type}/{aggregate_id}	GET — экспорт аудита событий.
/api/v1/admin/users … /{user_id} … /role, /status	Пользователи и жизненный цикл.
/api/v1/admin/kyc/queue, /api/v1/admin/kyc/{user_id}/decision	Очередь KYC и решения.
/api/v1/admin/transactions … /{tx_id} … /flag, /resolve, /reconcile	Разбор транзакций.
/api/v1/admin/compliance/reports	Отчёты (админ).
/api/v1/admin/escrow/contracts	Надзор за эскроу.
/api/v1/admin/cms/legal (+ /draft, /publish, /transition, /rollback)	CMS юридических документов.
/api/v1/admin/cms/help (+ те же суффиксы)	CMS справки.
/api/v1/admin/cms/email (+ те же суффиксы)	CMS email-шаблонов.
/api/v1/admin/cms/landing (+ те же суффиксы)	CMS лендингов.

Примеры

{
  "email": "user@example.com",
  "password": "YourStrongPassw0rd!",
  "display_name": "Demo User"
}

curl -sS -X POST "https://YOUR_HOST/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "YourStrongPassw0rd!",
    "display_name": "Demo User"
  }'

curl -sS -X POST "https://YOUR_HOST/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "user@example.com",
    "password": "YourStrongPassw0rd!"
  }'

curl -sS "https://YOUR_HOST/api/v1/me" -b cookies.txt

curl -sS "https://YOUR_HOST/api/v1/wallet/balances" -b cookies.txt

curl -sS "https://YOUR_HOST/api/v1/wallet/activity?limit=20" -b cookies.txt

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "title": "Поставка оборудования",
    "description": "Серверное оборудование по спецификации",
    "amount": "8000.00",
    "currency": "USD"
  }'

Далее подставьте ESCROW_ID:

curl -sS "https://YOUR_HOST/api/v1/escrow/contracts/ESCROW_ID" -b cookies.txt

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow/ESCROW_ID/fund" \
  -H "Content-Type: application/json" -b cookies.txt -d '{}'

curl -sS -X POST "https://YOUR_HOST/api/v1/escrow/ESCROW_ID/release" \
  -H "Content-Type: application/json" -b cookies.txt -d '{}'

curl -sS "https://YOUR_HOST/api/v1/status"
curl -sS "https://YOUR_HOST/readiness"