شماره راهنما46اتصال TCart با حساب عادی فروشنده و تأیید خودکار سفارش
راهنمای تخصصی اتصال حساب پذیرنده هر فروشگاه، ثبت کلیدها، ساخت فاکتور، امضای callback و تطبیق امن سفارش.
این مسیر برای فروشگاه عادی طراحی شده است؛ هر فروشگاه با حساب پذیرنده TCart خودش کار می‌کند. کلید API و Secret callback در تنظیمات همان فروشگاه نگهداری می‌شوند و در پایگاه داده tenant رمزنگاری شده‌اند. فاکتورهای این مسیر در Master DB با tenant/store/order نگاشت می‌شوند. این اتصال با حساب سراسری پلتفرم یا ساختار فروشنده چندفروشنده متفاوت است. مستندات و سطح دسترسی API را در https://tcartt.com/docs و پنل واقعی پذیرنده بررسی کنید؛ جزئیات schema پاسخ باید با نسخه جاری سرویس تطبیق داده شود.
۱. پیش‌نیاز حساب عادی پذیرنده
برای هر فروشگاه حساب پذیرنده مستقل داشته باشید و سطح اشتراکی را انتخاب کنید که API ساخت فاکتور را فعال می‌کند. نام پذیرنده، دامنه، وضعیت حساب و امکان ساخت فاکتور را در پنل رسمی بررسی کنید. اتصال جاری برای حساب عادی است و نباید vendor پلتفرم به فاکتور فروشگاه نسبت داده شود.
۲. دریافت کلید API و Secret callback
کلید API برای درخواست سمت سرور و Secret برای اعتبارسنجی امضای callback استفاده می‌شود. هر دو باید از یک حساب پذیرنده باشند. آن‌ها را در JavaScript، HTML، URL، مخزن عمومی یا پیام پشتیبانی قرار ندهید. در پنل فروشگاه کلیدها را وارد کنید؛ مقدار ذخیره‌شده دوباره نمایش داده نمی‌شود و برای حفظ مقدار قبلی فیلد را خالی بگذارید.
۳. نشانی callback و HTTPS
نشانی callback مربوط به نصب عمومی اوردیکس است و در تنظیمات TCart مطابق راهنمای پنل پذیرنده ثبت می‌شود. نشانی باید HTTPS و از اینترنت قابل دسترس باشد. در هر فاکتور نیز callback_url و return_url ارسال می‌شوند؛ return_url برای بازگشت خریدار است و callback_url مرجع تأیید سمت سرور.
۴. ایجاد سفارش و نگاشت فاکتور
هنگام checkout، سفارش ابتدا در دیتابیس tenant ثبت می‌شود. سپس رکورد نگاشت در Master DB با tenant_id، store_id، order_id و external_order_id ایجاد می‌شود. اگر timeout رخ دهد، به‌جای ارسال درخواست create دوم، همان external_order_id برای reconciliation نگهداری می‌شود.
۵. واحد پول و مبلغ یکتا
مبلغ سفارش در سامانه ریال است و برای API TCart به تومان تبدیل می‌شود. مبلغ ریالی باید مضرب ۱۰ باشد و مبلغ تومانی حداقل پذیرنده را رعایت کند. پاسخ فاکتور باید invoice_id، tracking_code، payment_url، base_price_toman و unique_amount_toman معتبر داشته باشد؛ vendor_id برای حساب عادی صفر و وضعیت اولیه pending است.
۶. هدایت خریدار و پیگیری
نشانی payment_url فقط پس از اعتبارسنجی پاسخ API به خریدار داده می‌شود. خریدار باید unique_amount_toman را دقیق بپردازد. پس از بازگشت، صفحه پیگیری وضعیت را از سرور دریافت می‌کند؛ پارامترهای مرورگر یا نمایش صفحه موفق پرداخت را تأیید نمی‌کنند.
۷. اعتبارسنجی X-Resid-Signature
callback با هدر X-Resid-Signature می‌آید. بدنه خام محدود به ۱ MiB خوانده و JSON آن canonical می‌شود: کلیدهای object به‌صورت بازگشتی مرتب و JSON فشرده با گزینه‌های سازگار تولید می‌شود. HMAC-SHA256 با Secret همان فروشگاه محاسبه و با hash_equals مقایسه می‌شود. هر تغییر در داده canonical یا Secret نادرست امضا را بی‌اعتبار می‌کند.
۸. تطبیق payload و سفارش
event باید payment.confirmed و status باید paid باشد. invoice_id و external_order_id باید به رکورد Master برسند؛ amount_toman باید دقیقاً با unique_amount_toman برابر باشد؛ base_price_toman باید با مبلغ پایه فاکتور و total_rial سفارش تطبیق کند؛ vendor_id باید با نوع فاکتور سازگار باشد.
۹. جلوگیری از ثبت تکراری
رویداد با hash نوع و payload canonical در جدول رویدادها ثبت می‌شود. پردازش تکراری همان رویداد دوباره انجام نمی‌شود. مرجع ledger نیز به invoice_id وابسته است؛ بنابراین callback تکراری نباید سفارش، موجودی یا دفتر مالی را دوباره تغییر دهد.
۱۰. استعلام و پرداخت نامشخص
GET فاکتور برای تازه‌سازی وضعیت خواندنی است. اگر پاسخ paid برسد اما callback معتبر ثبت نشده باشد، وضعیت به manual_review می‌رود؛ GET به‌تنهایی سند پرداخت نیست. پس از timeout یا callback گم‌شده، فاکتور دوم نسازید و همان شناسه را برای تطبیق نگه دارید.
۱۱. پرداخت دیرهنگام و سفارش بسته‌شده
اگر callback معتبر برای سفارش منقضی، لغوشده یا دارای وضعیت متناقض برسد، پرداخت به‌صورت خودکار به سفارش دیگری منتقل نمی‌شود. فاکتور و رویداد در وضعیت بررسی دستی قرار می‌گیرند تا گزارش درگاه، شناسه سفارش و سند مالی با هم تطبیق داده شوند.
۱۲. آزمون نهایی و نگهداری
ابتدا یک سفارش آزمایشی کم‌ارزش بسازید و ساخت فاکتور، هدایت، callback، امضا، تطبیق مبلغ، تغییر وضعیت سفارش و ثبت ledger را بررسی کنید. برای هر فروشگاه کلید مستقل نگه دارید، Secret افشاشده را rotate کنید و لاگ‌ها را از کلید، توکن و اطلاعات پرداخت حساس پاک نگه دارید.
نقشه اجرایی: اتصال TCart با حساب عادی فروشنده و تأیید خودکار سفارش
نمای مفهومی از موضوعات این راهنما؛ عنوان‌ها و داده‌ها صرفاً آموزشی‌اند.
پس از مطالعه این راهنما چه مواردی را بررسی کنم؟
- پیش‌نیازها و محدوده دسترسی مرتبط با این بخش را پیش از شروع بررسی کنید.
- هر مرحله را با داده واقعی و در دامنه مجاز فضای کاری انجام دهید.
- پس از اجرا، وضعیت و نتیجه را در همان ماژول بازبینی کنید.
نکته مهم: این شبیه‌سازی داده واقعی را تغییر نمی‌دهد. نتیجه نهایی به مجوز کاربر، پلن، تنظیمات اتصال و سرویس‌های بیرونی وابسته است.