API-এর মাধ্যমে অর্ডার চেক করার সময় «চলমান» স্ট্যাটাস হ্যান্ডেল করা

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":""}'

URL স্ট্রিংয়ে API-কী পাঠাবেন না। রিকোয়েস্টের ঠিকানা প্রক্সি লগ, অ্যানালিটিক্স সিস্টেম, ব্রাউজার হিস্ট্রি এবং টেকনিক্যাল লগে পড়ে। 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 বা অনুরূপ সুপারিশ দিলে সেটিকে অগ্রাধিকার হিসেবে ব্যবহার করুন।
• ওয়েবহুকযুক্ত অর্ডারের জন্য নিয়ন্ত্রণ polling রাখুন: নোটিফিকেশন নাও পৌঁছাতে পারে।

বিরল polling-এর অসুবিধা হলো প্রকৃত সমাপ্তির পরেও ইন্টারফেস পুরোনো স্ট্যাটাস দেখাতে পারে। অতিরিক্ত ঘন ঘন polling-এর অসুবিধা হলো API সীমায় পৌঁছে 429 পাওয়ার এবং অতিরিক্ত লোড তৈরি করার ঝুঁকি।

processing নিয়ন্ত্রণের জন্য কোন সময়গুলো সংরক্ষণ করবেন

স্বাভাবিক সম্পাদন এবং আটকে যাওয়া আলাদা করতে শুধুমাত্র একটি বর্তমান স্ট্যাটাস যথেষ্ট নয়। প্রতিটি সক্রিয় অর্ডারের জন্য সংরক্ষণ করুন তৈরির সময়, প্রথম processing পাওয়ার সময়, শেষ সফল API রেসপন্স, বাহ্যিক স্ট্যাটাসের শেষ পরিবর্তন এবং অগ্রগতির শেষ পরিবর্তন।

এছাড়াও মূল পরিমাণ, নিশ্চিত সম্পন্ন পরিমাণ, অবশিষ্টাংশ এবং সরবরাহকারীর মূল স্ট্যাটাস সংরক্ষণ করা উপকারী। API অগ্রগতি না দিলে এটি অর্ডার আটকে গেছে ভাবার কারণ নয়: শেষ রেসপন্সের সময় এবং সেবার শর্তে উল্লেখ থাকলে প্রত্যাশিত প্রক্রিয়াকরণ সময়ের উপর নির্ভর করুন।

সর্বোচ্চ অপেক্ষার সময় সব সেবার জন্য একটি সংখ্যা দিয়ে নির্ধারণ করা যাবে না। সরবরাহকারী নির্দিষ্ট সেবার জন্য যে সময়সীমা উল্লেখ করেন তা ব্যবহার করুন, কিউ এবং ডেটা আপডেটের জন্য অভ্যন্তরীণ বাফারসহ। সময়সীমা উল্লেখ না থাকলে প্রতিটি সেবা বিভাগের জন্য আলাদা নিয়ম নির্ধারণ করুন এবং প্রকৃত প্রক্রিয়াকরণের ইতিহাস অনুযায়ী তা পুনর্বিবেচনা করুন।

processing পরিবর্তন না হলে কী করবেন

দীর্ঘস্থায়ী processing ত্রুটি প্রমাণ করে না। প্রথমে যাচাই করুন সফল API রেসপন্স এসেছিল কি না, completed_quantity বা remains পরিবর্তিত হয়েছিল কি না, ওয়েবহুক ছিল কি না এবং সেবার নিয়ম পরিবর্তিত হয়েছিল কি না। দৃশ্যমান বৃদ্ধির অনুপস্থিতি প্ল্যাটফর্মের পরিসংখ্যানের বিলম্ব বা সরবরাহকারী শুধুমাত্র শেষে অগ্রগতি আপডেট করার কারণে হতে পারে।

