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 پر ایونٹس بھیجتا رہے گا۔

لانچ سے پہلے دستاویزات کے مطابق درخواست کا طریقہ اور باڈی کا فارمیٹ جانچیں۔ زیادہ تر یہ JSON کے ساتھ POST ہوتا ہے، لیکن 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(سیکرٹ, raw_body) = X-Signature ہیڈر سے دستخط۔ ہیڈر کا نام، الگورتھم اور نتیجے کا فارمیٹ صرف API کی دستاویزات سے لیں۔ کچھ سروسز دستخط کی سٹرنگ میں ٹائم اسٹیمپ یا ایونٹ ID شامل کرتی ہیں۔ اس صورت میں صرف JSON باڈی کی جانچ نہیں کی جا سکتی۔

دستخط کی جانچ سے پہلے JSON تبدیل نہ کریں

دستخط کی جانچ درخواست کے اصل بائٹس سے کی جاتی ہے، نہ کہ JSON آبجیکٹ سے جسے ایپلیکیشن پہلے ہی پارس اور دوبارہ بنا چکی ہو۔ دوبارہ سیریلائز کرنے پر فیلڈز کی ترتیب، خالی جگہیں، حروف کی escaping، لائن بریک یا انکوڈنگ بدل سکتی ہے۔ انسان کے لیے 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 کا مطلب ہے کہ ایک جیسا ایونٹ نتیجہ صرف ایک بار بدلتا ہے۔ اگر یہ قاعدہ نظر انداز کیا جائے تو ڈپلیکیٹ کلائنٹ کو دوبارہ پیغام بھیجے گا، مینیجر کے لیے کئی ٹاسک بنائے گا، معاوضہ دے گا یا دوبارہ آپریشن شروع کرے گا۔

بہترین طریقہ یہ ہے کہ payload سے event_id استعمال کریں۔ اسے الگ ٹیبل یا پروسیس شدہ ایونٹس کے لاگ میں منفرد پابندی کے ساتھ محفوظ کریں۔ اگر الگ ID نہ ہو تو مستحکم فیلڈز سے کلید بنائیں: فراہم کنندہ کے آرڈر کی ID، ایونٹ کی قسم، اسٹیٹس اور تبدیلی کا وقت۔ یہ طریقہ کمزور ہے: غلط ٹائم اسٹیمپ کی صورت میں مختلف ایونٹس ایک جیسے لگ سکتے ہیں۔

ایونٹ اور اسٹیٹس کو ایک ہی آپریشن میں محفوظ کریں

"کیا ایونٹ پروسیس ہو چکا ہے" کی جانچ اور نتیجے کا ریکارڈ atomically ہونا چاہیے۔ ورنہ ایک ہی وقت میں آنے والی دو یکساں درخواستیں دونوں ریکارڈ کی عدم موجودگی دیکھیں گی اور عمل دو بار شروع کریں گی۔ عملی حل 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 کے ساتھ ہم آہنگی، رپورٹ بنانا یا فریق ثالث کے نظاموں سے درخواستیں بہتر ہے کہ ٹاسک قطار میں منتقل کر دی جائیں۔

عملی ترتیب یہ ہے: دستخط کی جانچ کریں، ایونٹ اور اسٹیٹس کی تبدیلی atomically محفوظ کریں، کامیاب جواب واپس کریں، پھر ثانوی اقدامات انجام دیں۔ اگر محفوظ کرنے سے پہلے جواب دیا جائے تو خرابی کی صورت میں ڈیٹا ضائع ہو جائے گا۔ اگر طویل نوٹیفکیشن بھیجنے کے بعد جواب دیا جائے تو فراہم کنندہ ڈیلیوری ناکام سمجھ کر ڈپلیکیٹ بھیج سکتا ہے۔

قطار کی کمی یہ ہے کہ ایک الگ جزو شامل ہو جاتا ہے جس کی نگرانی ضروری ہے: ٹاسک کی غلطیاں، تاخیر اور دوبارہ چلنا۔ لیکن مینیجر کے نوٹیفکیشن میں خرابی آرڈرز کے اسٹیٹس وصول کرنے کو روکتی نہیں۔

ٹیم اور کلائنٹ کے لیے نوٹیفکیشنز ترتیب دیں

اسٹیٹس بدلنے کے بعد سب کو یکساں طور پر مطلع کرنے کی ضرورت نہیں۔ مینیجر کے لیے عام طور پر منسوخیاں، غلطیاں، جزوی تکمیل اور وہ آرڈرز اہم ہوتے ہیں جو طویل عرصے تک تبدیل نہ ہوں۔ کلائنٹ کے لیے اکثر واضح نتیجہ کافی ہوتا ہے: آرڈر مکمل ہوا، منسوخ ہوا یا وضاحت درکار ہے۔

• مکمل شدہ آرڈر — ذاتی اکاؤنٹ میں اپ ڈیٹ یا کلائنٹ کو مختصر پیغام۔
• عمل درآمد میں غلطی — ذمہ دار شخص کو API کی بتائی ہوئی وجہ کے ساتھ نوٹیفکیشن۔
• جزوی تکمیل — ایڈجسٹمنٹ، واپسی یا اگلے اقدام کی جانچ کا ٹاسک۔
• نامعلوم اسٹیٹس — لاگ میں اندراج اور تکنیکی ماہر کو پیغام۔
• نامعلوم آرڈر ID — آپ کے نظام اور فراہم کنندہ کے درمیان تعلق کی الگ جانچ۔

ہر تکنیکی منتقلی پر پیغام نہ بھیجیں۔ فیڈ جلد ہی شور بن جائے گی اور اہم مسئلہ نظر انداز رہ جائے گا۔ اندرونی نوٹیفکیشن میں آرڈر نمبر، سروس، موجودہ اسٹیٹس، بیرونی ID اور کارڈ کا لنک شامل ہونا چاہیے۔

لاگ رکھیں اور نامکمل آرڈرز کی جانچ پڑتال کریں

لاگز اس لیے ضروری ہیں کہ یہ سمجھا جا سکے کہ سروس نے ایونٹ بھیجا تھا یا نہیں، کون سی باڈی آئی، دستخط کیوں ناکام ہوئے اور پروسیسنگ کس مرحلے پر رکی۔ وصولی کا وقت، ایونٹ ID، آرڈر ID، ایونٹ کی قسم، دستخط کی جانچ کا نتیجہ، اندرونی اسٹیٹس اور رسپانس کوڈ محفوظ کریں۔ سیکرٹس، ٹوکنز اور ذاتی ڈیٹا ماسک کریں۔

ڈیلیوری کی غلطیاں، غلط دستخط، نامعلوم آرڈرز، غیر تعاون یافتہ اسٹیٹس، ڈپلیکیٹس اور وہ ایونٹس جنہیں حالتوں کی ترتیب کی وجہ سے لاگو نہیں کیا جا سکتا، الگ سے ٹریک کریں۔ ایسے ریکارڈز میں اضافہ API اسکیم کی تبدیلی، میعاد ختم شدہ سیکرٹ، راستے کی خرابی یا ہینڈلر کی منطق میں غلطی کی علامت ہو سکتا ہے۔

وقتاً فوقتاً درمیانی اسٹیٹس والے آرڈرز کی API ڈیٹا حاصل کرنے کے طریقے سے جانچ پڑتال کریں۔ یہ جانچ ویب ہکس کا متبادل نہیں، لیکن چھوٹے ایونٹ، قطار کی خرابی یا ایسی صورت حال دریافت کرنے میں مدد کرتی ہے جب بیرونی اسٹیٹس درست نوٹیفکیشن کے بغیر بدل گیا ہو۔