API کے ذریعے آرڈر چیک کرتے وقت "processing" اسٹیٹس کو ہینڈل کرنا

API جواب میں processing کا کیا مطلب ہے

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

Processing کامیاب تکمیل کی تصدیق نہیں کرتا اور نہ ہی اس کا مطلب خرابی ہے۔ اس کے بعد آرڈر completed، partial، canceled یا failed میں جا سکتا ہے۔ جب تک فراہم کنندہ درمیانی اسٹیٹس واپس کر رہا ہے، اسی لنک اور اسی حجم کے لیے دوبارہ درخواست نہ بنائیں۔

processing اسٹیٹس کے ساتھ HTTP 200 کا مطلب API کا کامیاب جواب ہے، آرڈر کی کامیاب تکمیل نہیں۔ ان واقعات کو الگ سے محفوظ اور ہینڈل کرنا ضروری ہے۔

آرڈر چیک کرنے کے لیے کون سا ڈیٹا درکار ہے

polling کے لیے بیرونی آرڈر ID درکار ہے جو فراہم کنندہ نے بناتے وقت واپس کیا۔ اسے اندرونی ID، اصل حجم، سروس کے پیرامیٹرز، لنک، بنانے کے وقت اور اصل API جواب کے ساتھ محفوظ کریں۔ چینل کے نام، لنک یا حجم سے آرڈر تلاش کرنا قابلِ اعتماد نہیں: یہ اقدار کئی درخواستوں میں یکساں ہو سکتی ہیں۔

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

صرف موجودہ اسٹیٹس محفوظ کرنے کی کمی یہ ہے کہ تنازعے کی صورت میں یہ بحال نہیں کیا جا سکتا کہ آرڈر کب processing میں گیا، پیش رفت ہوئی یا نہیں، اور پہلے کون سے جوابات آئے تھے۔

curl کے ذریعے اسٹیٹس درخواست کی مثال

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

ایک آرڈر کے لیے GET درخواست

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

جواب کی مثال:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "وقت_کی_قدر"

}

completed_quantity اور remains فیلڈز صرف ساخت کی مثال کے طور پر دیے گئے ہیں۔ فراہم کنندہ progress، start_count، balance یا دیگر نام استعمال کر سکتا ہے۔ GET طریقے کی کمی یہ ہے کہ کچھ API اسٹیٹس کی جانچ صرف POST کے ذریعے قبول کرتے ہیں۔

POST درخواست اور بیچ جانچ کی مثال

ایک آرڈر کے اسٹیٹس کے لیے POST درخواست

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

API کلید کو URL سٹرنگ میں نہ بھیجیں۔ درخواست کے ایڈریس پروکسی لاگز، اینالیٹکس سسٹمز، براؤزر ہسٹری اور تکنیکی لاگز میں آ جاتے ہیں۔ POST کی کمی یہ ہے کہ اسے ایڈریس بار کے ذریعے دستی طور پر جانچنا مشکل ہے، لیکن یہ وجہ نہیں کہ سیکرٹ کو URL میں منتقل کیا جائے۔

فعال آرڈرز کی بیچ درخواست

اگر API بیچ جانچ کی سہولت دیتا ہے، تو کئی ID ایک ہی درخواست میں بھیجیں:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

جواب کو اندرونی آرڈر سے بیرونی ID کی بنیاد پر ملائیں، نہ کہ ایرے میں عنصر کی پوزیشن کی بنیاد پر۔ بیچ جانچ کی کمی: فراہم کنندہ تمام آرڈرز واپس نہ کرے، فہرست کا سائز محدود کرے یا صرف ایک ID کے لیے خرابی بتائے۔

processing کے لیے polling کیسے مقرر کریں

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

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