অভ্যন্তরীণ অপেক্ষার সময়সীমা ছাড়িয়ে গেলে অর্ডার স্বয়ংক্রিয়ভাবে বাতিল করবেন না। একটি অগ্রাধিকার স্ট্যাটাস যাচাই সম্পাদন করুন, থাকলে আলাদা মেথডে ডেটা অনুরোধ করুন এবং নোটিফিকেশনের ইতিহাস যাচাই করুন। সরবরাহকারী এখনও processing নিশ্চিত করলে অর্ডারটিকে অভ্যন্তরীণ «যাচাই প্রয়োজন» অবস্থায় নিন, কিন্তু বাহ্যিক স্ট্যাটাস প্রতিস্থাপন না করে সংরক্ষণ করুন।

• শেষ নিশ্চিত রেসপন্সের সময় এবং সম্পূর্ণ API রেসপন্স লিপিবদ্ধ করুন।
• আগের পোলের পর থেকে অগ্রগতি পরিবর্তিত হয়েছে কি না যাচাই করুন।
• অভ্যন্তরীণ থ্রেশহোল্ডে পৌঁছানোর পরে স্বয়ংক্রিয় রিকোয়েস্টের ফ্রিকোয়েন্সি কমান।
• সাপোর্টে বাহ্যিক ID, লিংক, সেবার প্যারামিটার, স্ট্যাটাসের ইতিহাস এবং টেকনিক্যাল ত্রুটি পাঠান।
• সরবরাহকারীর উত্তর বা স্পষ্ট চূড়ান্ত স্ট্যাটাসের আগে অবশিষ্টাংশ পুনরায় চালু করবেন না।

ম্যানুয়াল যাচাইয়ের অসুবিধা হলো অর্ডারটির জন্য সাপোর্টের মনোযোগ প্রয়োজন। কিন্তু স্বয়ংক্রিয় বাতিল বা ডুপ্লিকেট আরও বিপজ্জনক: সরবরাহকারীর কাছে সম্পাদন চলতে থাকতে পারে।

রিকোয়েস্ট ব্যর্থতা এবং অর্ডার স্ট্যাটাস কীভাবে আলাদা করবেন

নেটওয়ার্ক ত্রুটি, টাইমআউট, HTTP 429 এবং 5xx রেসপন্স অর্ডারের নিজের অবস্থা জানায় না। তারা শুধুমাত্র বোঝায় যে নতুন নির্ভরযোগ্য স্ট্যাটাস পাওয়া যায়নি। এমন পরিস্থিতিতে শেষ নিশ্চিত স্ট্যাটাস রাখুন, টেকনিক্যাল ত্রুটি লিপিবদ্ধ করুন এবং নতুন যাচাইয়ের পরিকল্পনা করুন।

429-এর ক্ষেত্রে Retry-After বিবেচনা করুন, যদি হেডার পাঠানো হয়। সাময়িক নেটওয়ার্ক ত্রুটি এবং 5xx-এর ক্ষেত্রে চেষ্টার মধ্যে বিরতি বাড়ান। অনুমোদন, স্বাক্ষর বা অ্যাক্সেস অধিকারের ত্রুটির ক্ষেত্রে ঘন ঘন রিট্রাই করবেন না: কী, টোকেনের মেয়াদ, IP সীমাবদ্ধতা এবং অ্যাক্সেস সেটিংস যাচাই করতে হবে।

API HTTP 200 ফেরত দিলেও JSON পার্স না হলে বা রেসপন্সে order_id এবং status না থাকলে সম্পূর্ণ রেসপন্স বডি সংরক্ষণ করুন এবং যাচাইটিকে ভুল হিসেবে চিহ্নিত করুন। স্ট্যাটাসের অনুপস্থিতিকে completed, canceled বা processing দিয়ে প্রতিস্থাপন করবেন না।

কখন স্বয়ংক্রিয় পুনরায় রিকোয়েস্ট বন্ধ করবেন

