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

VirtuOZ платформасы /api/v1/… префиксті бар нұсқаланған JSON API ұсынады — төлем және эскроу қызметтеріне тән талаптарға сәйкес: нақты шарттар, аутентификацияланған сессиялар және тексерілетін әрекеттер. YOUR_HOST орнына орнату хостын қойыңыз. Маршруттардың негізгі дерегі — сервер коды; OpenAPI операциялардың кең жиынтығын сипаттайды.

Қолдау, хелпдеск және автоматтандыру

Интеграция, өндірістік кіру, webhook сценарийлері немесе сіздің стекіңізге автоматтандыру бойынша сұрақтар үшін хелпдеск арқылы хабарласыңыз: анықтама орталығынан тикет ашыңыз немесе support@evopay.biz жазыңыз. Авторизацияланған клиенттер POST /api/v1/helpdesk/tickets арқылы тикет жасай алады.

Біз интеграцияны автоматтандыруға дайынбыз — бухгалтерия, ERP немесе маркетплейстер: песочница, тест деректері, қателерді өңдеу және іске қосу алдында AML/KYC сәйкестігін келісу.

Құжаттама

• Интерактив: /docs (Swagger UI), конфигурацияда қосылған болса.
• Схема: GET /api/v1/openapi.json. /docs UI бір 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 күйі.
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 саясатын қайта жүктеу.

Профиль және әмиян

Әдіс	Жол	Ескерту
GET	/api/v1/me	Профиль.
GET	/api/v1/wallet/balances	Қалдықтар.
GET	/api/v1/wallet/activity	Қозғалыс.

Эскроу және дау

Әдіс	Жол	Ескерту
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}	Лендинг.

Email үлгілері

Әдіс	Жол	Ескерту
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	Сканер.
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/…	POST — проекция replay.
/api/v1/admin/events/export/…	GET — оқиға аудиті.
/api/v1/admin/users …	Пайдаланушылар.
/api/v1/admin/kyc/…	KYC кезегі.
/api/v1/admin/transactions …	Транзакцияларды қарау.
/api/v1/admin/compliance/reports	Комплаенс есептері.
/api/v1/admin/escrow/contracts	Эскроу бақылау.
/api/v1/admin/cms/legal|help|email|landing	CMS (/draft, /publish, /transition, /rollback).

Мысалдар

{
  "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 -X POST "https://YOUR_HOST/api/v1/escrow" \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"title":"Келісім","description":"…","amount":"8000.00","currency":"USD"}'

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