• آرڈر بنانے کے بعد فوراً کئی بار اسٹیٹس چیک نہ کریں: سروس کو قطار میں لگنے میں وقت درکار ہو سکتا ہے۔
• بار بار processing آنے پر درخواستوں کے درمیان وقفہ بڑھائیں، مستقل فریکوئنسی نہ رکھیں۔
• ٹاسک شروع کرنے کے وقت میں تھوڑا سا بے ترتیب فرق شامل کریں تاکہ آرڈرز بیک وقت API کو پول نہ کریں۔
• اگر فراہم کنندہ Retry-After یا ایسی ہی کوئی سفارش بھیجے، تو اسے ترجیحی بنیاد پر استعمال کریں۔
• webhooks والے آرڈرز کے لیے کنٹرول polling رکھیں: اطلاع نہ پہنچ سکتی ہے۔

کم polling کی کمی یہ ہے کہ انٹرفیس حقیقی تکمیل کے بعد پرانا اسٹیٹس دکھا سکتا ہے۔ بہت زیادہ polling کی کمی یہ ہے کہ API حدود سے ٹکرانے، 429 وصول کرنے اور اضافی بوجھ پیدا کرنے کا خطرہ ہے۔

processing کی نگرانی کے لیے کون سے اوقات محفوظ کرنے ہیں

عام تکمیل اور پھنس جانے میں فرق کرنے کے لیے صرف موجودہ اسٹیٹس کافی نہیں۔ ہر فعال آرڈر کے لیے بنانے کا وقت، پہلی بار processing ملنے کا وقت، آخری کامیاب API جواب، بیرونی اسٹیٹس کی آخری تبدیلی اور پیش رفت کی آخری تبدیلی محفوظ کریں۔

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

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

اگر processing تبدیل نہ ہو تو کیا کریں

طویل processing خرابی کا ثبوت نہیں۔ پہلے چیک کریں کہ کامیاب API جوابات آئے یا نہیں، completed_quantity یا remains بدلے یا نہیں، webhooks آئے یا نہیں اور سروس کے قواعد بدلے یا نہیں۔ نظر آنے والی پیش رفت کی کمی پلیٹ فارم کے اعدادوشمار کی تاخیر یا اس وجہ سے ہو سکتی ہے کہ فراہم کنندہ پیش رفت صرف آخر میں اپڈیٹ کرتا ہے۔

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

• آخری تصدیق شدہ جواب کا وقت اور پورا API جواب ریکارڈ کریں۔
• چیک کریں کہ پچھلی polling کے بعد پیش رفت بدلی یا نہیں۔
• اندرونی حد پوری ہونے کے بعد خودکار درخواستوں کی فریکوئنسی کم کریں۔
• سپورٹ کو بیرونی ID، لنک، سروس کے پیرامیٹرز، اسٹیٹس کی تاریخ اور تکنیکی خرابیاں فراہم کریں۔
• فراہم کنندہ کے جواب یا واضح حتمی اسٹیٹس سے پہلے بقایا دوبارہ شروع نہ کریں۔

دستی جانچ کی کمی یہ ہے کہ آرڈر کو سپورٹ کی توجہ درکار ہوتی ہے۔ لیکن خودکار منسوخی یا ڈپلیکیٹ زیادہ خطرناک ہے: فراہم کنندہ کے ہاں تکمیل جاری رہ سکتی ہے۔

درخواست کی خرابی اور آرڈر کے اسٹیٹس میں فرق کیسے کریں

نیٹ ورک کی خرابی، ٹائم آؤٹ، HTTP 429 اور 5xx جواب خود آرڈر کی حالت نہیں بتاتے۔ یہ صرف یہ ظاہر کرتے ہیں کہ نیا مستند اسٹیٹس حاصل نہیں ہو سکا۔ ایسی صورت میں آخری تصدیق شدہ اسٹیٹس برقرار رکھیں، تکنیکی خرابی ریکارڈ کریں اور نئی جانچ کا منصوبہ بنائیں۔

429 کی صورت میں Retry-After کا خیال رکھیں، اگر ہیڈر بھیجا گیا ہو۔ عارضی نیٹ ورک خرابیوں اور 5xx کی صورت میں کوششوں کے درمیان وقفہ بڑھائیں۔ اجازت، دستخط یا رسائی حقوق کی خرابی کی صورت میں بار بار retry نہ کریں: کلید، ٹوکن کی مدت، IP پابندیاں اور رسائی کی ترتیبات چیک کرنا ضروری ہے۔

