Api
وب‌هوک‌ها و رویدادها#
API تجارت در حال حاضر وب‌هوک‌های خروجی پیکربندی‌شدنی ارائه نمی‌کند. هیچ نقطه پایانی برای ثبت URL بازگشتی، هیچ راز امضایی برای مدیریت و هیچ صف تلاش دوباره تحویل برای نقاط مشترکین وجود ندارد.
این صفحه توضیح می‌دهد کدام سطح‌های رویداد واقعاً وجود دارند، تا یک یکپارچه‌سازی بتواند به‌جای انتظار برای وب‌هوکی که هرگز نمی‌رسد یک الگوی بااطمینان انتخاب کند.
آنچه امروز وجود دارد#
| سطح | جهت | چه کسی می‌تواند استفاده کند |
|---|---|---|
| بازگشت‌های فراخوان payment gateway | ارائه‌دهنده به برنامه | فقط ارائه‌دهنده پرداخت |
| کانال‌های broadcast | برنامه به مرورگر | کارمندان واردشده |
| جریان اطلاعیه‌ها | برنامه به مرورگر | کارمندان واردشده |
| polling API v2 | برنامه به کلاینت | اعتبارنامه‌های یکپارچه‌سازی |
بازگشت‌های فراخوان payment gateway#
یکپارچه‌سازی HesabPay نقاط سرور‌به‌سرور برای شروع یک نشست پرداخت و تأیید یک پرداخت را افشا می‌کند. این‌ها توسط برنامه یا ارائه‌دهنده فراخوانی می‌شوند، نه توسط مشترکین شخص ثالث:
| نقطه پایانی | هدف |
|---|---|
POST /api/v1/hesabpay/create-session | شروع یک نشست پرداخت میزبانی‌شده |
POST /api/v1/hesabpay/verify-payment | تأیید یک پرداخت تکمیل‌شده |
ارائه‌دهنده پس از checkout مشتری را به URL موفقیت یا شکست برنامه برمی‌گرداند. آن redirectها روبه‌کاربر هستند، نه وب‌هوک، و نباید به‌عنوان مدرک پرداخت تلقی شوند؛ مرحله تأیید (verify) همان گام معتبر است.
این نقاط پایانی به احراز هویت Sanctum نیاز دارند و بخشی از سطح یکپارچه‌سازی v2 نیستند.
کانال‌های broadcast#
Laravel Reverb رویدادهای لحظه‌ای را برای اطلاعیه‌ها و استریم چت به مرورگر می‌فرستد. کانال‌ها در routes/channels.php به ازای هر کاربر و هر تجارت مجاز می‌شوند.
سیستم‌های خارجی نمی‌توانند با یک توکن یکپارچه‌سازی به این کانال‌ها عضو شوند. آن‌ها برای زنده نگه‌داشتن رابط وب وجود دارند، نه برای تغذیه یک ERP.
جریان اطلاعیه‌ها#
برنامه جریان اطلاعیه‌ها را برای کارمند واردشده به‌صورت دوره‌ای می‌خواند (poll). نقاط پایانی زیر /api/v1/business/notifications قرار دارند و به نشست مرورگر متکی‌اند، بنابراین برای یک یکپارچه‌سازی سرور‌به‌سرور قابل استفاده نیستند.
اگر نیاز دارید بیرون از رابط کاربری به رویدادهای تجارت واکنش نشان دهید، به‌جای آن منابع تجارت را polling کنید.
الگوی پیشنهادی یکپارچه‌سازی#
تا وقتی وب‌هوک‌های خروجی در دسترس شوند، از polling با واترمارک استفاده کنید:
- تازه‌ترین
created_atوidپردازش‌شده خود را برای هر منبع ذخیره کنید. /api/v2/sales?from=<watermark date>را باper_page=100درخواست کنید.- رشته‌هایی را که از قبل دارید دور بریزید، بقیه را پردازش کنید.
- واترمارک را به جلو منتقل کنید.
- با برنامه‌ای که با سهمیه‌تان هم‌خوان است تکرار کنید: برای مثال هر پنج دقیقه برای سفارش‌ها و ساعتی برای فروش‌ها.
| منبع | دوره پیشنهادی | دلیل |
|---|---|---|
| سفارش‌ها | 5 دقیقه | تغییرات وضعیت زمان‌حساس‌اند |
| فروش‌ها | 15–60 دقیقه | گزارش‌گیری و مغایرت‌گیری |
| خریدها | ساعتی | اسناد تأمین‌کننده آهسته تغییر می‌کنند |
| موجودی | 15–60 دقیقه | دسترس‌پذیری برای کانال‌های دیگر |
| محصولات | روزانه | تغییرات کاتالوگ کم‌تعداد است |
هنگام انتخاب دوره، سهمیه را رعایت کنید. یک polling پنج‌دقیقه‌ای 288 درخواست در روز به ازای هر نقطه پایانی است.
طراحی برای یک وب‌هوک آینده#
اگر بعداً وب‌هوک‌های خروجی افزوده شوند، طراحی یکپارچه‌سازی شما از قبل ایمن‌ترین حالت را دارد اگر:
idمنبع را کلید خارجی اصلی خود نگه دارید؛created_atرا ذخیره کنید و به‌عنوان واترمارک به کار ببرید؛- پردازش خود را idempotent بسازید؛
- تحویل تکراری را تحمل کنید؛
- پیش از اعتماد به هر محموله، هدر امضای آینده را تأیید کنید.
Idempotency مهم‌ترین آن‌هاست: یک وب‌هوک ممکن است بیش از یک بار تحویل شود، و صفحه‌ای که polling شده هم همین‌طور.
آنچه ارائه نمی‌شود#
- هیچ نقطه پایانی ثبت مشترک.
- هیچ نوع رویداد یا کاتالوگ محموله.
- هیچ لاگ تحویل یا پخش دوباره.
- هیچ امضای HMAC برای رخدادهای خروجی.
- هیچ فید websocket برای یکپارچه‌سازی‌ها.
برای جبران آن رابط وب را scrape نکنید. آن نشست‌محور است، بدون اطلاع تغییر می‌کند و قرارداد فقط‌خواندنی API را نقض می‌کند.