Market Sessions API - رفرنس کامل¶

توضیحات کلی¶

این API برای مدیریت جلسات معاملاتی (Trading Sessions) استفاده می‌شود. هر نماد می‌تواند چندین جلسه معاملاتی در روز داشته باشد.

ساختار داده Session¶

{
  "uid": "sess_123abc",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "open_at": "2025-12-30T09:00:00Z",
  "close_at": "2025-12-30T17:00:00Z",
  "opening_price": "1000000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "Infinity",
  "quantity_tick_size": "100",
  "created_at": "2025-12-30T08:00:00Z",
  "updated_at": "2025-12-30T08:00:00Z"
}

فیلدها¶

uid: شناسه منحصر به فرد جلسه
tenant_id: شناسه تانانت (بانک/سازمان)
symbol: نماد معاملاتی
open_at: زمان شروع جلسه
close_at: زمان پایان جلسه
opening_price: قیمت شروع
broker_fee_percentage: درصد کارمزد بروکر
market_fee_percentage: درصد کارمزد بازار
price_tolerance_percentage: محدودیت نوسان قیمت (%)
quantity_tick_size: اندازه تیک حجم
created_at: تاریخ ایجاد
updated_at: تاریخ به‌روزرسانی

اندپوینت‌ها¶

1. List Sessions (لیست جلسات)¶

GET /api/exchange/v1/sessions

توضیحات: - دریافت لیست جلسات معاملاتی - شامل فیلترهای زمانی و نماد

پارامترهای Query: - offset (integer, optional, default: 0) - limit (integer, optional, default: 10, max: 100) - symbol (string, optional): فیلتر بر اساس نماد - open_at_from (string, optional): ISO 8601 - open_at_to (string, optional): ISO 8601 - created_at_from (string, optional): ISO 8601 - created_at_to (string, optional): ISO 8601

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

نمونه موفق¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/sessions?\
symbol=BTC-IRR&\
open_at_from=2025-12-30T00:00:00Z&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

name="__codelineno-2-1">{ "heads": { "uid": "شناسه", "symbol": "نماد", "open_at": "زمان شروع", "close_at": "زمان پایان", "opening_price": "قیمت شروع", "status": "وضعیت" }, "items": [ { "uid": "sess_123", "tenant_id": "tenant_001", "symbol": "BTC-IRR", "open_at": "2025-12-30T09:00:00Z", "close_at": "2025-12-30T17:00:00Z", "opening_price": "1000000000", "broker_fee_percentage": "0.1", "market_fee_percentage": "0.1", "price_tolerance_percentage": "Infinity", "quantity_tick_size": "100", "status": "active" }, { "uid": "sess_456", "tenant_id": "tenant_001", "symbol": "BTC-IRR", "open_at": "2025-12-31T09:00:00Z", "close_at": "2025-12-31T17:00:00Z", "opening_price": "1050000000", "broker_fee_percentage": "0.1", "market_fee_percentage": "0.1", "price_tolerance_percentage": "5", "quantity_tick_size": "100", "status": "upcoming" } ], "total": 2, "offset": 0, "limit": 10 }

نمونه ناموفق 1: عدم احراز هویت¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/sessions"

پاسخ (401 Unauthorized):

{
  "detail": "Not authenticated"
}

نمونه ناموفق 2: پارامتر تاریخ نامعتبر¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/sessions?open_at_from=invalid-date" \
  -H "Authorization: Bearer <user_token>"

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["query", "open_at_from"],
      "msg": "invalid datetime format, expected ISO 8601",
      "type": "value_error.datetime"
    }
  ]
}

2. Create Session (ایجاد جلسه)¶

POST /api/exchange/v1/sessions

توضیحات: - ایجاد جلسه معاملاتی جدید - تنظیم زمان‌ها و پارامترهای معاملاتی

بدنه درخواست:

{
  "symbol": "string",
  "open_at": "string",
  "close_at": "string",
  "opening_price": "string",
  "broker_fee_percentage": "string",
  "market_fee_percentage": "string",
  "price_tolerance_percentage": "string",
  "quantity_tick_size": "string"
}

فیلدهای اجباری: - symbol - open_at - close_at

دسترسی: admin

نمونه موفق¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/sessions" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "open_at": "2025-12-31T09:00:00Z",
    "close_at": "2025-12-31T17:00:00Z",
    "opening_price": "1050000000",
    "broker_fee_percentage": "0.1",
    "market_fee_percentage": "0.1",
    "price_tolerance_percentage": "5",
    "quantity_tick_size": "100"
  }'

پاسخ (201 Created):

{
  "uid": "sess_789",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "open_at": "2025-12-31T09:00:00Z",
  "close_at": "2025-12-31T17:00:00Z",
  "opening_price": "1050000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "5",
  "quantity_tick_size": "100",
  "created_at": "2025-12-30T14:00:00Z",
  "updated_at": "2025-12-30T14:00:00Z"
}

