# API اتصال‌ها و استعلام‌ها

مسیرهای کلید بازار، سیاست نرخ و اجرای بررسی ارائه‌دهندگان.

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

## دسترسی مشترک

تمام مسیرهای این مقاله متعلق به پنل مدیریت و نیازمند نقش مالک‌اند. PUT و POST مبدأ همان پنل را نیز بررسی می‌کنند. دریافت تنظیمات مقدار کلید ذخیره‌شده را بازنمی‌گرداند.

خطاهای پایه شامل ۴۰۰ ورودی، ۴۰۱ جلسه، ۴۰۳ دسترسی، ۴۰۹ تعارض یا شرط اجرایی و ۵۰۳ آماده نبودن اتصال است. نتیجه ارائه‌دهنده با خطای ورود به پنل یکسان نیست.

## تنظیم و اجرای استعلام

شناسه‌ها باید UUID باشند. نوع هویت یا موبایل به اجرای هویتی می‌رود؛ bank_owner و حالت قدیمی بدون kind به اجرای بانکی می‌رود. این مسیر اطلاعات هویتی یا بانکی دلخواه برای جایگزینی پرونده نمی‌پذیرد.

| روش و مسیر | قرارداد | حد و رفتار |
| --- | --- | --- |
| GET /api/inquiries | تنظیمات و services | مالک؛ فهرست برای بازدیدکننده عمومی نیست |
| PUT /api/inquiries | {service_key,label,scope,provider_name,base_url,secret?,version} | حداکثر ۱۶٬۰۰۰ بایت؛ ذخیره نسخه‌دار |
| POST /api/inquiries/run | {inquiry_id,service_id,kind?} | حداکثر ۱٬۰۰۰ بایت؛ identity، mobile_owner یا bank_owner |

## کلیدهای بازار

حد ورودی ۱۲٬۰۰۰ بایت است. ارائه‌دهنده و مقصد در کد مشخص‌اند. بررسی Ondo برای خواندن فهرست است؛ ذخیره کلیدها تماس معاملاتی ایجاد نمی‌کند.

| روش و مسیر | ورودی | خروجی |
| --- | --- | --- |
| GET /api/integrations/wallex | — | {hasKey,version,updatedAt} |
| PUT /api/integrations/wallex | {secret,version} | وضعیت بدون مقدار کلید |
| GET /api/integrations/ondo | — | {hasKey,version,updatedAt} |
| PUT /api/integrations/ondo | {secret,version} | وضعیت بدون مقدار کلید |
| POST /api/integrations/ondo/check | {secret} | {assetCount,checkedAt}؛ بدون ذخیره |

## سیاست نرخ تبدیل

mode فقط single یا average و شناسه‌ها فعلاً wallex و nobitex هستند. single یک گزینه و average حداقل دو گزینه غیرتکراری می‌خواهد. بدون اتصال پایگاه داده، وضعیت ۵۰۳ برمی‌گردد.

| روش و مسیر | قرارداد | قاعده |
| --- | --- | --- |
| GET /api/integrations/exchange-rate | {policy,expectedUpdatedAt,configured} | نبود سیاست: single با wallex |
| PUT /api/integrations/exchange-rate | {policy:{mode,sources},expectedUpdatedAt} | تا ۲٬۰۰۰ بایت؛ نسخه باید برابر رکورد فعلی باشد |

## مقصدهای تعریف‌شده در کد

| اتصال | مقصد | کاربرد |
| --- | --- | --- |
| والکس | https://api.wallex.ir/hector/web/v1/markets | نشانی ثابت داده عمومی در تنظیمات |
| Ondo | GET https://api.gm.ondo.finance/v1/assets/all/metadata | بررسی دسترسی کلید به فهرست |
| ثبت‌احوال شبانیک | https://shabanic.ir/api/v1/nid_inquiry | شناسایی اتصال هویتی |
| شاهکار شبانیک | https://shabanic.ir/api/v2/shahkar | شناسایی اتصال مالکیت موبایل |
| مالکیت شبا شبانیک | https://shabanic.ir/api/v2/matchIbanByNationalcode | شناسایی اتصال بانکی |

> دامنه جدول: این‌ها قراردادهای موجود در کد هستند. آمادگی هر سرویس به مجوز، کلید و اتصال اجرایی وابسته است؛ خواندن مستند درخواست واقعی ایجاد نمی‌کند.

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

- planck-admin/app/api/inquiries/route.ts
- planck-admin/app/api/inquiries/run/route.ts
- planck-admin/app/api/integrations/wallex/route.ts
- planck-admin/app/api/integrations/ondo/route.ts
- planck-admin/app/api/integrations/ondo/check/route.ts
- planck-admin/app/api/integrations/exchange-rate/route.ts
- planck-admin/lib/inquiries.ts
- planck-admin/lib/ondo-server.ts
- planck-admin/lib/identity-server.ts