# نامزد اتصال واقعی سایاپی برای OpenCart 3

این بسته جدا از افزونهٔ سندباکس `sayapay` است؛ کد جدید `sayapay_live` و جدول‌های مستقل دارد. بسته پیش‌فرض خاموش است. آزمون‌های محلی و میزبان‌های ساختگی، نصب واقعی OpenCart/MySQL، موجودی، رویدادهای بومی یا انتقال بانکی را تأیید نمی‌کنند.

## دامنهٔ محدود

- فقط OpenCart بومی `3.0.x.x`، PHP 8.1+ با عدد صحیح ۶۴بیتی، mysqli و cURL/TLS معتبر.
- فقط سفارش یک‌بارهٔ تازه با وضعیت صفر؛ سفارش ویرایش‌شده، بازیابی‌شده یا از قبل پردازش‌شده پشتیبانی نمی‌شود.
- فقط IRR یا IRT با `currency_value` به‌صورت متن اعشاری دقیقاً برابر ۱. مبلغ از SQL تازهٔ سفارش، اقلام و جمع‌های بومی خوانده می‌شود؛ مبلغ مرورگر یا محاسبهٔ شناور ورودی درگاه مبنا نیست.
- کوپن، ووچر، امتیاز، اعتبار، سفارش دوره‌ای و بازاریابی بومی فروشگاه خارج از دامنه‌اند؛ جمع‌ها فقط `sub_total`، `shipping`، `tax` و `total` هستند.
- شبای مقصد فقط همان ذی‌نفع مجاز و متعلق به پذیرندهٔ کلید، با سهم ۱۰۰٪ است؛ دریافت کلید به‌تنهایی تأیید پذیرندگی، دامنه یا تسهیم نیست.
- تأیید پرداخت فقط از رسید منطبق سمت سرور و حالت `settlement_requested` یا `settled` انجام می‌شود؛ واریز نهایی بانکی همچنان تطبیق‌نشده است. استرداد، برداشت خودکار و پرداخت رمزارزی وجود ندارد.

## نصب و تنظیم خصوصی

از فایل‌های داخل `upload/` فقط پس از پشتیبان‌گیری نصب کنید. نصب از مدیریت فروشگاه، دو جدول `sayapay_live_payment` و `sayapay_live_lock` را با پیشوند واقعی فروشگاه ایجاد می‌کند و نمایش روش را خاموش نگه می‌دارد. جداول بومی سفارش، اقلام، جمع‌ها، تاریخچه، موجودی و گزینه‌های محصول و دو جدول افزونه باید InnoDB و دارای کلید اصلی بومی تک‌ستونی باشند. افزونه هیچ جدول بومی را تبدیل نمی‌کند.

کلید `sp_live` را فقط با ثابت `SAYAPAY_LIVE_MERCHANT_KEY` در `config.php` خصوصی بخش فروشگاه قرار دهید؛ نه داخل فرم مدیریت، فایل عمومی، گیت یا چت. رمز وب‌سرویس آسان‌پرداخت لازم نیست. نشانی API ثابت و HTTPS است و قابل تغییر توسط فرم یا خریدار نیست. ثابت پذیرش `SAYAPAY_LIVE_OPENCART_ACCEPTED` برای بررسی نمایش درگاه در تنظیم خصوصی فروشگاه و برای اجازهٔ ذخیرهٔ فعال‌سازی در تنظیم خصوصی بخش مدیریت لازم است؛ کلید API در تنظیم مدیریت لازم نیست.

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

ثابت خصوصی `SAYAPAY_LIVE_OPENCART_ACCEPTED` و تنظیم نمایش روش، هر دو تا پایان پذیرش مستقل خاموش بمانند. پذیرش شامل نصب/حذف/ارتقا، MariaDB/MySQL و رقابت قفل، نشست مهمان و بازگشت، واحد پول، موجودی، ضدتقلب و رویدادهای محصول و آزمون بانکی کم‌مبلغ با مجوز است. آزمون محدود هسته و SQL زیر، پذیرش کامل یک فروشگاه عمومی نیست.

## گزارش محلی فقط‌خواندنی مدیریت

