نمونه‌های cURL آماده¶

این صفحه شامل نمونه‌های cURL آماده برای تست API است. تمامی مثال‌ها با {BASE_URL} کار می‌کنند.

تنظیمات اولیه¶

# تعریف متغیرهای محیطی
export BASE_URL="https://api.example.com"
export CLIENT_ID="your_client_id"
export CLIENT_SECRET="your_client_secret"

# یا برای محیط توسعه
export BASE_URL="http://localhost:8000"

1. Health Check¶

درخواست¶

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

پاسخ موفق¶

{
  "status": "up"
}

2. احراز هویت (Authentication)¶

درخواست:

curl -X POST "{{ USSO_BASE_URL }}/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "client_abc123",
    "client_secret": "secret_xyz789"
  }'

پاسخ موفق:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "refresh_token_xyz789abc123"
}

پاسخ ناموفق (کلاینت نامعتبر):

{
  "detail": "Invalid client credentials"
}

پاسخ ناموفق (داده ناقص):

{
  "detail": [
    {
      "loc": ["body", "client_secret"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

2.2. Refresh - دریافت توکن جدید¶

درخواست:

curl -X POST "{{ USSO_BASE_URL }}/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "refresh_token_xyz789abc123"
  }'

پاسخ موفق:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.new_token...",
  "token_type": "bearer",
  "expires_in": 86400
}

پاسخ ناموفق (توکن منقضی):

{
  "detail": "Refresh token has expired"
}

3. Health Check (API Exchange)¶

درخواست¶

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

پاسخ موفق¶

{
  "status": "up"
}

4. Symbol API¶

4.1. لیست نمادها¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols?\
is_active=true&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <your_jwt_token>"

پاسخ موفق:

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "is_active": "فعال"
  },
  "items": [
    {
      "uid": "sym_123",
      "symbol": "BTC-IRR",
      "is_active": true
    },
    {
      "uid": "sym_456",
      "symbol": "ETH-IRR",
      "is_active": true
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 10
}

پاسخ ناموفق (بدون توکن):

{
  "detail": "Not authenticated"
}

4.2. ایجاد نماد (فقط ادمین)¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SOL-IRR",
    "price_precision": 2,
    "quantity_precision": 6,
    "min_order_quantity": "0.1",
    "tick_size": "1000",
    "daily_fluctuation_price_limit_percent": "10",
    "description": "Solana to IRR"
  }'

پاسخ موفق:

{
  "uid": "sym_101",
  "symbol": "SOL-IRR",
  "is_active": true,
  "created_at": "2025-12-30T14:00:00Z"
}

پاسخ ناموفق (نماد تکراری):

{
  "detail": "Symbol already exists"
}

5. Order API¶

5.1. ایجاد سفارش لیمیت خرید¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.5",
    "time_in_force": "good-till-canceled"
  }'

پاسخ موفق:

{
  "uid": "ord_789xyz",
  "status": "active",
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "filled": "0.0",
  "created_at": "2025-12-30T12:00:00Z"
}

پاسخ ناموفق (موجودی ناکافی):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "insufficient balance",
      "type": "value_error"
    }
  ]
}

پاسخ ناموفق (حجم کمتر از حداقل):

{
  "detail": [
    {
      "loc": ["body", "quantity"],
      "msg": "value is less than minimum",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0.0001}
    }
  ]
}

5.2. ایجاد سفارش مارکت فروش¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "sell",
    "type": "market",
    "quantity": "0.2"
  }'

پاسخ موفق:

{
  "uid": "ord_790abc",
  "status": "filled",
  "symbol": "BTC-IRR",
  "side": "sell",
  "type": "market",
  "quantity": "0.2",
  "filled": "0.2",
  "trades": [
    {
      "trade_id": "trade_791",
      "quantity": "0.2",
      "price": "999000000"
    }
  ],
  "created_at": "2025-12-30T12:00:00Z"
}

5.3. لیست سفارشات¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/orders?\
symbol=BTC-IRR&\
status=active&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ موفق:

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "side": "جهت",
    "price": "قیمت",
    "quantity": "حجم",
    "status": "وضعیت"
  },
  "items": [
    {
      "uid": "ord_123",
      "symbol": "BTC-IRR",
      "side": "buy",
      "price": "1000000000",
      "quantity": "0.5",
      "status": "active"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

5.4. لغو سفارش¶

درخواست:

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

پاسخ موفق:

{
  "uid": "ord_123",
  "status": "cancelled",
  "symbol": "BTC-IRR",
  "side": "buy",
  "quantity": "0.5",
  "filled": "0.0"
}

پاسخ ناموفق (سفارش قابل لغو نیست):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "order cannot be cancelled",
      "type": "value_error"
    }
  ]
}

6. Trade API¶

