چگونه اعلان‌های تکمیل سفارش‌های API را تنظیم کنیم

کدام رویدادها را باید تکمیل سفارش در نظر گرفت

ابتدا مشخص کنید کدام وضعیت در API به معنای تکمیل واقعی سفارش است. نزد ارائه‌دهندگان مختلف، این می‌تواند سفارش انجام‌شده، تحویل‌شده، لغوشده، ردشده، برگشت‌خورده یا نیمه‌انجام‌شده باشد. خودکارسازی را فقط به واژه «موفق» گره نزنید: سفارش ممکن است چند وضعیت میانی را طی کند و سپس به دلیل محدودیت، بررسی یا لغو متوقف شود.

نباید فقط نتیجه مثبت را پردازش کنید. اگر سرویس اعلان خطا، لغو، برگشت یا انجام جزئی را ارسال می‌کند، آن را هم باید در سیستم داخلی ثبت کنید. در غیر این صورت، سفارش در پنل، CRM یا ربات در حالت انتظار می‌ماند، در حالی که ادامه اجرا دیگر رخ نخواهد داد.

جدول تطبیق وضعیت‌ها را تهیه کنید

وضعیت API را بدون پردازش به رابط کاربری منتقل نکنید. نام‌ها و منطق ارائه‌دهنده ممکن است تغییر کند و یک وضعیت داخلی گاهی چند وضعیت خارجی را در خود جمع می‌کند. مقدار اصلی را جداگانه نگه دارید: برای بررسی خطاها و تطبیق با مستندات به کار می‌آید.

• pending، created، queued — سفارش جدید یا در انتظار پردازش.
• processing، in_progress، running — سفارش در حال اجراست.
• completed، delivered، success — سفارش انجام‌شده.
• partial، partially_completed — سفارش نیمه‌انجام‌شده.
• cancelled، rejected، failed — سفارش لغوشده یا پایان‌یافته با خطا.
• refunded، returned — سفارش نیازمند برگشت یا اصلاح است.
• وضعیت ناشناخته — کارت را به‌طور خودکار تغییر نمی‌دهد و برای بررسی ارسال می‌شود.

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

وب‌هوک، نظرسنجی API یا هر دو روش را انتخاب کنید

وب‌هوک درخواستی از سوی سرویس به URL شما هنگام تغییر وضعیت سفارش است. نظرسنجی API برعکس عمل می‌کند: سیستم شما در بازه‌های زمانی مشخص اطلاعات سفارش را درخواست می‌کند. برای اعلان‌های تکمیل معمولاً وب‌هوک‌ها راحت‌ترند، چون به‌روزرسانی بدون درخواست‌های مداوم به متد بررسی وضعیت می‌رسد.

• وب‌هوک‌ها برای واکنش سریع مناسب‌اند: به‌روزرسانی کارت، شروع مرحله بعد یا ارسال پیام به مسئول.
• نظرسنجی زمانی مناسب است که ارائه‌دهنده از اعلان‌های callback پشتیبانی نمی‌کند یا سرور درخواست‌های خارجی را نمی‌پذیرد.
• روش ترکیبی از وب‌هوک به‌عنوان کانال اصلی استفاده می‌کند و نظرسنجی را برای یافتن سفارش‌های ازدست‌رفته یا معلق به کار می‌برد.

عیب نظرسنجی تأخیر و بار اضافی روی API است. عیب وب‌هوک‌ها این است که باید endpoint را محافظت کنید، موارد تکراری را در نظر بگیرید و به ترتیب تحویل رویدادها اتکا نکنید.

endpoint را برای دریافت رویدادها تنظیم کنید

برای اعلان‌ها به یک آدرس HTTPS عمومی نیاز دارید که از سمت سرویس API قابل دسترسی باشد. در تنظیمات یکپارچه‌سازی معمولاً URL هندلر، رمز امضا و فهرست رویدادها مشخص می‌شود: تغییر وضعیت، تکمیل، لغو، خطا یا انجام جزئی.

