# API نشست و داشبورد مشتری

روش‌ها، بدنه‌ها و محدودیت‌های مسیرهای خصوصی حساب.

وضعیت: نیازمند پیکربندی | مخاطب: توسعه‌دهندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## نشست و خطاهای مشترک

مسیرهای خصوصی از کوکی HttpOnly نشست مشتری استفاده می‌کنند؛ شناسهٔ کاربر ارسالی در بدنه جای نشست معتبر را نمی‌گیرد. مسیرهای authBody به Origin هم‌مبدأ، Content-Type شامل application/json، تنظیم بودن سرویس و بدنهٔ شیء حداکثر ۱۶٬۰۰۰ بایت نیاز دارند.

خطای اعتبارسنجی معمولاً 400، نیاز به ورود 401، Origin نامعتبر 403، نوع محتوا 415، محدودیت سرویس ورود 429 و نبود اتصال 503 است. خطاهای AuthError با بدنهٔ {error:string} برمی‌گردند. بعضی GETهای خصوصی نیز Sec-Fetch-Site:cross-site را رد می‌کنند.

## ورود و ثبت‌نام

| روش و مسیر | بدنه یا رفتار | پاسخ موفق |
| --- | --- | --- |
| GET /api/auth/session | بدون بدنه؛ بررسی و در صورت امکان تازه‌سازی نشست | {user} یا {user:null}؛ نبود نشست معتبر لزوماً 401 نیست. |
| POST /api/auth/login | identifier یا email، password، remember اختیاری | {user,notice?} و کوکی نشست |
| POST /api/auth/register | firstName، lastName، phone، email، password؛ username و referralCode اختیاری | {phone,step:verify}؛ ثبت‌نام باید به تأیید موبایل برسد. |
| POST /api/auth/otp | action=send\|resend\|verify، phone؛ verify با code؛ intent و remember اختیاری | ارسال: {phone,step:verify}؛ تأیید: نشست یا {step:reset} برای بازیابی |
| POST /api/auth/email | email؛ نیازمند نشست | {message} برای درخواست تأیید ایمیل |
| POST /api/auth/logout | Origin هم‌مبدأ؛ پاک‌کردن نشست حتی در اختلال سرویس بالادست | {ok:true} |

## بازیابی رمز

POST /api/auth/recovery با action=request و email، بازیابی PKCE را آغاز می‌کند؛ پاسخ عمومی وجود حساب را افشا نمی‌کند. بازگشت GET /auth/recovery?code=… پس از بررسی verifier با HTTP303 به صفحهٔ تنظیم رمز یا خطای بازیابی می‌رود.

action=reset و password به کوکی بازیابی معتبر نیاز دارد. رمز جدید ۱۲ تا ۲۵۶ نویسه است؛ پس از موفقیت، دسترسی بازیابی و نشست محلی پاک می‌شوند. نبود یا انقضای دسترسی بازیابی 401 می‌دهد. مقادیر کوکی و توکن در مثال مستندات قرار نمی‌گیرند.

## خواندن و ویرایش داشبورد

GET /api/dashboard وضعیت خصوصی حساب، preferences، banks، notifications، unread_count، alerts، referral_codes، referral_stats، api_keys، wallets، positions، transactions، orders، credits، staking و sessions را می‌خواند. مدل کامل در lib/dashboard.ts تعریف شده است.

POST /api/dashboard بدنهٔ {action,payload} می‌گیرد. پاسخ معمول ویرایش {ok:true} است؛ حساب بانکی قرارداد نتیجهٔ جداگانه دارد. عملیات مالی مانند تغییر موجودی، خرید، برداشت یا ایجاد اعتبار جزو actionهای مجاز نیستند.

| action | payload مجاز |
| --- | --- |
| profile | first_name، last_name، birth_date اختیاری و national_id در صورت مجازبودن |
| preferences | پرچم‌های نمایش و اعلان/تأیید، theme=dark\|light، locale=fa\|en\|ar، currency=TMN\|USDT |
| alert_add | project_id از نوع UUID، direction=above\|below، target_price_rial رشتهٔ صحیح مثبت ۱ تا ۳۰ رقم |
| bank_remove / bank_primary / alert_remove / api_revoke | id از نوع UUID |
| notification_read | id اختیاری؛ نبود آن برای ثبت خوانده‌شدن مجموعه |
| bank_add | iban، account_title و card_number اختیاری، request_key از نوع UUID و consent=true |