Polling অসীম হওয়া উচিত নয়। সাময়িক ত্রুটির জন্য টেকনিক্যাল পুনরাবৃত্তির সংখ্যা সীমিত করুন এবং আলাদাভাবে অর্ডার processing-এ থাকার মোট সময় নিয়ন্ত্রণ করুন। রিট্রাই সীমা শেষ হলে যাচাই টাস্কটি বিশ্লেষণ কিউতে নিন, প্রতিটি মিনিটে ফলাফলহীন নতুন রিকোয়েস্ট তৈরি করবেন না।

স্ট্যাটাস রিকোয়েস্টের পুনরাবৃত্তি সাধারণত নিরাপদ যদি মেথড শুধুমাত্র ডেটা পড়ে। তৈরি, বাতিল, টপ-আপ, পুনরায় চালু এবং ফেরতের মেথড টাইমআউটের পরে যান্ত্রিকভাবে পুনরাবৃত্তি করা যাবে না। ইডেম্পোটেন্ট কী বা সরবরাহকারীর স্পষ্ট নিশ্চয়তা ছাড়া এই ধরনের পুনরাবৃত্তি অর্ডার দুবার পরিবর্তন করতে পারে।

রিট্রাই সীমিত করার অসুবিধা হলো কিছু আপডেট ম্যানুয়াল কাজ হয়ে যাবে। অসীম রিট্রাই আরও খারাপ: তারা ত্রুটি ঢেকে দেয়, সীমা খরচ করে এবং লগ বিশ্লেষণ জটিল করে।

processing-এর পরে চূড়ান্ত স্ট্যাটাস কীভাবে গ্রহণ করবেন

দেরিতে আসা polling রেসপন্স বা পুরোনো ওয়েবহুকের কারণে 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 ঠিক কী নিশ্চিত করছে: ফেরত ইতিমধ্যে সম্পন্ন হয়েছে, ফেরত শুধুমাত্র পরিকল্পিত, অবশিষ্টাংশ বাতিল হয়েছে নাকি সাপোর্টে যোগাযোগ প্রয়োজন। ফেরত সম্পর্কিত ফিল্ড না থাকলে অবশিষ্টাংশ স্বয়ংক্রিয়ভাবে ক্ষতিপূরণ হয়েছে বলে গণ্য করবেন না।

আলাদা সিদ্ধান্ত ছাড়া অসম্পন্ন অংশ পুনরায় চালু করবেন না। সরবরাহকারী এখনও হিসাব সম্পন্ন করছেন, প্ল্যাটফর্মের পরিসংখ্যান বিলম্বে আপডেট হতে পারে এবং নতুন অনুরোধ ডুপ্লিকেট প্রমোশন তৈরি করতে পারে। নিশ্চয়তার অপেক্ষার অসুবিধা হলো অবশিষ্টাংশ তাৎক্ষণিকভাবে বন্ধ হবে না, কিন্তু অতিরিক্ত অর্ডার তৈরি হবে না।

ওয়েবহুক নিয়ন্ত্রণ যাচাইয়ের বিকল্প নয়

ওয়েবহুক পরবর্তী polling-এর অপেক্ষা না করে ইভেন্টের পরপরই অর্ডার কার্ড আপডেট করতে দেয়। হ্যান্ডলারে বাহ্যিক ID দিয়ে অর্ডার খুঁজুন, স্বাক্ষর বা সিক্রেট যাচাই করুন, ইভেন্ট ID সংরক্ষণ করুন এবং অনুমোদনযোগ্যতা যাচাইয়ের পরেই রূপান্তর প্রয়োগ করুন।

ওয়েবহুকের পুনরায় ডেলিভারি নিরাপদ হওয়া উচিত: একই ইভেন্টকে নতুন পরিবর্তন হিসেবে গণ্য করা যাবে না। ইভেন্টগুলো ক্রমবহির্ভূতভাবেও আসতে পারে, তাই শুধুমাত্র দেরিতে আসা processing-এর ভিত্তিতে চূড়ান্ত অর্ডারকে পিছিয়ে নেবেন না।

