User API - رفرنس کامل¶

توضیحات کلی¶

این API برای مدیریت کاربران و پروفایل‌های آن‌ها استفاده می‌شود. تمامی اندپوینت‌ها نیاز به احراز هویت با JWT دارند.

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

{
  "uid": "user_123abc",
  "phone": "989123456789",
  "national_code": "1234567890",
  "birth_date": "1390-12-01",
  "is_deleted": false,
  "is_active": true,

  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T10:00:00Z",

  "metadata": {},

  "bank_accounts": [
    {
      "bank": "MELLI",
      "currency": "IRR",
      "account_number": "2002002001",
      "iban": "IR123456789012345678901234",
      "is_primary": true
    }
  ],

  "accepted_contracts": [
    {
      "contract_id": "market_rules_v1",
      "accepted_at": "2025-12-30T10:00:00Z"
    }
  ],

  "wallet_id": "wallet_123abc"
}

فیلدها¶

`id`¶

شناسه منحصر به فرد کاربر (string)

`phone`¶

شماره تلفن با فرمت بین‌المللی (string)

`national_code`¶

کد ملی کاربر (string، ۱۰ رقم)

`is_deleted`¶

وضعیت حذف کاربر (boolean)

`is_active`¶

وضعیت فعال بودن کاربر (boolean)

`created_at`¶

تاریخ ایجاد کاربر (ISO 8601 datetime)

`updated_at`¶

تاریخ آخرین به‌روزرسانی (ISO 8601 datetime)

`metadata`¶

شیء شامل اطلاعات اضافی کاربر (object، می‌تواند خالی باشد)

`bank_accounts`¶

آرایه‌ای از حساب‌های بانکی کاربر (array)

bank: نام بانک (string، مثال: "MELLI")
currency: واحد پولی (string، مثال: "IRR")
account_number: شماره حساب (string)
iban: شماره شبا (string)
is_primary: حساب اصلی (boolean)

`accepted_contracts`¶

آرایه‌ای از قراردادهای پذیرفته شده (array) - contract_id: شناسه قرارداد (string) - accepted_at: تاریخ پذیرش (ISO 8601 datetime)

`wallet_id`¶

شناسه کیف پول کاربر (string)

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

1. List Users (لیست کاربران)¶

GET /api/sso/v1/users

توضیحات: - دریافت لیست کاربران با فیلترهای مختلف

فقط برای نقش‌های ادمین و ساپورت

پارامترهای Query: - offset (integer, optional, default: 0)

limit (integer, optional, default: 10, max: 100)
is_active (boolean, optional): وضعیت فعال بودن
created_at_from (string, optional): ISO 8601
created_at_to (string, optional): ISO 8601
national_code (string, optional): کد ملی

نمونه موفق¶

درخواست:

curl -X GET "${BASE_URL}/api/sso/v1/users?\
is_active=true&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK):

{
  "heads": {...},
  "items": [
    {
      "id": "user_123abc",
      "phone": "989123456789",
      "national_code": "1234567890",
      "wallet_id": "wallet_123def",
      ...
    }, ...
  ],
  "total": 150,
  "offset": 0,
  "limit": 10
}

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

درخواست:

curl -X GET "${BASE_URL}/api/sso/v1/users"

پاسخ (401 Unauthorized):

{
  "error": "unauthorized",
  "detail": "Not authenticated"
}

نمونه ناموفق 2: دسترسی غیرمجاز¶

درخواست:

# کاربر عادی سعی می‌کند لیست بگیرد
curl -X GET "${BASE_URL}/api/sso/v1/users" \
  -H "Authorization: Bearer <user_token>"

پاسخ (403 Forbidden):

{
  "error": "permission_denied",
  "detail": "Access denied"
}

2. Create User (ایجاد کاربر)¶

POST /api/sso/v1/users

توضیحات: - ایجاد کاربر جدید

به طور خودکار کیف پول ایجاد می‌کند
برای بانک‌ها و کلاینت‌های اولیه

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

{
  "phone": "+989123456789",
  "national_code": "1234567890",
  "bank_accounts": [
    {
      "bank": "MELLI",
      "currency": "IRR",
      "account_number": "2002002001",
      "iban": "IR123456789012345678901234",
      "is_primary": true
    }
  ],
  "accepted_contracts": [
    {
      "contract_id": "market_rules_v1",
      "accepted_at": "2025-12-30T10:00:00Z"
    }
  ],
  "metadata": {}
}

فیلدهای اجباری:

phone
national_code
birth_data

نمونه موفق¶

درخواست:

href="#__codelineno-8-1">curl -X POST "${BASE_URL}/api/sso/v1/users" \ -H "Authorization: Bearer <access_token>" \ -H "Content-Type: application/json" \ -d '{ "phone": "989121234567", "national_code": "0020030040", "bank_accounts": [ { "bank": "MELLI", "currency": "IRR", "account_number": "2002002001", "iban": "IR123456789012345678901234", "is_primary": true } ], "accepted_contracts": [ { "contract_id": "market_rules_v1", "accepted_at": "2025-12-30T10:00:00Z" } ], "metadata": {} }'

پاسخ (201 Created):