یک مسیر جداگانه فقط برای رویدادهای API اختصاص دهید. این‌گونه تنظیم لاگ، محدودکردن دسترسی، تعیین محدودیت درخواست و جدا نگه‌داشتن ترافیک سرویس از فرم‌های سایت ساده‌تر است. از آدرس محیط آزمایشی برای سفارش‌های واقعی استفاده نکنید: پس از به‌روزرسانی محیط، ارائه‌دهنده همچنان رویدادها را به URL ذخیره‌شده ارسال می‌کند.

پیش از راه‌اندازی، متد درخواست و قالب بدنه را طبق مستندات بررسی کنید. بیشتر اوقات POST با JSON است، اما form-data، پارامترهای query یا طرح سریال‌سازی اختصاصی هم دیده می‌شود. خطای تجزیه را باید در لاگ ثبت کنید، وگرنه تشخیص payload نادرست از خرابی برنامه دشوار خواهد بود.

ارتباط بین سفارش و رویداد را حفظ کنید

هنگام ایجاد سفارش از طریق API، شناسه‌ای را که ارائه‌دهنده برگردانده ذخیره کنید. در کنار آن شماره داخلی سفارش، نوع سرویس، وضعیت اصلی، زمان آخرین تغییر و پاسخ اصلی API را به شکل امن نگه دارید. وب‌هوک ورودی را بر اساس ID ارائه‌دهنده تطبیق دهید، نه بر اساس لینک کانال، نام سرویس یا نام مشتری.

اگر API اجازه می‌دهد هنگام ایجاد، شناسه خارجی ارسال شود، شماره سفارش خود را در فیلدی مانند external_id یا client_reference اضافه کنید. این کار جست‌وجو در لاگ‌ها و بررسی موقعیت‌های اختلافی را ساده‌تر می‌کند. اما شماره خارجی را تنها کلید نکنید: برخی ارائه‌دهندگان آن را در هر اعلان برنمی‌گردانند.

برای ID ناشناخته از وب‌هوک، سفارش جدید ایجاد نکنید. رویداد ناشناخته را باید در لاگ ذخیره و جداگانه بررسی کرد. ایجاد خودکار رکورد می‌تواند به داده‌های نادرست یا پردازش درخواست جعلی منجر شود.

از ساختار مشخص payload استفاده کنید

نام دقیق فیلدها به API بستگی دارد. موارد زیر قرارداد یک سرویس مشخص نیست، بلکه نمونه‌ای از رویداد JSON است که می‌توانید هنگام طراحی هندلر داخلی از آن الگو بگیرید. شناسه رویداد، ID سفارش نزد ارائه‌دهنده، وضعیت، زمان تغییر و داده‌های تشخیصی اهمیت دارند.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

تعداد واحدهای انجام‌شده را بدون وضعیت، نشانه تکمیل در نظر نگیرید. سفارش ممکن است نیمه‌انجام‌شده باشد و عدد موجود در payload گرد شده، با تأخیر به‌روزرسانی شده یا اصلاً ارسال نشده باشد. عیب ذخیره کل بدنه رویداد این است که ممکن است داده‌های شخصی یا فیلدهای سرویسی در آن باشد؛ بنابراین چنین رکوردهایی را باید ماسک کرد و مدت نگهداری آن‌ها را محدود کرد.

امضا را بر اساس بدنه اصلی درخواست بررسی کنید

URL باز هندلر ممکن است درخواستی نه از سوی سرویس API دریافت کند. اگر ارائه‌دهنده امضا، رمز یا توکن ارسال می‌کند، آن‌ها را پیش از تغییر سفارش بررسی کنید. طرح رایج HMAC-SHA256 است: ارائه‌دهنده امضا را از بایت‌های بدنه درخواست و رمز مشترک محاسبه می‌کند و نتیجه را در هدر HTTP می‌فرستد.

