سوالات متداول (FAQ)¶

احراز هویت¶

سوال 1: چگونه توکن بگیرم؟¶

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

پاسخ: از اندپوینت login با client_id و client_secret

سوال 2: توکن منقضی شده، چه کار کنم؟¶

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

پاسخ: از اندپوینت refresh با refresh_token

سوال 3: خطای "Not authenticated" می‌گیرم¶

راه‌حل‌ها: 1. بررسی کنید توکن دریافت کرده‌اید 2. هدر Authorization را ارسال کنید: Authorization: Bearer <token> 3. بررسی کنید توکن منقضی نشده باشد

صفحه‌بندی¶

سوال 4: چگونه صفحه بعد را بگیرم؟¶

# صفحه 1: offset=0, limit=10
# صفحه 2: offset=10, limit=10
# صفحه 3: offset=20, limit=10

offset = (page - 1) * limit

مثال:

# صفحه 3 با 20 آیتم
curl "{{ API_BASE_URL }}/api/exchange/v1/orders?offset=40&limit=20" \
  -H "Authorization: Bearer <token>"

سوال 5: حداکثر limit چقدر است؟¶

پاسخ: 100 آیتم

سفارشات¶

سوال 6: انواع سفارشات کدامند؟¶

Limit: سفارش با قیمت مشخص
Market: سفارش با قیمت بازار
Stop-Limit: سفارش شرطی با قیمت فعال‌سازی و اجرا
Stop-Market: سفارش شرطی با قیمت فعال‌سازی و اجرای مارکت

سوال 7: Time in Force چیست؟¶

GTC: تا لغو نشود باقی می‌ماند
FOK: پر شدن کامل یا لغو
IOC: پر شدن فوری یا لغو بقیه
AON: همه یا هیچ

سوال 8: چگونه سفارش را لغو کنم؟¶

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

سوال 9: سفارش من در چه وضعیتی است؟¶

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

وضعیت‌ها: - new: ایجاد شده - queued: در صف - active: در دفتر سفارشات - partial: بخشی پر شده - filled: کامل پر شده - cancelled: لغو شده - rejected: رد شده - expired: منقضی شده

معاملات¶

سوال 10: چگونه معاملات خود را ببینم؟¶

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades?symbol=BTC-IRR" \
  -H "Authorization: Bearer <token>"

سوال 11: Maker و Taker چیست؟¶

Maker: کسی که نقدینگی اضافه می‌کند (سفارش در دفتر) - کارمزد 0.1%
Taker: کسی که نقدینگی می‌گیرد (سفارش وارد شده) - کارمزد 0.2%

سوال 12: کارمزد معاملات چقدر است؟¶

Maker: 0.1%
Taker: 0.2%

مثال:

معامله: 0.5 BTC @ 100M = 50M IRR
Maker: 50,000 IRR
Taker: 100,000 IRR

بازار¶

سوال 13: چگونه قیمت لحظه‌ای بگیرم؟¶

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

سوال 14: چگونه عمق بازار را ببینم؟¶

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

سوال 15: نمادهای فعال کدامند؟¶

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols?is_active=true" \
  -H "Authorization: Bearer <token>"

کیف پول¶

سوال 16: چگونه موجودی را چک کنم؟¶

curl -X GET "{{ API_BASE_URL }}/api/accounting/v1/wallets" \
  -H "Authorization: Bearer <token>"

سوال 17: چگونه واریز کنم؟¶

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_123/deposit" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "amount": "100000000",
    "currency": "IRR",
    "payment_method": "bank_transfer",
    "reference_id": "ref_123"
  }'

سوال 18: چگونه برداشت کنم؟¶

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_123/withdraw" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "amount": "50000000",
    "currency": "IRR",
    "destination": "bank",
    "destination_address": "IR123..."
  }'

سوال 19: موجودی در حال استفاده (Hold) چیست؟¶

پاسخ: موجودی قفل شده برای سفارشات فعال

مثال:

موجودی کل: 100M
سفارش فعال: 50M
Hold: 50M
Available: 50M

خطاها¶

سوال 20: خطای 401 چیست؟¶

پاسخ: عدم احراز هویت - توکن ندارید - توکن منقضی شده - فرمت اشتباه

سوال 21: خطای 403 چیست؟¶

پاسخ: عدم دسترسی - کاربر به این منبع دسترسی ندارد - سعی در دیدن داده‌های دیگران

سوال 22: خطای 404 چیست؟¶

پاسخ: یافت نشد - شناسه اشتباه - منبع وجود ندارد

سوال 23: خطای 422 چیست؟¶

پاسخ: داده نامعتبر - فیلد اجباری ندارید - مقدار خارج از محدوده - فرمت اشتباه

سوال 24: خطای 429 چیست؟¶

پاسخ: محدودیت نرخ - درخواست‌های زیاد در زمان کم - صبر کنید و دوباره تلاش کنید

گردش کار¶

سوال 25: گردش کار کامل یک معامله؟¶

Login → دریافت توکن
Get Wallets → بررسی موجودی
Get Tickers → بررسی قیمت
Create Order → ثبت سفارش
Get Orders → مشاهده وضعیت
Get Trades → مشاهده معاملات

سوال 26: چگونه استاپ لاس بگذارم؟¶

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "sell",
    "type": "stop-limit",
    "stop_price": "950000000",
    "price": "940000000",
    "quantity": "0.5"
  }'

توسعه¶

سوال 27: چگونه تست کنم؟¶

# اسکریپت تست کامل
#!/bin/bash

export JWT_TOKEN=$(curl -s -X POST "{{ USSO_BASE_URL }}/auth/login" \
  -d '{"client_id":"...","client_secret":"..."}' | jq -r '.access_token')

# تست‌ها
curl -s "{{ API_BASE_URL }}/api/exchange/v1/health" | jq .
curl -s "{{ API_BASE_URL }}/api/exchange/v1/symbols" -H "Authorization: Bearer $JWT_TOKEN" | jq '.items[0]'
curl -s "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR" | jq .

سوال 28: چگونه خطاها را مدیریت کنم؟¶

import requests

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 401:
        print("توکن منقضی شده، رفرش کنید")
    elif e.response.status_code == 422:
        print("خطای اعتبارسنجی:", e.response.json())
except Exception as e:
    print("خطای ناشناخته:", e)

سوال 29: چگونه لاگ بگیرم؟¶

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def make_request(url, headers):
    logger.info(f"Request: {url}")
    response = requests.get(url, headers=headers)
    logger.info(f"Status: {response.status_code}")
    return response

پشتیبانی¶

سوال 30: چگونه با پشتیبانی تماس بگیرم؟¶

ایمیل: [email protected]
ساعات: شنبه تا چهارشنبه، ۹ تا ۱۷
موضوع: مشکل فنی API

سوال 31: چگونه باگ گزارش دهم؟¶

# عنوان: [BUG] توضیح کوتاه

## شرح
توضیح کامل مشکل

## مراحل
1. ...
2. ...

## انتظار
نتیجه مورد انتظار

## واقعیت
نتیجه واقعی

## اطلاعات
- زمان: ...
- نماد: ...
- کاربر: ...

نکات نهایی¶

بهترین روش‌ها¶

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

اشتباهات رایج¶

❌ قرار دادن توکن در کد
❌ استفاده از HTTP
❌ نادیده گرفتن خطاها
❌ درخواست بدون صفحه‌بندی
❌ لاگ کردن توکن

موفق باشید! 🚀