نمونه ناموفق 1: زمان نامعتبر¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/sessions" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "open_at": "2025-12-31T17:00:00Z",
    "close_at": "2025-12-31T09:00:00Z"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "close_at must be after open_at",
      "type": "value_error"
    }
  ]
}

نمونه ناموفق 2: همپوشانی جلسات¶

درخواست:

# جلسه‌ای که با جلسه موجود همپوشانی دارد
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/sessions" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "open_at": "2025-12-30T10:00:00Z",
    "close_at": "2025-12-30T12:00:00Z"
  }'

پاسخ (409 Conflict):

{
  "detail": "Session overlaps with existing session"
}

3. Retrieve Session (دریافت جلسه خاص)¶

POST /api/exchange/v1/sessions/{uid}

توضیحات: - دریافت اطلاعات کامل یک جلسه

پارامترهای Path: - uid (string, required): شناسه جلسه

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

نمونه موفق¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_123" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

{
  "uid": "sess_123",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "open_at": "2025-12-30T09:00:00Z",
  "close_at": "2025-12-30T17:00:00Z",
  "opening_price": "1000000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "Infinity",
  "quantity_tick_size": "100",
  "created_at": "2025-12-30T08:00:00Z",
  "updated_at": "2025-12-30T08:00:00Z"
}

نمونه ناموفق: جلسه یافت نشد¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_999" \
  -H "Authorization: Bearer <user_token>"

پاسخ (404 Not Found):

{
  "detail": "Session not found"
}

4. Update Session (به‌روزرسانی جلسه)¶

PATCH /api/exchange/v1/sessions/{uid}

توضیحات: - به‌روزرسانی پارامترهای جلسه - می‌تواند زمان‌ها یا کارمزدها را تغییر دهد

پارامترهای Path: - uid (string, required)

بدنه درخواست:

{
  "open_at": "string (اختیاری)",
  "close_at": "string (اختیاری)",
  "opening_price": "string (اختیاری)",
  "broker_fee_percentage": "string (اختیاری)",
  "market_fee_percentage": "string (اختیاری)",
  "price_tolerance_percentage": "string (اختیاری)",
  "quantity_tick_size": "string (اختیاری)"
}

دسترسی: admin

نمونه موفق¶

درخواست:

curl -X PATCH "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_123" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "close_at": "2025-12-30T18:00:00Z",
    "price_tolerance_percentage": "10"
  }'

پاسخ (200 OK):

{
  "uid": "sess_123",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "open_at": "2025-12-30T09:00:00Z",
  "close_at": "2025-12-30T18:00:00Z",
  "opening_price": "1000000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "10",
  "quantity_tick_size": "100",
  "created_at": "2025-12-30T08:00:00Z",
  "updated_at": "2025-12-30T14:30:00Z"
}

نمونه ناموفق: زمان نامعتبر¶

درخواست:

curl -X PATCH "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_123" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "open_at": "2025-12-30T19:00:00Z"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "open_at must be before current close_at",
      "type": "value_error"
    }
  ]
}

5. Delete Session (حذف جلسه)¶

DELETE /api/exchange/v1/sessions/{uid}

توضیحات: - حذف نرم جلسه (soft delete) - جلسه فعال نمی‌تواند حذف شود

پارامترهای Path: - uid (string, required)

دسترسی: admin

نمونه موفق¶

درخواست:

curl -X DELETE "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_123" \
  -H "Authorization: Bearer <admin_token>"

پاسخ (204 No Content):

بدون بدنه پاسخ

نمونه ناموفق 1: جلسه فعال¶

درخواست:

# جلسه‌ای که در حال حاضر فعال است
curl -X DELETE "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_123" \
  -H "Authorization: Bearer <admin_token>"

پاسخ (403 Forbidden):

{
  "detail": "Cannot delete active session"
}

نمونه ناموفق 2: جلسه یافت نشد¶

درخواست:

curl -X DELETE "{{ API_BASE_URL }}/api/exchange/v1/sessions/sess_999" \
  -H "Authorization: Bearer <admin_token>"

پاسخ (404 Not Found):

{
  "detail": "Session not found"
}

وضعیت‌های جلسه¶

1. Upcoming (پیش‌رو)¶

زمان فعلی < open_at

- جلسه هنوز شروع نشده - سفارش‌ها پذیرفته می‌شوند اما اجرا نمی‌شوند

2. Active (فعال)¶

open_at <= زمان فعلی <= close_at

- جلسه در حال اجرا - سفارشات اجرا می‌شوند

3. Closed (بسته شده)¶

زمان فعلی > close_at

- جلسه به پایان رسیده - سفارشات باقی مانده لغو می‌شوند

