=== افزونه پرداخت جیبیت برای ووکامرس (Jibit for WooCommerce) ===
Contributors: jibit-woocommerce
Tags: woocommerce, payment gateway, jibit, iran, ppg
Requires at least: 5.8
Tested up to: 6.8
Requires PHP: 7.2
WC requires at least: 6.0
WC tested up to: 10.2
Stable tag: 2.0.1
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.en.html

اتصال فروشگاه ووکامرس شما به درگاه پرداخت جیبیت (Jibit PPG).

== Description ==

این افزونه امکان اتصال فروشگاه ووکامرس به درگاه پرداخت جیبیت را با استفاده از API نسخه ۳ فراهم می‌کند.

ویژگی‌ها:
* اتصال به API رسمی Jibit PPG v3 (`https://napi.jibit.ir/ppg/v3`) با مدیریت خودکار توکن دسترسی و تازه‌سازی
* پشتیبانی از چک‌اوت کلاسیک و چک‌اوت بلوکی (Cart & Checkout Blocks) و ذخیره‌سازی سفارش HPOS
* تبدیل خودکار مبلغ از ریال، تومان، هزار ریال و هزار تومان به ریال
* شماره سفارش ووکامرس به‌عنوان شماره تراکنش در پنل جیبیت (قابل جست‌وجو)، و نام خریدار در توضیحات تراکنش
* تایید امن تراکنش: فقط تراکنشی که خود افزونه برای همان سفارش ایجاد کرده پذیرفته می‌شود و وضعیت آن مستقیماً از API جیبیت استعلام می‌شود
* بازآشتی خودکار (Reconciliation) هر ۱۵ دقیقه برای سفارش‌هایی که پرداخت شده‌اند اما خریدار به سایت بازنگشته است، به‌همراه اکشن دستی «بررسی وضعیت پرداخت در جیبیت» در صفحه سفارش
* ثبت خودکار اطلاعات بانکی تراکنش در یادداشت سفارش: شماره کارت ماسک‌شده، نام صاحب کارت، PSP و شماره‌های پیگیری بانکی (RRN / Trace / Reference)
* نرمال‌سازی شماره موبایل خریدار (+98، 0098، ارقام فارسی و عربی)
* دکمه «تست اتصال» در تنظیمات: بررسی کلیدها و مجاز بودن آی‌پی سرور، به‌همراه نمایش آی‌پی سرور برای ثبت در پنل جیبیت
* نمایش شماره تراکنش، شناسه تراکنش و لینک «مشاهده در پنل جیبیت» در صفحه سفارش
* لاگ اشکال‌زدایی اختیاری با لاگر ووکامرس (بدون ثبت کلیدها، توکن‌ها و شماره کارت کامل)
* پیام‌های موفقیت/شکست قابل تنظیم با شورت‌کد

این افزونه فاقد قابلیت استرداد وجه (Refund) از پیشخوان ووکامرس است. برای استرداد وجه به مشتریان، از پنل کاربری جیبیت (dashboard.jibit.ir) اقدام نمایید.

== Installation ==

1. افزونه را در مسیر `wp-content/plugins/` آپلود و فعال کنید (ووکامرس باید نصب و فعال باشد).
2. واحد پول فروشگاه را روی ریال یا تومان قرار دهید.
3. به مسیر ووکامرس > تنظیمات > پرداخت‌ها > جیبیت بروید.
4. کلید API و کلید مخفی دریافتی از پنل جیبیت (dashboard.jibit.ir) را وارد کنید.
5. آی‌پی سرور سایت خود را در پنل جیبیت به‌عنوان آی‌پی مجاز ثبت کنید.
6. درگاه را فعال و تنظیمات را ذخیره کنید.

== Frequently Asked Questions ==

= درگاه در صفحه پرداخت نمایش داده نمی‌شود =
درگاه فقط زمانی نمایش داده می‌شود که کلید API و کلید مخفی وارد شده باشد و واحد پول فروشگاه ریال یا تومان باشد.

= خطای ip.not_trusted دریافت می‌کنم =
آی‌پی سرور سایت شما در پنل جیبیت به‌عنوان آی‌پی مجاز ثبت نشده است. دکمه «تست اتصال» در تنظیمات درگاه آی‌پی سرور شما را نمایش می‌دهد.

