# اتصال شبانیک برای تطبیق شبا با کد ملی

## استفاده
در پنل مدیریت `http://localhost:3001/?section=inquiries` سرویس «تطبیق شبا با کد ملی» را باز کنید. نام ارائه‌دهنده «شبانیک»، نوع `bank_owner` و نشانی `https://shabanic.ir/api/v2/matchIbanByNationalcode` است. فقط توکن را بدون پیشوند Bearer وارد کنید. حالت آماده به معنی آماده‌بودن اتصال نرم‌افزار است، نه تأیید اعتبار توکن یا مجوز پنل شبانیک.

در بخش احراز هویت کاربران، جزئیات درخواست دارای رضایت ثبت‌شده و حساب بانکی را باز کنید و «استعلام شبا» را بزنید. اگر چند سرویس شبانیک آماده باشند می‌توان سرویس را انتخاب کرد. چهار رقم آخر شبا برای تشخیص حساب و شناسه پیگیری برای نتیجه نمایش داده می‌شود.

## قرارداد ارائه‌دهنده
منبع: مستندات ارسالی کاربر و https://shabanic.ir/p_api_postman
درخواست POST با JSON `iban` و `nationalCode` و `Authorization: Bearer <token>`، به نشانی ثابت HTTPS ارسال می‌شود. شبا با IR و ۲۴ رقم و کد ملی ده‌رقمی (با صفرهای ابتدایی) از رکوردهای ثبت‌شده خوانده می‌شوند. مرورگر اجازه انتخاب داده شخص دیگر، نشانی دلخواه یا ارسال نتیجه «موفق» ندارد.

فقط HTTP 200 به همراه success بولی true، statusCode عددی 200، isMatched بولی و trackId معتبر با پیشوند shabanic نتیجه قطعی است. اگر status وجود داشته باشد باید DONE باشد. false صریح یعنی عدم تطبیق؛ خطای HTTP، عدم دسترسی، پاسخ ناقص یا غیر JSON یعنی خطای استعلام. هیچ خطایی تأیید تلقی نمی‌شود. متن خام پاسخ ذخیره یا بازگردانده نمی‌شود.

## دسترسی و ثبت
مهاجرت: `supabase/migrations/202609090002_shabanic_bank_inquiry.sql`.
اجرای درخواست فقط برای مالک پنل دارای AAL2 است. Supabase pgsql-http 1.6 درخواست را از داخل تابع محدود می‌فرستد؛ کلید در Vault می‌ماند و هرگز به رابط یا سرور وب برگردانده نمی‌شود. SSL فعال و مهلت استاندارد pgsql-http پنج ثانیه است؛ هیچ دسترسی ممتاز برای تغییر تنظیمات شبکه اضافه نشده است. این مسیر هم‌زمان برای اجرای دستی مدیر طراحی شده، نه پردازش انبوه.

رکورد هویت و همان حساب بانکی هنگام استعلام قفل می‌شوند. تغییر موبایل، حذف حساب، درخواست ردشده یا بدون رضایت مانع ارسال است. تطبیق موفق مجدداً ارسال نمی‌شود؛ خطاها حداکثر پنج بار در ۲۴ ساعت و با فاصله یک دقیقه قابل تلاش‌اند. هیچ تلاش خودکاری انجام نمی‌شود. پس از ارسال و قبل از ثبت نهایی، قطع کامل دیتابیس ممکن است نتیجه را نامشخص کند؛ ارائه‌دهنده در مستندات کلید idempotency نداده است.

جدول خصوصی `marketplace_private.inquiry_attempts` دارای RLS است و مدیر اجراکننده، زمان، سرویس، نتیجه، خطای استاندارد و شناسه پیگیری را نگه می‌دارد. عدم تطبیق وضعیت بانک را ردشده می‌کند. تطبیق موفق پیش از تکمیل احراز هویت، بانک را در انتظار نگه می‌دارد؛ فقط با احراز اولیه وضعیت نهایی بانک تأیید می‌شود. اتصال ثبت‌احوال و مالکیت موبایل نیز نصب شده است؛ وضعیت و مستندات جدید در `SHABANIC_IDENTITY_INQUIRIES.md` آمده است.

## آزمون‌ها
۱۰۴ آزمون مارکت‌پلیس و ۲۶ آزمون مدیریت موفق؛ typecheck و build پنل موفق. پوشش شامل دسترسی مالک/AAL2، جلوگیری از نتیجه جعلی، پاسخ مثبت/منفی، خرابی و پاسخ مبهم، عدم ارسال تکراری نتیجه مثبت، سقف تلاش، تغییر نشانی و عدم انتقال کلید قبلی، حذف حساب و رد هویت است. تماس HTTP و Vault در تست محلی شبیه‌سازی می‌شوند. اعتبار واقعی توکن و مجوز شبانیک با آزمون زنده بررسی نشده‌اند و داده هویتی واقعی یا آزمایشی به ارائه‌دهنده ارسال نشده است.

## وضعیت نصب
در Supabase پروژه نصب و تطبیق کد چهار تابع با نسخه آزموده‌شده بررسی شد. سرویس موجود با حفظ کلید به scope صحیح `bank_owner` و ارائه‌دهنده شبانیک اصلاح شد و نسخه ۳ آماده اجراست. تعداد درخواست هویتی و تلاش استعلام هر دو صفر بود. نبود مجوز خواندن کلید برای مشتری، نبود مجوز نتیجه‌نویسی مشتری و RLS جدول تلاش‌ها بررسی شد.