4. Paused (موقتاً متوقف)¶

توسط ادمین متوقف شده

- معاملات متوقف - سفارشات در صف انتظار

پارامترهای جلسه¶

1. Opening Price (قیمت شروع)¶

opening_price = "1000000000"

کاربرد: - قیمت مرجع برای شروع جلسه - محاسبه نوسانات

2. Broker Fee (کارمزد بروکر)¶

broker_fee_percentage = "0.1"

کاربرد: - کارمزد دریافتی بروکر - به صورت درصد

3. Market Fee (کارمزد بازار)¶

market_fee_percentage = "0.1"

کاربرد: - کارمزد بازار - به صورت درصد

4. Price Tolerance (محدودیت نوسان)¶

price_tolerance_percentage = "5"

کاربرد: - حداکثر نوسان قیمت نسبت به قیمت شروع - جلوگیری از دستکاری

5. Quantity Tick Size (تیک حجم)¶

quantity_tick_size = "100"

کاربرد: - حجم سفارشات باید مضربی از این عدد باشد - مثال: 100, 200, 300

مثال‌های کامل¶

نمونه 1: جلسه صبح¶

{
  "symbol": "BTC-IRR",
  "open_at": "2025-12-30T09:00:00Z",
  "close_at": "2025-12-30T12:00:00Z",
  "opening_price": "1000000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "5",
  "quantity_tick_size": "100"
}

توضیح: - زمان: 9 تا 12 - قیمت شروع: 1,000,000,000 IRR - کارمزد: 0.1% + 0.1% - نوسان: حداکثر ±5% - حجم: مضربی از 100

نمونه 2: جلسه عصر¶

{
  "symbol": "BTC-IRR",
  "open_at": "2025-12-30T13:00:00Z",
  "close_at": "2025-12-30T17:00:00Z",
  "opening_price": "1020000000",
  "broker_fee_percentage": "0.1",
  "market_fee_percentage": "0.1",
  "price_tolerance_percentage": "Infinity",
  "quantity_tick_size": "100"
}

توضیح: - زمان: 13 تا 17 - قیمت شروع: 1,020,000,000 IRR - نوسان: نامحدود (Infinity)

نمونه 3: جلسه با نوسان محدود¶

{
  "symbol": "USDT-IRR",
  "open_at": "2025-12-30T00:00:00Z",
  "close_at": "2025-12-30T23:59:59Z",
  "opening_price": "50000",
  "broker_fee_percentage": "0.05",
  "market_fee_percentage": "0.05",
  "price_tolerance_percentage": "1",
  "quantity_tick_size": "10"
}

توضیح: - زمان: 24 ساعته - قیمت شروع: 50,000 IRR - کارمزد: 0.05% + 0.05% - نوسان: حداکثر ±1% - حجم: مضربی از 10

گردش کار جلسه¶

sequenceDiagram
    participant Admin
    participant SessionAPI
    participant MatchingEngine
    participant DB

    Admin->>SessionAPI: POST /sessions (ایجاد جلسه)
    SessionAPI->>DB: ذخیره جلسه
    SessionAPI-->>Admin: تایید ایجاد

    Note over Admin,SessionAPI: انتظار تا زمان شروع

    System->>SessionAPI: بررسی زمان
    SessionAPI->>DB: فعال‌سازی جلسه
    SessionAPI->>MatchingEngine: شروع جلسه

    Note over MatchingEngine: پردازش سفارشات

    System->>SessionAPI: بررسی زمان پایان
    SessionAPI->>MatchingEngine: پایان جلسه
    SessionAPI->>DB: بستن جلسه

    MatchingEngine->>DB: لغو سفارشات باقی مانده

چک‌لیست ایجاد جلسه¶

قبل از ایجاد جلسه: - [ ] نماد وجود دارد - [ ] زمان‌ها معتبر هستند - [ ] همپوشانی با جلسات موجود ندارد - [ ] قیمت شروع منطقی است - [ ] کارمزدها تعریف شده‌اند - [ ] محدودیت نوسان مشخص است

نکات امنیتی¶

بررسی همپوشانی
قبل از ایجاد بررسی شود
جلوگیری از تداخل
تغییرات جلسه فعال
محدودیت در تغییرات
نیاز به تایید دو مرحله‌ای
لاگ‌گیری
تمام تغییرات ثبت شود
تغییرات زمان و کارمزد حتماً لاگ شود

خلاصه¶

اندپوینت	متد	توضیحات	دسترسی
`/sessions`	GET	لیست جلسات	همه
`/sessions`	POST	ایجاد جلسه	admin
`/sessions/{uid}`	POST	دریافت جلسه	همه
`/sessions/{uid}`	PATCH	به‌روزرسانی	admin
`/sessions/{uid}`	DELETE	حذف جلسه	admin

بعدی: مطالعه Orders API