کلیات سیستم بازار اسکناس همتا به همتا¶

مقدمه¶

این مستندات راهنمای جامع برای یکپارچه‌سازی با سیستم بازار اسکناس همتا به همتا (P2P) است. این سیستم به کاربران اجازه می‌دهد تا به صورت مستقیم و بدون واسطه مرکزی، اسکناس‌های خود را معامله کنند.

مفهوم بازار همتا به همتا (P2P)¶

چیست؟¶

بازار همتا به همتا (Peer-to-Peer) یک سیستم معاملاتی است که در آن:

کاربران به صورت مستقیم با یکدیگر معامله می‌کنند
هیچ واسطه مرکزی برای نگهداری دارایی‌ها وجود ندارد
امنیت معاملات از طریق سیستم escrow (وثیقه) تضمین می‌شود
قیمت‌ها توسط بازار تعیین می‌شود، نه یک مرجع مرکزی

نقش بانک‌ها¶

بانک‌ها در این سیستم می‌توانند:

ارائه‌دهنده خدمات به کاربران خود باشند
متصل‌کننده کاربران به بازار P2P
نظارت بر معاملات و تضمین امنیت
ارائه API برای یکپارچه‌سازی در اپلیکیشن‌های خود

معماری سیستم¶

سرویس‌های اصلی¶

┌─────────────────────────────────────────────────────────────┐
│                    سیستم بازار P2P                          │
└─────────────────────────────────────────────────────────────┘
         │
         ├──────────────────────────────────────────┐
         │                                          │
    ┌────▼────┐                              ┌────▼────┐
    │  Auth   │                              │  User   │
    │  API    │                              │  API    │
    └────┬────┘                              └────┬────┘
         │                                          │
         └────────────────┬─────────────────────────┘
                          │
                    ┌─────▼─────┐
                    │ Accounting│
                    │   API     │
                    └─────┬─────┘
                          │
                    ┌─────▼─────┐
                    │ Exchange  │
                    │   API     │
                    └───────────┘

توضیح سرویس‌ها¶

1. Auth API¶

احراز هویت کلاینت‌ها
دریافت access token و refresh token
با استفاده از client_id و client_secret

2. User API¶

مدیریت کاربران
ایجاد کاربر جدید
دریافت و ویرایش اطلاعات کاربر
ایجاد منابع اولیه (کیف پول)

3. Accounting API¶

مدیریت مالی
کیف پول‌ها و موجودی‌ها
واریز و برداشت
تراکنش‌ها و holdها

4. Exchange API¶

بازار معاملاتی
سیمبول‌های معاملاتی
سشن‌های معاملاتی
سفارش‌ها و معاملات
داده‌های بازار

گردش کار معاملاتی¶

مرحله 1: احراز هویت¶

Client → Auth API (login)
       ← access_token + refresh_token

مرحله 2: ایجاد کاربر و کیف پول¶

Client → User API (create user)
       ← user_id + wallet_id

مرحله 3: واریز وجه¶

Client → Accounting API (deposit)
       ← transaction_id

مرحله 4: مشاهده بازار¶

Client → Exchange API (get symbols/sessions)
       ← لیست نمادها و زمان‌های معاملاتی

مرحله 5: ثبت سفارش¶

Client → Exchange API (create order)
       ← order_id

مرحله 6: انجام معامله¶

System → Matching Engine
       ← trade_id + status

مرحله 7: مشاهده نتیجه¶

Client → Exchange API (get trades)
       ← لیست معاملات انجام شده

مزایای سیستم¶

برای کاربران¶

✅ قیمت‌گذاری رقابتی - کشف قیمت بهتر
✅ دسترسی به نقدینگی - بازار گسترده‌تر
✅ انعطاف‌پذیری - معامله در هر زمان
✅ شفافیت - تمام معاملات قابل ردیابی

برای بانک‌ها¶

✅ کاهش هزینه‌ها - بدون نیاز به بازارساز
✅ گسترش خدمات - ارائه بازار P2P
✅ رقابت‌پذیری - جذب کاربران بیشتر
✅ امنیت - سیستم وثیقه هوشمند

ساختار داده‌های کلی¶

پاسخ استاندارد لیست¶

تمامی اندپوینت‌های لیست‌گیری از ساختار زیر پیروی می‌کنند:

{
  "heads": {
    "uid": "شناسه",
    "created_at": "تاریخ ایجاد",
    "updated_at": "تاریخ به‌روزرسانی"
  },
  "items": [
    {
      "uid": "item_1",
      "field1": "value1",
      "field2": "value2"
    },
    {
      "uid": "item_2",
      "field1": "value1",
      "field2": "value2"
    }
  ],
  "total": 100,
  "offset": 0,
  "limit": 10
}

پاسخ خطا¶

{
  "detail": [
    {
      "loc": ["body", "field_name"],
      "msg": "توضیح خطا",
      "type": "error_type"
    }
  ]
}

نکات امنیتی¶

احراز هویت¶

تمامی درخواست‌ها (به جز login) نیاز به JWT Token دارند
توکن در هدر Authorization: Bearer <token> ارسال شود
توکن‌ها دارای زمان انقضا هستند

دسترسی‌ها¶

هر کاربر فقط به داده‌های خود دسترسی دارد
برخی اندپوینت‌ها نیاز به نقش خاص دارند
تمامی دسترسی‌ها لاگ می‌شود

شروع کار¶

گام 1: دریافت توکن¶

curl -X POST "${BASE_URL}/api/auth/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

گام 2: استفاده از توکن¶

export JWT_TOKEN="your_access_token"

curl -X GET "${BASE_URL}/api/user/v1/users/me" \
  -H "Authorization: Bearer $JWT_TOKEN"

گام 3: شروع معاملات¶

به بخش رفرنس API مراجعه کنید و با توجه به نیاز خود از اندپوینت‌ها استفاده کنید.

مسیر یادگیری پیشنهادی¶

مطالعه کامل این صفحه - درک کلیت سیستم
بخش مبانی API - قراردادها و احراز هویت
بخش منطق دامنه - درک گردش کار بازار
بخش رفرنس API - جزئیات هر اندپوینت
بخش مثال‌ها - کدهای آماده استفاده

پشتیبانی¶

برای سوالات فنی: - ایمیل: [email protected] - Swagger: https://app.uln.me/api/exchange/v1/docs - ساعات پاسخگویی: شنبه تا چهارشنبه، ۹ تا ۱۷

نکته: این مستندات به صورت مداوم به‌روزرسانی می‌شود. آخرین تغییرات را در بخش Changelog دنبال کنید.