= چطور لاگ برای پشتیبانی تهیه کنم؟ =
گزینه «لاگ اشکال‌زدایی» را در تنظیمات فعال کنید، مشکل را تکرار کنید و فایل لاگ با منبع jibit-payment-gateway را از ووکامرس > وضعیت > گزارش‌ها ارسال کنید. پس از رفع مشکل این گزینه را غیرفعال کنید.

= خریدار پرداخت کرده ولی سفارش در انتظار پرداخت مانده است =
افزونه هر ۱۵ دقیقه این سفارش‌ها را بررسی و تکمیل می‌کند. برای بررسی فوری، از منوی «اقدامات سفارش» گزینه «بررسی وضعیت پرداخت در جیبیت» را اجرا کنید.

== Changelog ==

= 2.0.1 =
* عنوان درگاه در صفحه پرداخت به «پرداخت امن جیبیت» تغییر کرد و یادآوری خاموش کردن VPN به توضیحات اضافه شد.
* لوگوی جیبیت در صفحه پرداخت بزرگ‌تر و با کیفیت بالاتر نمایش داده می‌شود.

= 2.0.0 =
* حذف قابلیت «کسر کارمزد از خریدار» و «اطلاع‌رسانی پیامکی» برای نسخه انتشار عمومی.
* امنیت: بازگشت از درگاه فقط با شناسه تراکنشی پذیرفته می‌شود که خود افزونه برای همان سفارش ایجاد کرده است (رفع امکان تکمیل یک سفارش با تراکنش پرداخت‌شده سفارش دیگر).
* ثبت اطلاعات بانکی تراکنش (کارت ماسک‌شده، صاحب کارت، PSP، RRN / Trace / Reference) در یادداشت سفارش.
* درگاه در فروشگاه‌هایی با واحد پول غیر از ریال/تومان یا بدون کلید API نمایش داده نمی‌شود.
* زمان‌بندی بازآشتی خودکار پس از به‌روزرسانی افزونه (بدون نیاز به غیرفعال/فعال‌سازی مجدد) نیز ایجاد می‌شود.
* پشتیبانی از ارقام فارسی/عربی در شماره موبایل خریدار؛ تبدیل دقیق‌تر مبالغ اعشاری.
* دکمه «تست اتصال» (بررسی کلیدها و آی‌پی مجاز، نمایش آی‌پی سرور)، لاگ اشکال‌زدایی اختیاری، و بخش «تراکنش جیبیت» با لینک پنل در صفحه سفارش.
* افزودن لینک تنظیمات در صفحه افزونه‌ها، اعلان نیاز به ووکامرس، و پاک‌سازی تنظیمات و توکن‌ها هنگام حذف افزونه.

= 1.7.3 =
* فیلد description ارسالی به جیبیت اکنون فقط و فقط نام و نام خانوادگی خریدار است، بدون هیچ کاراکتر یا برچسب اضافه.

= 1.7.2 =
* در تلاش اول پرداخت، clientReferenceNumber دقیقاً برابر شماره سفارش ووکامرس است (بدون هیچ پسوندی) تا جست‌وجوی دقیق (exact match) شماره سفارش در پنل جیبیت نتیجه بدهد. فقط در صورت تلاش مجدد پس از پرداخت ناموفق، پسوند شماره تلاش (مثلاً «-2») اضافه می‌شود.

= 1.7.1 =
* شماره تراکنش نمایش‌داده‌شده در پنل جیبیت (clientReferenceNumber) اکنون با شماره سفارش ووکامرس شروع می‌شود (قابل جست‌وجو برای پذیرنده)؛ رشته «wc-» و نام خریدار به فیلد توضیحات (description) منتقل شدند.

= 1.7.0 =
* افزودن گزینه مستقل «ارسال پیامک به خریدار» تا بتوانید بدون خاموش کردن کل سیستم پیامکی، فقط پیامک خریدار را غیرفعال کنید (پیامک مدیر مستقل از این گزینه ارسال می‌شود).
* پیامک خریدار سازمان‌یافته‌تر شد: نام فروشگاه، متن پیام، تشکر و تاریخ/ساعت شمسی هرکدام در خط جداگانه.
* واحد پول در متن پیامک‌ها از IRR به «ریال» تغییر کرد.

