آرڈر API سے اٹھانا: وہ ایک فیصلہ جس پر پورا نظام کھڑا ہے

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

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

پڑھنا اور اٹھانا ایک چیز نہیں

GET /orders صرف پڑھتا ہے۔ جو بھی پوچھے، اسے وہی آرڈر دکھا دیتا ہے اور خود کچھ نہیں بدلتا۔ اس کا مطلب یہ ہے کہ اگر آپ دو کارکن چلا رہے ہیں، یا ایک کارکن ہے مگر وہ ناکامی پر دوبارہ کوشش کرتا ہے، تو ایک ہی آرڈر دونوں کے ہاتھ آئے گا اور دونوں اسے پورا کرنے چل پڑیں گے۔

کام اٹھانے والا راستہ POST /orders-pull ہے۔ یہ آپ کے انتظار میں پڑے ہوئے ہاتھ والے آرڈر چنتا ہے، ہر ایک کو انتظار سے کارروائی کی حالت میں بدلتا ہے، اور جواب میں صرف وہی آرڈر دیتا ہے جن کی یہ تبدیلی واقعی لگ گئی۔ اگر دوسرا کارکن ایک لمحے بعد پوچھے تو وہ آرڈر اس کے جواب میں ہوگا ہی نہیں۔ درخواست کے ساتھ limit بھیجا جا سکتا ہے، جو خالی چھوڑنے پر سو ہے اور پانچ سو سے اوپر نہیں جاتا۔ ترتیب پرانے آرڈر سے شروع ہوتی ہے۔

یہ فرق چھوٹا نہیں ہے۔ دو کارکنوں کا ایک ہی خریدار کو دو الگ اکاؤنٹ بھیج دینا اسی ایک انتخاب سے ہوتا ہے۔

پورا چکر، اسی ترتیب میں

1. اٹھائیں۔ POST /orders-pull۔
2. پٹا لگائیں، اگر آپ کا کام سست ہے۔ PATCH /orders/{id}/last-process-time، خالی جسم کے ساتھ۔
3. پہنچائیں۔ POST /orders-update میں وہ سطریں بھیجیں جو خریدار کو ملنی ہیں۔
4. بند کریں۔ اسی کال میں حالت completed لکھیں، یا partial اگر آپ نے آرڈر کا کچھ حصہ ہی پورا کیا ہے۔

شناخت ہر کال پر ایک سرخی سے ہوتی ہے اور اس کی دو صورتیں قبول ہیں: X-Api-Key یا Authorization: Bearer۔ کنجی اپنے پینل کے API والے صفحے سے بنتی ہے۔ سرخی بھیجی ہی نہ ہو تو جواب API_KEY_REQUIRED آتا ہے، اور غلط کنجی پر INVALID_API_KEY۔ یہ دو الگ خرابیاں ہیں اور ان کا علاج بھی الگ ہے۔

تیس منٹ والا پٹا خود بخود نہیں لگتا

دونوں پڑھنے والے راستے ایسے آرڈر چھوڑ دیتے ہیں جن پر پچھلے تیس منٹ کے اندر کارروائی کا وقت درج ہو۔ پڑھ کر لگتا ہے کہ نظام خود دہرائی روک رہا ہے۔ ایسا نہیں ہے، کیونکہ یہ وقت کوئی راستہ خود نہیں لکھتا۔ اسے صرف آپ لکھتے ہیں، PATCH /orders/{id}/last-process-time سے۔

یعنی یہ ایک ایسا پٹا ہے جو آپ خود اپنے اوپر لگاتے ہیں۔ آرڈر اٹھاتے وقت لگا دیں تو وہ آدھے گھنٹے تک آپ کی اگلی پوچھ گچھ میں نہیں آئے گا، جو اس وقت کام کی چیز ہے جب ترسیل میں دیر لگتی ہو اور آپ ہر منٹ پوچھ رہے ہوں۔ کوئی خاص مدت چاہیے تو ISO وقت بھیج دیں، اور فوراً چھوڑنا ہو تو null۔ اس راستے کو بالکل استعمال نہ کریں تو یہ کھڑکی آپ پر لگتی ہی نہیں۔

ایک بات صاف رہے: دو بار اٹھانے سے orders-pull پہلے ہی بچا لیتا ہے۔ پٹا دوسری خرابی کے لیے ہے، یعنی جب آرڈر آپ کے پاس ہے، کام جاری ہے، اور آپ اسے دوبارہ سامنے نہیں دیکھنا چاہتے۔

آپ کی بھیجی ہوئی سطروں کے ساتھ کیا ہوتا ہے

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

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

سطر کے اندر کیا ہے، اس سے نظام کو کوئی غرض نہیں۔ وہ ایک عبارت کے طور پر محفوظ ہوتی ہے اور اسے کبھی پڑھا یا الگ نہیں کیا جاتا۔ یعنی جو ترتیب آپ کے اشتہار میں لکھی ہے، وہی خریدار کو متوقع ہوگی، اور اس پر عمل کرانے والا کوئی نہیں۔ سب کچھ خالی نکل آئے تو INVALID_ACCOUNTS آتا ہے جس کا پیغام "No valid accounts provided" ہے۔

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

دو حدیں جن پر 429 آتا ہے

ترسیل والی کال پر ایک ہی کنجی سے کالوں کے درمیان کم از کم دو سو ملی سیکنڈ کا وقفہ ہے، اور ایک ہی صارف کے صرف دو مطالبات ایک وقت میں چل سکتے ہیں۔ دونوں پر جواب 429 آتا ہے اور جسم میں retry_after_ms ہوتا ہے، پہلی صورت میں RATE_LIMIT کے ساتھ اور دوسری میں CONCURRENCY_LIMIT کے ساتھ۔

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

ہاتھ والا مطلب سست نہیں ہے

یہ غلط فہمی عام ہے، اور اعداد اس کے بالکل الٹ ہیں۔ ہاتھ والی نوعیت یہ بتاتی ہے کہ مال کون چڑھاتا ہے، یہ نہیں کہ کتنی دیر لگتی ہے۔

سائٹ پر ہاتھ والے مکمل ہوئے 6,649 آرڈروں کا حساب لگایا جائے تو ادائیگی سے مکمل ہونے تک کا درمیانی وقت آدھے منٹ سے بھی کم ہے، اور تقریباً ہر چار میں سے تین آرڈر دس منٹ کے اندر بند ہو جاتے ہیں۔ ایک دن سے زیادہ صرف ہر چالیس میں سے ایک پر لگتا ہے۔

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

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

راستوں کی مکمل فہرست، مال بنانے اور تھوک میں سطریں چڑھانے کے راستے سمیت، API والے صفحے پر ہے۔ فہرست کو ہاتھ والی، ذخیرے والی یا بیرونی نوعیت میں سے کیا رکھنا ہے، یہ فیصلہ مال سنبھالنے والے صفحے پر ہے، اور خدمات کی طرف کا معاملہ خدمت بنانے والے صفحے پر۔