স্থিতিশীল ওয়েবহুক থাকলেও নিয়ন্ত্রণ polling প্রয়োজন। ওয়েবহুকের অসুবিধা হলো আরও জটিল সেটআপ: অ্যাক্সেসযোগ্য হ্যান্ডলার, জাল রিকোয়েস্ট থেকে সুরক্ষা, ডিডুপ্লিকেশন এবং ইভেন্ট লগ প্রয়োজন।

processing এবং আটকে যাওয়ার সময় ক্লায়েন্টকে কী দেখাবেন

ইন্টারফেসে সম্পূর্ণ টেকনিক্যাল JSON দেখানোর প্রয়োজন নেই। processing-এর জন্য «অর্ডার কাজ চলছে» অবস্থা যথেষ্ট। API নির্ভরযোগ্য অগ্রগতি পাঠালে নিশ্চিত পরিমাণ মূল পরিমাণ থেকে আলাদাভাবে দেখান এবং এটি চূড়ান্ত ফলাফল হিসেবে উপস্থাপন করবেন না।

যে অর্ডার অভ্যন্তরীণ নিয়ন্ত্রণ সময়সীমা ছাড়িয়ে গেছে তার জন্য «সম্পাদন যাচাই করছি»-এর মতো বোধগম্য অবস্থা ব্যবহার করুন। সরবরাহকারীর রেসপন্সে নিশ্চিত না হওয়া পর্যন্ত বাতিল, ফেরত বা সম্পূর্ণ সমাপ্তির কথা জানাবেন না।

অর্ডার গ্রহণ, চূড়ান্ত সম্পাদন, partial, বাতিল, ত্রুটি এবং যাচাইয়ের প্রয়োজনে নোটিফিকেশন উপকারী। প্রতিটি polling-এর পরে বার্তা শব্দ তৈরি করে এবং ক্লায়েন্টকে অনুরোধের প্রকৃত অবস্থা বুঝতে সাহায্য করে না।

প্রসেসিং লগে কী কী এন্ট্রি প্রয়োজন

রেসপন্সের ইতিহাস আটকে থাকা processing, হারানো ওয়েবহুক, আংশিক সম্পাদন নিয়ে বিরোধ এবং ইন্টারফেস ও API-এর মধ্যে অমিল বিশ্লেষণ করতে সাহায্য করে। প্রতিটি অনুরোধের জন্য সংরক্ষণ করুন বাহ্যিক ID, আপডেটের উৎস, রিকোয়েস্ট ও রেসপন্সের সময়, HTTP কোড, মূল স্ট্যাটাস, স্বাভাবিকীকৃত স্ট্যাটাস, অগ্রগতি, অবশিষ্টাংশ এবং টেকনিক্যাল ত্রুটির টেক্সট।

সাধারণ লগে API-কী, টোকেন, স্বাক্ষর এবং অন্যান্য সিক্রেট লিখবেন না। কাঁচা রেসপন্সে অ্যাক্সেস সীমিত করুন: সেখানে এমন ডেটা থাকতে পারে যা সাপোর্ট ইন্টারফেসে থাকা উচিত নয়।

চালু করার আগে বারবার processing, অগ্রগতির অনুপস্থিতি, টাইমআউট, 429, 5xx ত্রুটি, ভুল JSON, দেরিতে আসা ওয়েবহুক, duplicate ওয়েবহুক, partial, canceled এবং অজানা স্ট্যাটাসের পরিস্থিতি যাচাই করুন। টেস্ট মোড ইন্টিগ্রেশনের কাঠামোর জন্য উপকারী, কিন্তু এর অসুবিধা হলো এটি প্রকৃত কিউ এবং কার্যকর API-এর বিলম্ব পুনরাবৃত্তি নাও করতে পারে।