6.1. لیست معاملات¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades?\
symbol=BTC-IRR&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ موفق:

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price": "قیمت",
    "quantity": "حجم",
    "created_at": "تاریخ"
  },
  "items": [
    {
      "uid": "trade_123",
      "symbol": "BTC-IRR",
      "price": "999000000",
      "quantity": "0.2",
      "maker_fee": "199800",
      "taker_fee": "399600",
      "created_at": "2025-12-30T10:05:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

7. Market Data API¶

7.1. دریافت تیکر نماد خاص¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR"

پاسخ موفق:

{
  "symbol": "BTC-IRR",
  "last_price": "1000000000",
  "daily_volume": "50000000000",
  "bid": "999000000",
  "ask": "1001000000",
  "daily_change": "50000000",
  "daily_change_relative": "0.05",
  "high": "1020000000",
  "low": "980000000",
  "timestamp": 1735555200
}

7.2. دریافت عمق بازار¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/depth/BTC-IRR?limit=10"

پاسخ موفق:

{
  "symbol": "BTC-IRR",
  "last_updated": "2025-12-30T10:00:00Z",
  "last_price": "1000000000",
  "bids": [
    {"price": "999000000", "quantity": "0.5"},
    {"price": "998000000", "quantity": "1.2"}
  ],
  "asks": [
    {"price": "1001000000", "quantity": "0.3"},
    {"price": "1002000000", "quantity": "0.7"}
  ]
}

8. Wallet API¶

8.1. لیست کیف پول‌ها¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/accounting/v1/wallets?\
type=spot&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ موفق:

{
  "heads": {
    "uid": "شناسه",
    "currency": "ارز",
    "balance": "موجودی کل",
    "available": "موجودی قابل استفاده"
  },
  "items": [
    {
      "uid": "wallet_456",
      "currency": "IRR",
      "balance": "100000000",
      "hold": "50000000",
      "available": "50000000"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

8.2. واریز وجه¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_456/deposit" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100000000",
    "currency": "IRR",
    "payment_method": "bank_transfer",
    "reference_id": "bank_ref_123456"
  }'

پاسخ موفق:

{
  "uid": "txn_789",
  "type": "deposit",
  "amount": "100000000",
  "status": "completed",
  "created_at": "2025-12-30T13:00:00Z"
}

8.3. برداشت وجه¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_456/withdraw" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50000000",
    "currency": "IRR",
    "destination": "bank",
    "destination_address": "IR123456789012345678901234"
  }'

پاسخ موفق:

{
  "uid": "txn_790",
  "type": "withdrawal",
  "amount": "50000000",
  "status": "pending",
  "created_at": "2025-12-30T13:30:00Z"
}

9. Session API¶

9.1. لیست جلسات معاملاتی¶

درخواست:

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

پاسخ موفق:

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "open_at": "زمان شروع",
    "close_at": "زمان پایان",
    "opening_price": "قیمت شروع"
  },
  "items": [
    {
      "uid": "sess_123",
      "symbol": "BTC-IRR",
      "open_at": "2025-12-30T09:00:00Z",
      "close_at": "2025-12-30T17:00:00Z",
      "opening_price": "1000000000"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

10. User API¶

10.1. دریافت اطلاعات کاربر¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/user/v1/users/user_123" \
  -H "Authorization: Bearer <user_token>"

پاسخ موفق:

{
  "uid": "user_123",
  "username": "john_doe",
  "email": "[email protected]",
  "role": "trader",
  "status": "active",
  "wallet_id": "wallet_456"
}

10.2. ایجاد کاربر (فقط ادمین)¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/user/v1/users" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ali_rezaei",
    "email": "[email protected]",
    "phone": "+989121234567",
    "national_code": "0020030040",
    "role": "trader"
  }'

پاسخ موفق:

{
  "uid": "user_789xyz",
  "username": "ali_rezaei",
  "email": "[email protected]",
  "wallet_id": "wallet_abc123",
  "status": "active"
}

11. کاربردهای پیشرفته¶

11.1. گردش کار کامل یک معامله¶

# مرحله 1: دریافت توکن
export JWT_TOKEN=$(curl -s -X POST "{{ USSO_BASE_URL }}/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"client_abc123","client_secret":"secret_xyz789"}' | jq -r '.access_token')

# مرحله 2: مشاهده موجودی
curl -X GET "{{ API_BASE_URL }}/api/accounting/v1/wallets" \
  -H "Authorization: Bearer $JWT_TOKEN"

# مرحله 3: مشاهده قیمت
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR"

# مرحله 4: ثبت سفارش خرید
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.1"
  }'

# مرحله 5: مشاهده سفارشات
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/orders?status=active" \
  -H "Authorization: Bearer $JWT_TOKEN"

# مرحله 6: مشاهده معاملات
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades" \
  -H "Authorization: Bearer $JWT_TOKEN"

11.2. اسکریپت تست کامل¶

#!/bin/bash

# تنظیمات
BASE_URL="https://api.example.com"
CLIENT_ID="client_abc123"
CLIENT_SECRET="secret_xyz789"

echo "=== تست کامل API ==="

# 1. Login
echo -e "\n1. Login..."
LOGIN_RESPONSE=$(curl -s -X POST "$BASE_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\"}")

JWT_TOKEN=$(echo $LOGIN_RESPONSE | jq -r '.access_token')
echo "Token: ${JWT_TOKEN:0:20}..."

# 2. Health Check
echo -e "\n2. Health Check..."
curl -s "$BASE_URL/api/exchange/v1/health" | jq .

# 3. Get Symbols
echo -e "\n3. Get Symbols..."
curl -s "$BASE_URL/api/exchange/v1/symbols?limit=5" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq '.items[] | {symbol, is_active}'

# 4. Get Ticker
echo -e "\n4. Get Ticker..."
curl -s "$BASE_URL/api/exchange/v1/tickers/BTC-IRR" | jq '{symbol, last_price, daily_change}'

# 5. Get Wallets
echo -e "\n5. Get Wallets..."
curl -s "$BASE_URL/api/accounting/v1/wallets" \
  -H "Authorization: Bearer $JWT_TOKEN" | jq '.items[] | {currency, balance, available}'

echo -e "\n=== تست کامل شد ==="

12. خطاهای رایج و راه‌حل‌ها¶

12.1. خطای 401 - توکن ندارد¶

مشکل:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols"
# پاسخ: {"detail": "Not authenticated"}

راه‌حل:

# ابتدا login کنید و توکن بگیرید
export JWT_TOKEN=$(curl -s -X POST "{{ USSO_BASE_URL }}/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"...","client_secret":"..."}' | jq -r '.access_token')

# سپس با توکن درخواست دهید
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer $JWT_TOKEN"

12.2. خطای 401 - توکن منقضی¶

مشکل:

# پاسخ: {"detail": "Token has expired"}

راه‌حل:

# رفرش توکن
export JWT_TOKEN=$(curl -s -X POST "{{ USSO_BASE_URL }}/auth/refresh" \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}" | jq -r '.access_token')

12.3. خطای 422 - داده ناقص¶

مشکل:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{"symbol":"BTC-IRR","side":"buy"}'
# پاسخ: {"detail": [{"loc": ["body", "type"], "msg": "field required"}]}

راه‌حل:

# اضافه کردن فیلدهای اجباری
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.5"
  }'

13. نکات استفاده از cURL¶

13.1. ذخیره پاسخ در فایل¶

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer $JWT_TOKEN" > response.json

13.2. نمایش فقط هدر¶

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

13.3. نمایش جزئیات درخواست¶

curl -v -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer $JWT_TOKEN"

13.4. استفاده از jq برای پردازش¶

# نمایش فقط قیمت
curl -s "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR" | jq -r '.last_price'

# نمایش لیست نمادها
curl -s "{{ API_BASE_URL }}/api/exchange/v1/symbols" | jq -r '.items[].symbol'

14. چک‌لیست قبل از اجرا¶

[ ] BASE_URL تنظیم شده است
[ ] JWT_TOKEN معتبر است (اگر نیاز به احراز دارد)
[ ] پارامترهای اجباری ارسال شده‌اند
[ ] فرمت JSON صحیح است
[ ] هدرهای لازم اضافه شده‌اند

بعدی: مطالعه index.md برای لینک‌دهی به تمام بخش‌ها

نمونه‌های cURL آماده¶

تنظیمات اولیه¶

1. Health Check¶

درخواست¶

پاسخ موفق¶

2. احراز هویت (Authentication)¶

2.1. Login - دریافت توکن¶

2.2. Refresh - دریافت توکن جدید¶

3. Health Check (API Exchange)¶

درخواست¶

پاسخ موفق¶

4. Symbol API¶

4.1. لیست نمادها¶

4.2. ایجاد نماد (فقط ادمین)¶

5. Order API¶

5.1. ایجاد سفارش لیمیت خرید¶

5.2. ایجاد سفارش مارکت فروش¶

5.3. لیست سفارشات¶

5.4. لغو سفارش¶

6. Trade API¶

6.1. لیست معاملات¶

7. Market Data API¶

7.1. دریافت تیکر نماد خاص¶

7.2. دریافت عمق بازار¶

8. Wallet API¶

8.1. لیست کیف پول‌ها¶

8.2. واریز وجه¶

8.3. برداشت وجه¶

9. Session API¶

9.1. لیست جلسات معاملاتی¶

10. User API¶

10.1. دریافت اطلاعات کاربر¶

10.2. ایجاد کاربر (فقط ادمین)¶

11. کاربردهای پیشرفته¶

11.1. گردش کار کامل یک معامله¶

11.2. اسکریپت تست کامل¶

12. خطاهای رایج و راه‌حل‌ها¶

12.1. خطای 401 - توکن ندارد¶

12.2. خطای 401 - توکن منقضی¶

12.3. خطای 422 - داده ناقص¶

13. نکات استفاده از cURL¶

13.1. ذخیره پاسخ در فایل¶

13.2. نمایش فقط هدر¶

13.3. نمایش جزئیات درخواست¶

13.4. استفاده از jq برای پردازش¶

14. چک‌لیست قبل از اجرا¶