= 1.6.1 =
* متن پیامک مدیر بازنویسی شد: شامل نام فروشگاه، مبلغ، شماره تراکنش، شماره سفارش و تاریخ/ساعت به تقویم شمسی.

= 1.6.0 =
* افزودن اطلاع‌رسانی پیامکی پس از پرداخت موفق از طریق سرویس جیبیت پالس (Pulse SMS API)، با تنظیمات مجزا برای فعالسازی، کلید API/Secret، شماره ارسال‌کننده و شماره(های) موبایل مدیر. پیامک به خریدار و مدیر فروشگاه ارسال می‌شود و برای هر سفارش حداکثر یک‌بار (idempotent) ارسال می‌گردد.

= 1.5.1 =
* افزودن نرمال‌سازی شماره موبایل خریدار: فرمت‌های +989xxxxxxxxx، 0098xxxxxxxxxx و 98xxxxxxxxx پیش از ارسال به جیبیت به فرمت محلی 09xxxxxxxxx تبدیل می‌شوند. پیش از این، جیبیت این فرمت‌ها را با خطای payerMobileNumber.is_invalid رد می‌کرد.

= 1.5.0 =
* حذف کامل مکانیزم لغو تراکنش (Reverse Transaction) و استرداد وجه از افزونه. رفتار Reverse مستندسازی‌نشده و غیرقابل‌اتکا بود؛ استرداد اکنون باید مستقیماً از پنل جیبیت انجام شود.
* حذف پشتیبانی 'refunds' از درگاه، بنابراین دکمه استرداد در سفارش‌های ووکامرس دیگر نمایش داده نمی‌شود.

= 1.4.0 =
* حذف کامل استفاده از Refund Purchase API. استرداد از پیشخوان ووکامرس اکنون منحصراً از طریق API لغو تراکنش (Reverse) انجام می‌شود؛ در صورت عدم امکان لغو، به‌جای فراخوانی استرداد وجه واقعی، خطای مربوطه نمایش داده می‌شود.
* استرداد جزئی دیگر پشتیبانی نمی‌شود (چون Reverse فقط لغو کامل را پشتیبانی می‌کند)؛ تلاش برای استرداد مبلغی کمتر از کل سفارش با پیام خطای واضح رد می‌شود.

= 1.3.0 =
* افزودن فیلد قابل ویرایش «عنوان ردیف کارمزد» (پیش‌فرض: «کارمزد خدمات») برای حالت کسر کارمزد از خریدار.
* تغییر عبارت لغو تراکنش در یادداشت‌های سفارش به «لغو تراکنش (Reverse Transaction)» برای تمایز روشن از استرداد وجه (Refund).

= 1.2.2 =
* رفع اشکال race condition که می‌توانست باعث اجرای دوباره تکمیل پرداخت (و ارسال ایمیل تکراری) شود وقتی بازآشتی دوره‌ای و بازگشت واقعی از درگاه هم‌زمان به یک سفارش می‌رسیدند.

= 1.2.1 =
* عنوان و توضیحات درگاه دیگر توسط پذیرنده قابل تغییر نیستند (مقادیر ثابت شدند).
* تغییر نام ردیف کارمزد از «هزینه خدمات» به «کارمزد خدمات».

= 1.2.0 =
* افزودن بازآشتی خودکار سفارش‌های در انتظار پرداخت با API فیلتر تراکنش‌ها (هر ۱۵ دقیقه) به همراه اکشن دستی بررسی وضعیت در صفحه سفارش.
* استفاده از API لغو تراکنش (Reverse) به‌عنوان روش سریع‌تر استرداد کامل، پیش از رجوع به استرداد معمولی.

= 1.1.1 =
* افزودن هدر شناسایی `X-JIBIT-AGENT` به تمامی درخواست‌های ارسالی به API جیبیت.

= 1.1.0 =
* افزودن قابلیت «کسر کارمزد از خریدار» با استفاده از API استعلام کارمزد جیبیت.

= 1.0.0 =
* انتشار اولیه افزونه.