{
  "id": "user_123abc",
  "phone": "989123456789",
  "national_code": "1234567890",
  "birth_date": "1390-12-01",
  "is_deleted": false,
  "is_active": true,

  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T10:00:00Z",

  "metadata": {},

  "bank_accounts": [
    {
      "bank": "MELLI",
      "currency": "IRR",
      "account_number": "2002002001",
      "iban": "IR123456789012345678901234",
      "is_primary": true
    }
  ],

  "accepted_contracts": [
    {
      "contract_id": "market_rules_v1",
      "accepted_at": "2025-12-30T10:00:00Z"
    }
  ],

  "wallet_id": "wallet_123abc"
}

نمونه ناموفق 1: داده ناقص¶

درخواست:

curl -X POST "{{ BASE_URL }}/api/sso/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "989121234567",
    "birth_date": "1390-10-10"
  }'

پاسخ (422 Unprocessable Entity):

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

نمونه ناموفق 2: شماره تلفن تکراری¶

درخواست:

curl -X POST "$BASE_URL/api/sso/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+989123456789",
    "national_code": "0020030040"
  }'

پاسخ (409 Conflict):

{
  "error": "already_exists",
  "detail": "Phone number already exists"
}

نمونه ناموفق 3: فرمت شماره تلفن نامعتبر¶

درخواست:

curl -X POST "${BASE_URL}/api/sso/v1/users" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "invalid-phone",
    "national_code": "0020030040"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "phone"],
      "msg": "value is not a valid phone number",
      "type": "value_error.phone"
    }
  ]
}

3. Retrieve User (دریافت کاربر)¶

POST /api/sso/v1/users/{uid}

توضیحات:

دریافت اطلاعات کامل یک کاربر خاص

پارامترهای Path:

uid (string, required): شناسه کاربر

دسترسی: کاربر خودش یا admin

نمونه موفق¶

درخواست:

curl -X POST "${BASE_URL}/api/sso/v1/users/user_123abc" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK):

نمونه ناموفق 1: کاربر یافت نشد¶

درخواست:

curl -X POST "${BASE_URL}/api/sso/v1/users/user_999xyz" \
  -H "Authorization: Bearer <user_token>"

پاسخ (404 Not Found):

{
  "error": "not_found",
  "detail": "User not found"
}

4. Add account for User¶

POST /api/sso/v1/users/{id}/accounts

توضیحات:

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

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

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

{
  "bank": "MELLI",
  "currency": "IRR",
  "account_number": "2002002001",
  "iban": "IR123456789012345678901234",
  "is_primary": true
}

5. Add contract for User¶

POST /api/sso/v1/users/{id}/contracts

توضیحات:

به‌روزرسانی قراردادهای پذیرفته شده

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

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

{
  "contract_id": "contract_xyz"
}

ساختار داده کامل User¶

{
  "id": "user_123abc",
  "phone": "989123456789",
  "national_code": "1234567890",
  "birth_date": "1390-10-24",
  "is_deleted": false,
  "is_active": true,
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T12:00:00Z",
  "metadata": {},
  "bank_accounts": [
    {
      "bank": "MELLI",
      "currency": "IRR",
      "account_number": "2002002001",
      "iban": "IR123456789012345678901234",
      "is_primary": true
    },
    {
      "bank": "SEP",
      "currency": "IRR",
      "account_number": "3003003002",
      "iban": "IR567890123456789012345678",
      "is_primary": false
    }
  ],
  "accepted_contracts": [
    {
      "contract_id": "market_rules_v1",
      "accepted_at": "2025-12-30T10:00:00Z"
    },
    {
      "contract_id": "privacy_policy_v2",
      "accepted_at": "2025-12-30T10:15:00Z"
    }
  ],
  "wallet_id": "wallet_123def"
}

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

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

✅ ایجاد کاربر جدید با POST /users
✅ دریافت اطلاعات کاربر با GET /users/{uid}
✅ به‌روزرسانی اطلاعات با PATCH /users/{uid}

نکات امنیتی¶

همیشه از HTTPS استفاده کنید
توکن را محرمانه نگه دارید
داده‌های حساس لاگ نکنید
اعتبارسنجی ورودی‌ها
بررسی دسترسی‌ها

خلاصه¶

اندپوینت	متد	توضیحات	دسترسی
`/users`	GET	لیست کاربران	admin, support
`/users`	POST	ایجاد کاربر	admin
`/users/{id}`	POST	دریافت کاربر	خودش یا admin

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

User API - رفرنس کامل¶

توضیحات کلی¶

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

فیلدها¶

id¶

phone¶

national_code¶

is_deleted¶

is_active¶

created_at¶

updated_at¶

metadata¶

bank_accounts¶

accepted_contracts¶

wallet_id¶

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

1. List Users (لیست کاربران)¶

نمونه موفق¶

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

نمونه ناموفق 2: دسترسی غیرمجاز¶

2. Create User (ایجاد کاربر)¶

نمونه موفق¶

نمونه ناموفق 1: داده ناقص¶

نمونه ناموفق 2: شماره تلفن تکراری¶

نمونه ناموفق 3: فرمت شماره تلفن نامعتبر¶

3. Retrieve User (دریافت کاربر)¶

نمونه موفق¶

نمونه ناموفق 1: کاربر یافت نشد¶

4. Add account for User¶

5. Add contract for User¶

ساختار داده کامل User¶

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

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

نکات امنیتی¶

خلاصه¶

`id`¶

`phone`¶

`national_code`¶

`is_deleted`¶

`is_active`¶

`created_at`¶

`updated_at`¶

`metadata`¶

`bank_accounts`¶

`accepted_contracts`¶

`wallet_id`¶