## نتیجهٔ ثبت بانکی و تعارض‌ها

موفقیت bank_add به‌صورت {ok:true,id} است. رد قابل تشخیص می‌تواند {ok:false,code,error} باشد: bank_not_matched با HTTP422، bank_registration_unavailable با 503 و دیگر وضعیت‌های فرایند معمولاً با 409 برمی‌گردند.

نسخهٔ قدیمی پایگاه داده، قفل اطلاعات هویتی، تعارض داده یا سقف حساب و هشدار پاسخ مشخص دارند. در خطای شبکه یا نتیجهٔ نامطمئن، نمایش موفقیت پیش‌فرض مجاز نیست.

## دعوت و شارژ

| روش و مسیر | قرارداد | وضعیت |
| --- | --- | --- |
| GET /api/referrals | program، codes، stats، invitees، rewards برای همان حساب | 200؛ نیاز به نشست، اختلال503 |
| POST /api/referrals | {action:create,label}؛ عنوان حداکثر۶۰ نویسه | نتیجهٔ ایجاد کد؛ سقف۲۰ کد و تماس تأییدشده |
| GET /api/deposits | {enabled:false,provider:null,deposits}؛ تا۱۰۰ سابقهٔ اخیر | 200؛ نیاز به نشست |
| POST /api/deposits | {amountToman}؛ رشتهٔ صحیح مثبت حداکثر۱۲ رقم پس از نرمال‌سازی | 400 مبلغ نامعتبر؛ مبلغ معتبر نیز503 چون درگاه متصل نیست. |

## API خصوصی پروندهٔ دارایی

GET /api/tokenization فهرست پرونده‌های صاحب نشست را می‌خواند. POST همان مسیر با action=start نوع دارایی و پذیرش نسخهٔ شرایط را دریافت می‌کند؛ action=save اطلاعات پیش‌نویس، action=submit تأیید و ارسال پرونده و action=accept شمارهٔ نسخهٔ پیشنهاد و پذیرش صریح آن را ثبت می‌کند. به‌جز شروع، شناسهٔ پرونده و آخرین version برای جلوگیری از تغییر هم‌زمان لازم‌اند.

POST /api/tokenization/documents فایل و شناسهٔ جایگاه مدرک را به‌صورت multipart دریافت می‌کند. GET با id و document فقط پس از مجوز، فایل خصوصی را برمی‌گرداند. DELETE به شناسهٔ پرونده، نسخه و شناسهٔ مدرک نیاز دارد و فقط در وضعیت قابل ویرایش مجاز است.

کنترل صاحب داده، وضعیت و نسخه در سرور و پایگاه داده اعمال می‌شود. یادداشت داخلی کارشناسان در پاسخ مشتری قرار نمی‌گیرد. نبود سرویس یا مهاجرت، خطای عدم دسترسی سرویس می‌دهد؛ هیچ مسیر عمومی برای اعلام موفقیت صدور یا افزودن موجودی وجود ندارد.

- [ثبت و پیگیری توکنایزیشن](/docs/tokenization)

## مراجع پیاده‌سازی

- lib/customer-auth.ts
- lib/auth-cookies.ts
- lib/auth-input.ts
- lib/dashboard.ts
- lib/bank-registration.ts
- app/api/auth/session/route.ts
- app/api/auth/login/route.ts
- app/api/auth/register/route.ts
- app/api/auth/otp/route.ts
- app/api/auth/recovery/route.ts
- app/auth/recovery/route.ts
- app/api/dashboard/route.ts
- app/api/referrals/route.ts
- app/api/deposits/route.ts
- app/api/tokenization/route.ts
- app/api/tokenization/documents/route.ts
- lib/tokenization.ts
- supabase/migrations/202609240001_asset_tokenization.sql