اگر API نے HTTP 200 واپس کیا لیکن JSON پارس نہیں ہو رہا یا جواب میں order_id اور status موجود نہیں، تو جواب کا پورا باڈی محفوظ کریں اور جانچ کو غلط قرار دیں۔ اسٹیٹس کی عدم موجودگی کو completed، canceled یا processing سے نہ بدلیں۔

خودکار دوبارہ درخواستیں کب بند کریں

Polling لامحدود نہیں ہونی چاہیے۔ عارضی خرابیوں کے لیے تکنیکی دوبارہ کوششوں کی تعداد محدود کریں اور آرڈر کے processing میں رہنے کی کل مدت کو الگ سے کنٹرول کریں۔ retries کی حد ختم ہونے کے بعد جانچ کے ٹاسک کو تجزیہ کی قطار میں منتقل کریں، نہ کہ ہر منٹ بغیر نتیجہ کے نئی درخواستیں بنائیں۔

اسٹیٹس کی دوبارہ درخواست عام طور پر محفوظ ہے اگر طریقہ صرف ڈیٹا پڑھتا ہے۔ بنانے، منسوخ کرنے، ٹاپ اپ، دوبارہ شروع کرنے اور واپسی کے طریقے ٹائم آؤٹ کے بعد مشینی طور پر دہرائے نہیں جا سکتے۔ idempotent کلید یا فراہم کنندہ کی واضح تصدیق کے بغیر ایسی تکرار آرڈر کو دو بار تبدیل کر سکتی ہے۔

retries کی حد کی کمی یہ ہے کہ کچھ اپڈیٹس دستی کام بن جائیں گے۔ لامحدود retries اس سے بدتر ہیں: وہ خرابی کو چھپاتے ہیں، حدود خرچ کرتے ہیں اور لاگز کے تجزیے کو پیچیدہ بناتے ہیں۔

processing کے بعد حتمی اسٹیٹس کیسے قبول کریں

دیر سے آنے والی polling کے جواب یا پرانے webhook کی وجہ سے completed سے processing میں واپسی کی اجازت نہ دیں۔ ہر اپڈیٹ پر فراہم کنندہ کے واقعے کا وقت، ورژن نمبر اگر موجود ہو، اور موجودہ اندرونی حالت کا موازنہ کریں۔

• new اور pending processing، canceled یا failed میں جا سکتے ہیں۔
• processing completed، partial، canceled یا failed میں جا سکتا ہے۔
• partial کو خودکار طور پر completed نہیں سمجھنا چاہیے۔
• completed، canceled اور failed عام طور پر حتمی سمجھے جاتے ہیں اور خودکار واپسی کو روکتے ہیں۔
• نامعلوم اسٹیٹس یا ناجائز منتقلی کے لیے الگ جانچ درکار ہے۔

سخت منتقلی جدول کی بھی کمی ہے: فراہم کنندہ کوئی درست نئی حالت شامل کر سکتا ہے۔ اس لیے اصل اسٹیٹس محفوظ رکھیں اور اسے اندرونی درجہ بندی سے نہ مٹائیں۔

partial اور آرڈر کے بقایا کو کیسے ہینڈل کریں

Partial کا مطلب ہے کہ اصل حجم کا صرف ایک حصہ تصدیق شدہ ہے۔ API جواب میں حقیقی مکمل مقدار، بقایا، وجہ اور معاوضے کا ڈیٹا ہو سکتا ہے۔ یہ اقدار الگ محفوظ کریں: آرڈر کے اصل حجم کو مکمل مقدار سے نہ بدلیں۔

حتمی جواب کی مثال کچھ یوں ہو سکتی ہے:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "قدر_یا_فیلڈ_کی_عدم_موجودگی"

}

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

