وبهوک یا API دوره‌ای برای اتصال ووکامرس؟
اگر قرار است سفارش‌های ووکامرس به انبار، حسابداری یا سامانهٔ دیگری برسند، پرسش فقط «چگونه ارسال کنیم؟» نیست. باید معلوم باشد خبر تغییر از کجا می‌آید، اگر پیام نرسید چه می‌شود و چطور اختلاف داده پیدا می‌شود. وبهوک، واکشی دوره‌ای API و ترکیب آن‌ها پاسخ‌های متفاوتی به این مسئله‌اند.
تفاوت عملی وبهوک و واکشی دوره‌ای چیست؟
وبهوک یعنی ووکامرس پس از یک رویداد، مانند ایجاد یا تغییر سفارش، درخواست HTTP را به نشانی سامانهٔ مقصد می‌فرستد. در واکشی دوره‌ای، سامانهٔ مقصد در زمان‌های تعیین‌شده از REST API ووکامرس دادهٔ سفارش‌ها را می‌خواند. اولی اعلان را نزدیک به زمان تغییر می‌رساند؛ دومی برای کشف تغییرها به برنامهٔ زمان‌بندی و نگهداری نقطهٔ شروع نیاز دارد. هیچ‌کدام به‌تنهایی تضمین نمی‌کند هر رویداد دقیقاً یک بار پردازش شود.
کدام روش برای سناریوی شما مناسب‌تر است؟
- وبهوک: وقتی مقصد باید به تغییر سفارش سریع واکنش نشان دهد و یک نشانی امن و در دسترس برای دریافت درخواست دارد، نقطهٔ شروع خوبی است. مقصد باید بتواند درخواست را اعتبارسنجی، ثبت و پردازش کند.
- واکشی دوره‌ای API: وقتی مقصد نشانی دریافت عمومی ندارد، پردازش دسته‌ای کافی است یا لازم است تغییرهای جاافتاده بررسی شوند، مناسب است. باید صفحه‌بندی، بازهٔ زمانی، محدودیت درخواست و تغییرهای هم‌زمان طراحی شوند.
- ترکیب هر دو: برای اتصال حساس، وبهوک می‌تواند پردازش اولیه را آغاز کند و یک کار دوره‌ای سفارش‌های واجد شرایط را با مقصد تطبیق دهد. این یک الگوی طراحی است؛ تناوب آن به حجم و حساسیت عملیات بستگی دارد.
در وبهوک چه خطاهایی را باید از پیش پوشش داد؟
در تنظیمات ووکامرس برای وبهوک، موضوع رویداد، URL تحویل، وضعیت و secret تعیین می‌شود. درخواست دریافتی را با امضای X-WC-Webhook-Signature و بدنهٔ خام پیام اعتبارسنجی کنید؛ secret نباید در گزارش یا کد عمومی بماند. پاسخ موفق را پس از ثبت مطمئن رویداد بدهید و پردازش طولانی را به صف بسپارید. پاسخ ناموفق یا قطع مقصد باید در گزارش تحویل دیده و پیگیری شود.
مستندات فعلی ووکامرس می‌گوید وبهوک پس از بیش از پنج شکست تحویل پیاپی به‌طور خودکار غیرفعال می‌شود؛ آستانه قابل تنظیم است. بنابراین صرف فعال‌کردن وبهوک برای اطمینان از ادامهٔ همگام‌سازی کافی نیست. وضعیت وبهوک و گزارش‌های webhooks-delivery باید پایش شوند و مسئول روشن برای فعال‌سازی دوباره و جبران رویدادهای ازدست‌رفته وجود داشته باشد.
در واکشی دوره‌ای چه چیزی ممکن است جا بیفتد؟
اگر فقط «آخرین زمان اجرای موفق» را ذخیره کنید، سفارش‌هایی که هم‌زمان با اجرای درخواست تغییر می‌کنند ممکن است در مرز بازه از دست بروند. یک بازهٔ هم‌پوشان، صفحه‌بندی کامل و کلید پایدار سفارش به کاهش این خطر کمک می‌کند. فیلتر زمانی و پارامترهای موجود API را برای نسخهٔ واقعی فروشگاه بررسی کنید؛ زمان آخرین تغییر و وضعیت سفارش را در مقصد با دادهٔ مرجع تطبیق دهید.
تکرار امن و تطبیق؛ بخش مشترک هر دو روش
یک اعلان ممکن است دوباره برسد و یک بازهٔ واکشی هم‌پوشان همان سفارش را دوباره برگرداند. پردازش باید با کلید مشخصی مثل شناسهٔ فروشگاه، شناسهٔ سفارش و نوع عملیات تکرار امن باشد؛ تغییر وضعیت سفارش را نیز از ایجاد سفارش تفکیک کنید. «پاسخ ۲۰۰» فقط تحویل درخواست را نشان می‌دهد، نه الزاماً ثبت درست سند یا تغییر موجودی در مقصد.
برای کنترل، گزارش استثنا بسازید: سفارش موجود در ووکامرس و غایب در مقصد، نسخه یا مبلغ متفاوت، عملیات تکراری و خطای حل‌نشده. بازپخش باید با همان کلید انجام شود و اثر قبلی را بررسی کند. در اتصال حسابداری، قاعدهٔ لغو و مرجوعی ممکن است به سند اصلاحی نیاز داشته باشد؛ در اتصال انبار، مرجع موجودی و زمان رزرو باید جدا تعیین شوند.
مثال فرضی: ارسال سفارش به انبار
فرض کنید پس از تأیید پرداخت، وبهوک تغییر وضعیت سفارش را به گیرنده می‌رساند. گیرنده امضا را بررسی می‌کند، شناسهٔ رویداد و سفارش را ثبت و عملیات را در صف می‌گذارد. اگر انبار در دسترس نباشد، خطا ثبت می‌شود و تلاش کنترل‌شده ادامه می‌یابد. شبانه یک کار دوره‌ای سفارش‌های همان بازه را از API می‌خواند و با رکوردهای انبار مقایسه می‌کند؛ موارد غایب برای بررسی انسانی یا بازپخش ثبت می‌شوند. این مثال معماری است و گزارش پروژهٔ اجراشده نیست.
پیش از سفارش اتصال، این سؤال‌ها را پاسخ دهید
- کدام رویداد آغاز انتقال است: ایجاد سفارش، پرداخت موفق یا تغییر وضعیت؟
- مقصد نشانی HTTPS دریافت وبهوک و امکان نگهداری امن secret دارد؟
- تأخیر قابل قبول چقدر است و در قطع ارتباط چه کسی هشدار را می‌بیند؟
- کلید جلوگیری از پردازش تکراری چیست و تغییر سفارش چگونه اعمال می‌شود؟
- چه بازه‌ای برای تطبیق دوره‌ای لازم است و چه کسی مغایرت را اصلاح می‌کند؟
- در لغو، مرجوعی و خطای پرداخت چه اتفاقی باید در مقصد بیفتد؟
منابع فنی
برای قواعد موجودی، راهنمای اتصال ووکامرس به انبار را بخوانید. اگر مقصد نرم‌افزار مالی است، راهنمای اتصال حسابداری جزئیات سند و مرجوعی را پوشش می‌دهد. برای تعریف خروجی و آزمون، شرح نیاز پروژه را آماده کنید.