# API مدارک، تصویر و اتصال والت

مسیرهای خصوصی فایل و قرارداد چالش امضای آدرس عمومی.

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

## درخواست احراز

| روش و مسیر | ورودی | خروجی و محدودیت |
| --- | --- | --- |
| 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 درخواست امضای پیام است و تراکنش مالی یا تأیید خرج توکن نمی‌سازد.

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

- app/api/identity/route.ts
- app/api/identity/photo/route.ts
- app/api/avatar/route.ts
- app/api/wallet-connect/route.ts
- app/api/wallets/route.ts
- lib/identity.ts
- lib/identity-server.ts
- lib/identity-files.ts
- lib/profile-photo.ts
- supabase/functions/_shared/wallet-link.ts