اصل محاسبه چنین است: بدنه اصلی درخواست، مثلاً بایت‌های JSON بدون تغییر، و رمز یکپارچه‌سازی گرفته می‌شود. سپس HMAC-SHA256 محاسبه می‌شود. اگر نتیجه در قالب هگزادسیمال با مقدار هدر یکسان باشد، بدنه پس از امضا تغییر نکرده و درخواست احتمالاً از سوی طرفی ارسال شده که رمز را می‌داند.

مثال فرضی: HMAC_SHA256(secret, raw_body) = امضای موجود در هدر X-Signature. نام هدر، الگوریتم و قالب نتیجه را فقط باید از مستندات API گرفت. برخی سرویس‌ها برچسب زمانی یا ID رویداد را به رشته امضا اضافه می‌کنند. در این حالت نمی‌توان فقط بدنه JSON را بررسی کرد.

JSON را پیش از بررسی امضا تغییر ندهید

امضا بر اساس بایت‌های اصلی درخواست بررسی می‌شود، نه شیء JSON که برنامه قبلاً تجزیه و دوباره ساخته است. در سریال‌سازی مجدد ممکن است ترتیب فیلدها، فاصله‌ها، escape کاراکترها، خط جدید یا کدگذاری تغییر کند. برای انسان JSON همان می‌ماند، اما مجموعه بایت‌ها تغییر می‌کند و HMAC دیگر مطابقت نخواهد داشت.

برای جلوگیری از این مشکل، ابتدا raw body را به‌صورت bytes یا buffer بگیرید، آن را در حافظه نگه دارید، امضا را محاسبه کنید و فقط پس از بررسی موفق JSON را تجزیه کنید. روی بدنه trim، تبدیل کدگذاری، مرتب‌سازی کلیدها و قالب‌بندی اعمال نکنید. در middleware فریم‌ورک بررسی کنید که JSON پیش از دسترسی به بدنه اصلی به‌طور خودکار تجزیه نشود.

عیب این طرح وابستگی هندلر به ترتیب middleware است. با تنظیم نادرست، برنامه فقط شیء تبدیل‌شده را می‌بیند و اعلان‌های معتبر رد می‌شوند.

نمونه هندلر با بررسی HMAC

در ادامه یک نمونه فرضی به زبان Python آمده است. ترتیب اقدامات را نشان می‌دهد، نه یکپارچه‌سازی آماده را: هدرها، الگوریتم، قالب امضا و فیلدهای payload را باید با مقادیر مستندات ارائه‌دهنده جایگزین کنید.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

برای مقایسه از تابعی استفاده کنید که در نخستین کاراکتر ناهمخوان متوقف نشود. این کار خطر نشت اطلاعات مربوط به امضا از طریق زمان پاسخ را کاهش می‌دهد. رمز را در کد سمت کلاینت قرار ندهید، به URL اضافه نکنید و به‌طور کامل در لاگ‌ها ثبت نکنید.

پردازش رویدادها را idempotent کنید

ارائه‌دهنده ممکن است یک رویداد را چند بار تحویل دهد. دلایل معمول‌اند: سرور شما دیر پاسخ داده، اتصال پس از ذخیره داده قطع شده، endpoint موقتاً خطا برگردانده یا سرویس طبق قواعد خود تحویل مجدد را آغاز کرده است. تکرار به این معنا نیست که API سفارش جدیدی ایجاد کرده است.

Idempotency یعنی رویداد یکسان فقط یک بار نتیجه را تغییر می‌دهد. اگر این قاعده را در نظر نگیرید، نسخه تکراری دوباره پیام به مشتری می‌فرستد، چند وظیفه برای مدیر ایجاد می‌کند، غرامت واریز می‌کند یا عملیات تکراری را اجرا می‌کند.

بهترین کار استفاده از event_id موجود در payload است. آن را در جدول جداگانه یا لاگ رویدادهای پردازش‌شده با محدودیت یکتا ذخیره کنید. اگر ID جداگانه‌ای نیست، کلید را از فیلدهای پایدار بسازید: ID سفارش ارائه‌دهنده، نوع رویداد، وضعیت و زمان تغییر. این روش ضعیف‌تر است: با برچسب‌های زمانی نادقیق، رویدادهای متفاوت ممکن است یکسان به نظر برسند.

