پلانکدرخواست احراز
| روش و مسیر | ورودی | خروجی و محدودیت |
|---|---|---|
| GET /api/identity | نشست معتبر؛ بدون بدنه | IdentityState شامل request و checks |
| POST /api/identity | {action:start} | آغاز یا دریافت وضعیت درخواست توسط RPC حساب |
| POST /api/identity | {action:save,id,version,fields} | id معتبر، version صحیح مثبت و فیلدهای اعتبارسنجی‌شده |
| POST /api/identity | {action:submit,id,version,consent:true} | ارسال نهایی با کنترل شواهد و نسخه روی سرور |
فیلدها و وضعیت‌ها
fields شامل first_name، last_name، national_id، birth_certificate_number، father_name، address و postal_code است. تاریخ تولد در مسیر پروفایل مدیریت می‌شود و نباید به این بدنهٔ احراز افزوده فرض شود.
خطای RPC احراز، در صورت منع دسترسی 403، اختلال بالادست 503 و خطا یا تعارض دیگر 409 می‌دهد. وضعیت‌های پرونده draft، pending، documents_approved، verified، rejected و superseded و وضعیت‌های استعلام not_connected، pending، passed، failed و error هستند.
بارگذاری و دریافت مدرک
| مسیر | قرارداد |
|---|---|
| POST /api/identity/photo | بدنهٔ خام تصویر؛ هدر x-identity-id، هدر x-document-kind با card یا selfie و Content-Type معتبر؛ Origin و نشست بررسی می‌شوند. |
| GET /api/identity/photo?id=…&kind=card | شناسهٔ درخواست و kind=card|selfie؛ دریافت فایل فقط با مجوز خصوصی. |
| قالب و حجم | JPG، PNG یا WebP تا۵ مگابایت؛ امضای فایل با نوع اعلامی تطبیق داده می‌شود. |
| نتیجه و خطا | POST وضعیت احراز را برمی‌گرداند؛413 برای حجم،415 برای نوع،503 برای اختلال و خطاهای نشست/مجوز مطابق کنترل مشترک. |
تصویر پروفایل
POST /api/avatar تصویر خام با MIME معتبر و حداکثر ۲ مگابایت می‌گیرد و {ok:true,path} برمی‌گرداند. مسیر فایل به حساب و نام تصادفی وابسته است؛ مرورگر مسیر دلخواه برای بازنویسی فایل تعیین نمی‌کند.
GET /api/avatar یا GET /api/avatar?user=… فقط تصویر خود حساب را می‌خواند. شناسهٔ کاربر دیگر یا نبود تصویر 404، نوع نامعتبر 415 و اختلال ذخیره 503 می‌دهد. پاسخ تصویر private,no-store، nosniff و same-origin است.
قرارداد اتصال والت
| روش و مسیر | ورودی / خروجی | دسترسی |
|---|---|---|
| GET /api/wallet-connect | {projectId:string|null}؛ شناسهٔ عمومی معتبر WalletConnect یا null | عمومی |
| POST /api/wallet-connect | {action:challenge,address,chainId,label?}؛ پاسخ {id,message,expires_at} | نشست معتبر، Origin هم‌مبدأ و JSON حداکثر۸۰۰۰ بایت |
| POST /api/wallet-connect | {action:verify,id,signature}؛ نتیجهٔ {wallet} | همان نشست و پیام تک‌استفاده؛ امضای EOA معتبر |
| GET /api/wallets | {wallets:[{network,address,label,verified_at}]} | فقط آدرس‌های حساب واردشده |
اعتبارسنجی و خطاهای والت
address باید آدرس ۲۰بایتی EVM غیرصفر باشد و chainId عدد صحیح مثبت امن است. امضا در مسیر وب با 0x و ۱۳۰ رقم هگز پذیرفته می‌شود. origin از خود درخواست سرور تعیین می‌شود، نه بدنهٔ دلخواه مرورگر.
کدهای شناخته‌شده شامل wallet_rate_limit، wallet_challenge_expired، wallet_already_linked، wallet_limit، invalid_signature، origin_not_allowed و unauthorized هستند. وضعیت‌های 400،401،403،409 و429 مجاز حفظ می‌شوند و خطای نامشخص سرویس به wallet_unavailable و503 تبدیل می‌شود. این API درخواست امضای پیام است و تراکنش مالی یا تأیید خرج توکن نمی‌سازد.