صفحهٔ تنظیم افزونه، فقط برای درخواست GET همان صفحه با توکن معتبر و مجوز مشاهدهٔ مدیریت، جدول تشخیص پیش‌نیازها را نشان می‌دهد. این بررسی فقط قالب نسخه، PHP و افزونه‌های محلی، درایور و قالب پیشوند، واحد پول تنظیم‌شدهٔ مدیریت و عضویت وضعیت انتخابی در گروه‌های پردازش/تکمیل را می‌سنجد. نمایش روش و ثابت پذیرش بخش مدیریت جداگانه با وضعیت روشن/خاموش گزارش می‌شوند؛ نتیجهٔ کلی «آمادهٔ پرداخت» وجود ندارد.

این گزارش هیچ SQL، شبکه، تغییر تنظیم، خواندن کلید خصوصی فروشگاه یا اجرای سفارش و رویداد بومی ندارد و هیچ مقدار خصوصی را نمایش نمی‌دهد. دادهٔ ناقص یا خطای خواندن تنظیم، «نامشخص» می‌شود. واحد پول مدیریت اثبات `currency_value=1` سفارش نیست؛ قالب پیشوند و گروه وضعیت هم وجود یا سلامت جدول بومی را ثابت نمی‌کنند.

کلید و پذیرش بخش فروشگاه، ساختار و InnoDB/کلیدهای جدول‌ها و ثبت قطعی ذخیره‌سازی، آزمون نصب و رقابت/رویدادهای بومی، تأیید پذیرندگی و دامنه و پرداخت مجاز و تطبیق واریز بانکی همواره «بررسی نشده» باقی می‌مانند. قبول‌شدن تمام بررسی‌های محلی یا روشن‌بودن یک تنظیم، این گیت‌ها را باز نمی‌کند و پرداخت را فعال نمی‌کند.

## مرز عملیات و بازیابی

اتصال مجزای تازهٔ mysqli فقط برای این افزونه ساخته می‌شود؛ تنها روی همان اتصال `autocommit=1` تنظیم می‌شود. وضعیت، مبلغ و اقلام از همین اتصال تازه خوانده می‌شوند. پیش از هر درخواست بیرونی، عکس ثابت سفارش و سپس نشان «تلاش انجام شد» با ثبت مستقل و خواندن دوباره ذخیره می‌شوند؛ تراکنش بازِ قابل بازگشت، درخواست مالی را در بر نمی‌گیرد.

پس از نتیجهٔ نامعلوم POST، حتی با خطای HTTP، POST تکرار نمی‌شود. اگر شناسهٔ پاسخ هم ذخیره نشده باشد، بررسی دستی لازم است؛ سفارش تازه نسازید. با شناسهٔ ذخیره‌شده، حداکثر ۱۲ GET فقط‌خواندنی از مسیرهای بازگشت یا بازیابی هسته مجاز است. صف/cron خودکار در این نسخه نصب نمی‌شود؛ اجرای `recover()` فقط برای اتصال داخلی مورد اعتماد در نظر گرفته شده و مسیر عمومی بدون احراز ندارد.

قبل از قفل بازگشت، قابلیت خصوصی مهمان بررسی می‌شود. قفل مالک اختصاصی دارد و با گذشت زمان، خطا یا حذف افزونه دزدیده یا پاک نمی‌شود. شکست پیش‌بینی‌نشدهٔ ذخیره یا رویداد بومی، قفل را حفظ می‌کند. تکمیل با نشان پایدار `completion_started` فقط یک بار آغاز می‌شود؛ این تضمین «شروع نکردن دوباره پس از شکست نامعلوم» است، نه ادعای اجرای دقیقاً یک‌بارهٔ همهٔ رویدادهای افزونه‌های دیگر.

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

خاموش‌کردن نمایش یا ثابت پذیرش، POST تازه و انتقال تازه به صفحهٔ بانک را می‌بندد، اما بررسی GET و تکمیل یک پرداخت قبلاً صادرشده را به‌تنهایی متوقف نمی‌کند. حذف افزونه عمداً جدول‌ها، رسیدها و قفل‌های مالی را حذف نمی‌کند؛ از این اطلاعات با دسترسی محدود نسخهٔ پشتیبان بگیرید.

## منبع بررسی API بومی

### نتیجهٔ محدود هسته و دیتابیس واقعی — ۲۳ اکتبر ۲۰۲۶