نامکمل حصے کو الگ فیصلے کے بغیر دوبارہ شروع نہ کریں۔ فراہم کنندہ اب بھی حساب مکمل کر رہا ہو سکتا ہے، پلیٹ فارم کے اعدادوشمار تاخیر سے اپڈیٹ ہو سکتے ہیں، اور دوبارہ درخواست ڈپلیکیٹ پروموشن پیدا کر سکتی ہے۔ تصدیق کے انتظار کی کمی یہ ہے کہ بقایا فوراً بند نہیں ہوگا، لیکن اضافی آرڈر نہیں بنے گا۔

webhooks کنٹرول جانچ کی جگہ نہیں لیتے

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

webhook کی دوبارہ ترسیل محفوظ ہونی چاہیے: ایک ہی واقعے کو نئی تبدیلی نہ سمجھیں۔ واقعات ترتیب سے باہر بھی آ سکتے ہیں، اس لیے حتمی آرڈر کو صرف دیر سے آنے والی processing کی بنیاد پر واپس نہ کریں۔

مستحکم webhooks کے باوجود کنٹرول polling درکار ہے۔ webhooks کی کمی زیادہ پیچیدہ ترتیب ہے: قابل رسائی ہینڈلر، جعلی درخواستوں سے تحفظ، ڈیڈپلیکیشن اور ایونٹ لاگ درکار ہوتا ہے۔

processing اور پھنس جانے کی صورت میں کلائنٹ کو کیا دکھائیں

انٹرفیس میں پورا تکنیکی JSON دکھانے کی ضرورت نہیں۔ processing کے لیے "آرڈر کام میں ہے" کی حالت کافی ہے۔ اگر API نے مستند پیش رفت بھیجی ہے، تو تصدیق شدہ حجم کو اصل سے الگ دکھائیں اور اسے حتمی نتیجہ قرار نہ دیں۔

جس آرڈر نے اندرونی نگرانی کی مدت سے تجاوز کیا ہو، اس کے لیے "ہم تکمیل کی جانچ کر رہے ہیں" جیسی واضح حالت استعمال کریں۔ منسوخی، واپسی یا مکمل تکمیل کے بارے میں تب تک نہ بتائیں جب تک فراہم کنندہ کے جواب سے تصدیق نہ ہو۔

اطلاعات آرڈر قبول کرنے، حتمی تکمیل، partial، منسوخی، خرابی اور جانچ کی ضرورت کے وقت مفید ہیں۔ ہر polling کے بعد پیغامات شور پیدا کرتے ہیں اور کلائنٹ کو درخواست کی حقیقی حالت سمجھنے میں مدد نہیں دیتے۔

پروسیسنگ لاگ میں کون سے اندراجات درکار ہیں

جوابات کی تاریخ پھنسے ہوئے processing، گمشدہ webhook، جزوی تکمیل کے تنازعے اور انٹرفیس اور API کے درمیان فرق کو حل کرنے میں مدد کرتی ہے۔ ہر کال کے لیے بیرونی ID، اپڈیٹ کا ذریعہ، درخواست اور جواب کا وقت، HTTP کوڈ، اصل اسٹیٹس، نارملائزڈ اسٹیٹس، پیش رفت، بقایا اور تکنیکی خرابی کا متن محفوظ کریں۔

عام لاگز میں API کلیدیں، ٹوکنز، دستخط اور دیگر سیکرٹس نہ لکھیں۔ خام جوابات تک رسائی محدود کریں: ان میں ایسا ڈیٹا ہو سکتا ہے جو سپورٹ انٹرفیس میں نہیں ہونا چاہیے۔

لانچ سے پہلے بار بار processing، پیش رفت کی عدم موجودگی، ٹائم آؤٹ، 429، 5xx خرابی، غلط JSON، دیر سے آنے والا webhook، duplicate webhook، partial، canceled اور نامعلوم اسٹیٹس کے منظرنامے چیک کریں۔ ٹیسٹ موڈ انٹیگریشن کی ساخت کے لیے مفید ہے، لیکن اس کی کمی یہ ہے کہ یہ حقیقی قطاریں اور لائیو API کی تاخیر دہرا نہیں سکتا۔