رویداد و وضعیت را در یک عملیات ذخیره کنید

بررسی «آیا رویداد پردازش شده است» و ثبت نتیجه باید به‌صورت اتمیک انجام شود. در غیر این صورت، دو درخواست یکسان که همزمان می‌رسند، هر دو نبود رکورد را می‌بینند و اقدام را دو بار اجرا می‌کنند. گزینه عملی، ایندکس یکتا روی event_id و تراکنش پایگاه داده است.

ادامه فرضی هندلر چنین است:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

عیب پاسخ با کد موفق برای سفارش ناشناخته این است که ارائه‌دهنده ممکن است تحویل را تکرار نکند. بنابراین رویدادهای ناشناخته را باید جداگانه پایش و سریع بررسی کرد. اگر مستندات API کد پاسخ دیگری را برای چنین مواردی توصیه می‌کند، از آن پیروی کنید.

نقض ترتیب رویدادها را در نظر بگیرید

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

گذارهای مجاز را تعیین کنید. مثلاً وضعیت میانی نباید وضعیت نهایی را بازنویسی کند و سفارش لغوشده بدون بررسی جداگانه به انجام‌شده تبدیل نمی‌شود. اگر API اصلاح وضعیت نهایی را مجاز می‌داند، دلیل، مقدار اصلی و منبع تغییر را ذخیره کنید.

اگر payload زمان تغییر سفارش را دارد، همان را مقایسه کنید، نه زمان دریافت وب‌هوک را. وقتی API چنین برچسبی ارسال نمی‌کند، از اولویت وضعیت‌ها و تطبیق از طریق متد دریافت سفارش استفاده کنید. عیب اولویت‌ها این است که جای توالی واقعی را نمی‌گیرند، به‌ویژه اگر ارائه‌دهنده برگشت از وضعیت نهایی را مجاز بداند.

تحویل را سریع تأیید کنید و اقدامات را به صف بسپارید

عملیات طولانی را پیش از پاسخ به ارائه‌دهنده اجرا نکنید. بررسی امضا، یافتن سفارش، ثبت رویداد و به‌روزرسانی وضعیت معمولاً سریع تمام می‌شود. ارسال پیام، همگام‌سازی با CRM، تولید گزارش یا درخواست به سیستم‌های شخص ثالث را بهتر است به صف وظایف بسپارید.

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

عیب صف این است که مؤلفه جداگانه‌ای اضافه می‌شود که باید کنترل شود: خطاهای وظایف، تأخیرها و اجراهای مجدد. اما خرابی در اعلان مدیر، دریافت وضعیت‌های سفارش را مسدود نمی‌کند.

اعلان‌ها را برای تیم و مشتری تنظیم کنید

پس از تغییر وضعیت، لازم نیست به همه یکسان اطلاع دهید. برای مدیر معمولاً لغوها، خطاها، انجام جزئی و سفارش‌هایی که مدت طولانی تغییر نمی‌کنند مهم‌اند. برای مشتری اغلب نتیجه روشن کافی است: سفارش انجام شد، لغو شد یا نیاز به توضیح دارد.

• سفارش تکمیل‌شده — به‌روزرسانی در پنل کاربری یا پیام کوتاه به مشتری.
• خطای اجرا — اعلان به مسئول همراه با دلیلی که API ارسال کرده است.
• انجام جزئی — وظیفه بررسی اصلاح، برگشت یا اقدام بعدی.
• وضعیت ناشناخته — ثبت در لاگ و پیام به کارشناس فنی.
• ID سفارش ناشناخته — بررسی جداگانه ارتباط بین سیستم شما و ارائه‌دهنده.

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

لاگ نگه دارید و سفارش‌های ناتمام را تطبیق دهید

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

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

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