۱۵۱ بررسی با هستهٔ رسمی و ثابت OpenCart **3.0.5.1**، MariaDB **11.4.8** و PHP
**8.4.26** در محیط محلی جدا موفق شد. فایل‌های رسمی پیش از اجرا و هسته پس از اجرا
با آرشیو دارای SHA256 ثابت تطبیق داده شدند. نصب SQL اصلی، نصب و حذف کنترلر
مدیریت در CLI، ایجاد سفارش و اجرای مدل اصلی `addOrderHistory`، موجودی کالا و
گزینه، رویدادهای اصلی با ناظر آزمایشی، ماژول ضدتقلب IP بومی، قفل بین دو پردازش
و ثبت مستقل تلاش پرداخت بررسی شدند. بازگشت تکراری، رسید نامنطبق و تغییر اقلام
هنگام انتظار شبکه، نباید تکمیل یا کاهش موجودی تازه ایجاد کنند.

اسکیمای نصب رسمی این نسخه برای جدول‌های موردنیاز MyISAM دارد؛ افزونه آن را
درست رد کرد. فقط برای آزمون مثبت، ۹ جدولِ دیتابیس دورریختنی آزمایش صریحاً به
InnoDB تبدیل شدند. **افزونه هیچ جدول فروشگاه را خودکار تبدیل نمی‌کند** و این
آزمون مجوز تبدیل جدول یک فروشگاه واقعی نیست.

پاسخ‌های پرداخت در این آزمون تزریقی و ساختگی بودند؛ هیچ درخواست به سایاپی یا
بانک ارسال نشد. این نتیجهٔ CLI به‌تنهایی آزمون HTTP، نشست مهمان، TLS عمومی،
ایمیل یا ارتقای یک فروشگاه موجود نیست. نتیجهٔ مستقل مرورگر در ادامه آمده است؛
هیچ‌کدام به نسخه‌های دیگر OpenCart/PHP/دیتابیس تعمیم داده نمی‌شوند و روش پرداخت
همچنان پیش‌فرض خاموش است.

### آزمون محدود HTTP و مرورگر بومی — ۲۳ اکتبر ۲۰۲۶

۱۳۸ بررسی در ۱۴ سناریو با همان نسخه‌های ثابت، از مسیرهای واقعی هسته اجرا شد:
ورود مدیریت، نصب کنترلر افزونه، ذخیرهٔ فرم تنظیمات، سبد و خرید مهمان، نشست و
nonce، بازگشت مشتری و تکمیل از رسید منطبق. سه نشست مستقل در عرض‌های ۳۲۰، ۳۹۰
و ۱۴۴۰ پیکسل بررسی شدند. GET و nonce نامعتبر واقعاً پاسخ ۴۰۳ دارند؛ بازگشت
تکراری نباید تاریخچه یا موجودی را دوباره تغییر دهد و توقف صدور، پرداخت تازه
را می‌بندد ولی رسید معتبر قبلی را حذف نمی‌کند.

این محیط از کپی دورریختنی هسته، ۹ تبدیل InnoDB صرفاً آزمایشگاهی، HTTPS محلی
با گواهی self-signed و پاسخ پرداخت ساختگی استفاده می‌کند. فقط تابع انتقال
شبکه در کپی کنترلر جایگزین شده؛ تبلیغات بیرونی مدیریت و رویدادهای ایمیل نیز
صریحاً مهار شده‌اند. هیچ گواهی در اعتماد سیستم‌عامل نصب نشده است. هر تلاش
انتقال پیش از اعتبارسنجی ثبت می‌شود؛ کنترل منفی مستقل، آشکارشدن خطای پنهان را
می‌سنجد و نتیجهٔ نهایی پنج تلاش معتبر و صفر خطای پنهان بود.

این آزمون، نصب ZIP از uploader بومی، TLS عمومی فروشگاه، ایمیل و افزونه‌های
ثالث، ارتقا یا پرداخت واقعی بانک را تأیید نمی‌کند. پذیرش همان میزبان و یک
پرداخت بانکی محدود با مجوز، پیش از فعال‌سازی همچنان لازم است.

رفتار API و SQL از شاخهٔ رسمی OpenCart 3 بررسی شده است؛ این بررسی به معنی پذیرش نصب اختصاصی شما نیست:

- https://github.com/opencart/opencart/blob/3.0.x.x/upload/catalog/model/checkout/order.php
- https://github.com/opencart/opencart/blob/3.0.x.x/upload/system/library/db.php
- https://github.com/opencart/opencart/blob/3.0.x.x/upload/system/library/db/mysqli.php