গত বছর ঢাকার একটা ছোট ই-কমার্স টিমের সঙ্গে কাজ করার সময় একটা কথা বারবার শুনেছিলাম — পেমেন্ট গেটওয়ে বসানো তো এক দিনের কাজ, তাই না? বাস্তবে কোড লিখতে লেগেছিল দুই দিন, আর বাকি উনিশ দিন গেছে ব্যর্থ লেনদেন খুঁজে বের করতে, ডাবল অর্ডার মুছতে আর অ্যাকাউন্টস টিমের সঙ্গে দিনশেষের হিসাব মেলাতে। সমস্যাটা কোডে ছিল না। সমস্যাটা ছিল শুরুর ধারণায়।
api integration নিয়ে বাংলাদেশের বেশিরভাগ ছোট-মাঝারি প্রতিষ্ঠান আর নতুন ডেভেলপারের মনে কিছু বিশ্বাস এমনভাবে গেঁথে আছে যে সেগুলো আর কেউ প্রশ্ন করে না। অথচ প্রায় প্রতিটা বড় ইন্টিগ্রেশন-দুর্ঘটনার পেছনে এই বিশ্বাসগুলোর কোনো একটা লুকিয়ে থাকে। নিচে ছয়টা ধারণা ধরে ধরে ভাঙছি — কেন সেটা ভুল, আর তার জায়গায় ঠিক কাজটা কী।
ভুল ধারণা ১: ডকুমেন্টেশন থেকে কোড কপি করলেই কাজ শেষ
ডকুমেন্টেশন হলো সবচেয়ে ভালো দিনটার গল্প — যেদিন সব ঠিকঠাক চলে। সেখানে সাধারণত একটা সফল রিকোয়েস্ট আর একটা সুন্দর সফল রেসপন্স দেখানো থাকে। কিন্তু বাস্তবে আপনার কোড যে রেসপন্সগুলো সবচেয়ে বেশি পাবে, সেগুলোর অর্ধেকই ডকে নেই: গেটওয়ে টাইমআউট হয়ে HTML এরর পেজ ফেরত এল, JSON-এর বদলে খালি বডি এল, কিংবা status ফিল্ডটা কখনো স্ট্রিং কখনো নাম্বার হয়ে এল।
সঠিক অভ্যাস: ডকুমেন্টেশনকে নয়, বাস্তব রেসপন্সকে সত্য ধরুন। ইন্টিগ্রেশনের প্রথম দিনেই এমন একটা জায়গা বানান যেখানে প্রতিটা রিকোয়েস্ট-রেসপন্স জোড়া (URL, স্ট্যাটাস কোড, হেডার, বডি) কাঁচা অবস্থায় জমা হয়। এক সপ্তাহ চালালেই দেখবেন, ডকে না থাকা তিন-চার রকম এরর ফরম্যাট আপনার লগে বসে আছে। ওগুলোই আসল স্পেসিফিকেশন।
ভুল ধারণা ২: এটা তো এক দিনের কাজ
কোডটা সত্যিই ছোট। বিশ লাইনে একটা HTTP কল লেখা যায়। কিন্তু ইন্টিগ্রেশনের কাজ HTTP কলে শেষ হয় না, শুরু হয়। যে সময়টা আসলে লাগে, সেটা মোটামুটি এভাবে ভাগ হয়:
- সুখী পথ (হ্যাপি পাথ) কোড: মোট সময়ের ১৫ শতাংশ
- এরর, টাইমআউট, রিট্রাই আর ব্যর্থ লেনদেনের হ্যান্ডলিং: ৩৫ শতাংশ
- স্যান্ডবক্স থেকে লাইভে যাওয়া — কী রোটেশন, আইপি হোয়াইটলিস্ট, মার্চেন্ট ভেরিফিকেশন: ২০ শতাংশ
- হিসাব মেলানো, রিপোর্ট আর সাপোর্ট টিমের জন্য টুল: ৩০ শতাংশ
ক্লায়েন্টকে বাজেট দেওয়ার সময় এই ভাগটা খোলাখুলি বলা ভালো। বাংলাদেশে একটা পেমেন্ট গেটওয়ে ঠিকঠাক বসাতে ২০,০০০ টাকার কোট দেওয়া আর ৫০,০০০ টাকার কোট দেওয়ার মধ্যে পার্থক্যটা দক্ষতার নয় — পার্থক্যটা হলো, দ্বিতীয় জন ব্যর্থ পেমেন্টের দিনটার কথাও দামে ধরেছেন।
ভুল ধারণা ৩: API key ফ্রন্টএন্ডে রাখলে কেউ দেখবে না
এটা সবচেয়ে খরুচে ভুল। রিঅ্যাক্ট বা নেক্সট অ্যাপের বান্ডলে সিক্রেট কী রাখলে সেটা লুকোনো থাকে না — ব্রাউজারের নেটওয়ার্ক ট্যাব খুললেই হেডারে দেখা যায়, আর মিনিফাইড JS ফাইলে Ctrl+F করলেই বেরিয়ে আসে। এসএমএস গেটওয়ের কী ফাঁস হলে সবচেয়ে সাধারণ পরিণতি হলো, রাতারাতি কেউ আপনার ব্যালেন্স থেকে হাজার হাজার প্রোমোশনাল এসএমএস পাঠিয়ে দেয়, আর সকালে আপনি শূন্য ব্যালেন্স আর একটা অপ্রীতিকর বিল নিয়ে জাগেন।
নিয়মটা সহজ: থার্ড-পার্টি সিক্রেট কী কখনো ব্রাউজারে যাবে না। আপনার ব্যাকএন্ডে একটা পাতলা প্রক্সি রুট বানান, কী শুধু সার্ভারের এনভায়রনমেন্ট ভেরিয়েবলে থাকবে, আর .env ফাইলটা গিট রিপোতে কখনো কমিট হবে না। কী একবার কোথাও পেস্ট হয়ে গেলে ধরে নিন সেটা ফাঁস — রোটেট করুন, মুছে ফেললেই হবে না।
ভুল ধারণা ৪: একবার চলতে শুরু করলে চলতেই থাকবে
ইন্টিগ্রেশন হলো একমাত্র কোড যেটা আপনি না ছুঁলেও ভেঙে যেতে পারে, কারণ ওর অর্ধেকটা অন্যের সার্ভারে থাকে। যেসব কারণে ভালো চলতে থাকা ইন্টিগ্রেশন হঠাৎ মরে যায় তার তালিকাটা বিরক্তিকরভাবে পরিচিত: ভেন্ডর পুরোনো API ভার্সন বন্ধ করে দিল আর ডেপ্রিকেশনের মেইলটা কারও স্প্যাম ফোল্ডারে পড়ে ছিল; SSL সার্টিফিকেট রিনিউ হলো আর আপনার সার্ভারের পুরোনো CA বান্ডল সেটা চিনল না; কিংবা আপনি হোস্টিং বদলালেন আর নতুন সার্ভারের আইপি ভেন্ডরের হোয়াইটলিস্টে নেই।
সঠিক অভ্যাস: ইন্টিগ্রেশনকে একটা জীবন্ত জিনিস ধরুন। ভেন্ডরের চেঞ্জলগ বা স্ট্যাটাস পেজে সাবস্ক্রাইব করুন এবং সেটা একটা টিম মেইলবক্সে যাক, কোনো ব্যক্তির ব্যক্তিগত জিমেইলে নয়। কোডে API ভার্সন স্পষ্ট করে লিখে রাখুন (যেমন /v2/), যাতে ভেন্ডর ডিফল্ট বদলালে আপনার কোড আপনাআপনি নতুন আচরণে চলে না যায়। আর সার্ভারের আইপি বদলানোর আগে হোয়াইটলিস্ট আপডেট করাটা ডিপ্লয় চেকলিস্টের অংশ বানান।
ভুল ধারণা ৫: ওয়েবহুক এসেছে মানে টাকা এসে গেছে
পেমেন্ট ইন্টিগ্রেশনে এই ভুলটা সরাসরি টাকার ক্ষতি করে। আপনার সার্ভারের ওয়েবহুক URL টা পাবলিক — যে কেউ ওখানে POST করতে পারে। কেউ যদি একটা সফল-দেখতে পেলোড বানিয়ে পাঠায় আর আপনার কোড সেটা বিশ্বাস করে অর্ডার ডেলিভারির জন্য ছেড়ে দেয়, তাহলে আপনি টাকা ছাড়াই পণ্য পাঠিয়ে দিলেন। আবার উল্টোটাও হয়: ভেন্ডর একই ওয়েবহুক তিনবার পাঠাল (কারণ প্রথম দুবার আপনার সার্ভার দেরি করে সাড়া দিয়েছিল), আর আপনার সিস্টেম গ্রাহকের ওয়ালেটে তিনবার টাকা যোগ করে ফেলল।
তিনটা জিনিস ছাড়া কোনো ওয়েবহুককে বিশ্বাস করবেন না: এক, সিগনেচার যাচাই — ভেন্ডরের দেওয়া সিক্রেট দিয়ে পেলোডের HMAC-SHA256 হিসাব করে হেডারের সিগনেচারের সঙ্গে মেলান। দুই, ডিডুপ্লিকেশন — প্রতিটা ইভেন্টের আইডি ডেটাবেজে ইউনিক কলামে রাখুন, একই আইডি দ্বিতীয়বার এলে চুপচাপ 200 ফেরত দিন কিন্তু কিছু করবেন না। তিন, নিজে গিয়ে যাচাই — ওয়েবহুক পাওয়ার পর ভেন্ডরের verify বা query API-তে ট্রানজেকশন আইডি দিয়ে আসল স্ট্যাটাস জিজ্ঞেস করুন।
ওয়েবহুকের হ্যান্ডলারকে দ্রুত হতে হবে। বেশিরভাগ ভেন্ডর ৫ থেকে ১০ সেকেন্ডের মধ্যে সাড়া না পেলে সেটাকে ব্যর্থ ধরে আবার পাঠায়। তাই হ্যান্ডলারে ভারী কাজ (এসএমএস পাঠানো, ইনভয়েস PDF বানানো) করবেন না — ইভেন্টটা কিউতে ফেলে সঙ্গে সঙ্গে 200 ফেরত দিন, বাকি কাজ ব্যাকগ্রাউন্ডে হোক।
ভুল ধারণা ৬: রেট লিমিট বড় কোম্পানির সমস্যা, আমাদের ট্রাফিক তো কম
রেট লিমিটে সাধারণত ট্রাফিকের কারণে ধরা খায় না কেউ — ধরা খায় লুপের কারণে। সাতশো অর্ডারের কুরিয়ার স্ট্যাটাস আপডেট করতে একটা ফর-লুপে সাতশো API কল পরপর মেরে দিলে ভেন্ডরের সার্ভার তিরিশ কল পরেই 429 Too Many Requests দিতে শুরু করবে। খারাপটা হলো, নিষ্পাপ কোড তখন সঙ্গে সঙ্গে রিট্রাই করে — আর রিট্রাইয়ের ঝড়ে আপনার আইপি ঘণ্টাখানেকের জন্য ব্লক হয়ে যায়। ঈদের ক্যাম্পেইনের দিন এই ব্লকটা খেলে ক্ষতিটা টাকার অঙ্কে মাপা যায়।
সঠিক অভ্যাস: প্রথম দিন থেকেই ব্যাকঅফ লিখুন। 429 বা 5xx পেলে ১ সেকেন্ড, ২ সেকেন্ড, ৪ সেকেন্ড — এভাবে অপেক্ষা করে সর্বোচ্চ তিনবার চেষ্টা করুন, আর রেসপন্সে Retry-After হেডার থাকলে সেটাকেই মানুন। বাল্ক কাজ কখনো লাইভ রিকোয়েস্টের ভেতর করবেন না; ওটা কিউ বা ক্রনে ফেলুন যেখানে প্রতি সেকেন্ডে কয়টা কল যাবে সেটা আপনি নিয়ন্ত্রণ করতে পারবেন।
শুরু করার আগে পাঁচ মিনিটের চেকলিস্ট
- স্যান্ডবক্স আর লাইভ — দুই সেট ক্রেডেনশিয়াল আছে তো? দুটো যেন কনফিগে আলাদা থাকে, কোডে নয়।
- প্রতিটা আউটগোয়িং কলে টাইমআউট বসিয়েছেন? (কানেক্ট ১০ সেকেন্ড, রিড ৩০ সেকেন্ড — ডিফল্টে অনেক HTTP ক্লায়েন্ট অসীম সময় অপেক্ষা করে।)
- একই অনুরোধ দুবার গেলে কী হবে সেটা ঠিক করেছেন? অর্ডার আইডি বা আইডেম্পোটেন্সি কী দিয়ে ডুপ্লিকেট আটকান।
- ইন্টিগ্রেশন ফেল করলে গ্রাহক কী দেখবে, আর আপনার সাপোর্ট টিম কোথায় গিয়ে কারণটা দেখবে — দুটোরই উত্তর আছে?
সচরাচর জিজ্ঞাসা
REST নাকি GraphQL — শুরুতে কোনটা শিখব? যেটা আপনার ভেন্ডর দেয় সেটাই। বাংলাদেশে বাস্তবে যেসব API-র সঙ্গে কাজ করবেন — পেমেন্ট গেটওয়ে, কুরিয়ার, এসএমএস, ব্যাংক — তার প্রায় সবই REST, আর কিছু পুরোনো ব্যাংকিং সিস্টেম এখনো SOAP বা XML পাঠায়। পছন্দের প্রশ্নটা আপনার হাতে নেই, তাই HTTP, স্ট্যাটাস কোড আর JSON পার্সিং ভালো করে বোঝাটাই বেশি কাজে দেবে।
স্যান্ডবক্সে সব ঠিক চলছে, লাইভে ভাঙছে কেন? কারণ স্যান্ডবক্স মিথ্যে বলে। বেশিরভাগ স্যান্ডবক্স সবসময় সফল রেসপন্স দেয়, রেট লিমিট চাপায় না আর লেটেন্সি কম। লাইভে গিয়ে প্রথমবার আপনি আসল টাইমআউট, আসল 429 আর আসল প্রত্যাখ্যাত পেমেন্ট দেখেন। তাই লাইভে যাওয়ার আগে ইচ্ছে করে ব্যর্থতা টেস্ট করুন — ভুল কী দিয়ে কল করুন, নেটওয়ার্ক কেটে দিন, দেখুন আপনার সিস্টেম কীভাবে পড়ে।
পুরোনো লেনদেনের হিসাব মেলাতে হবে কেন, ওয়েবহুক তো আছেই? কারণ ওয়েবহুক হারায়। আপনার সার্ভার দুই মিনিট ডাউন ছিল, কিংবা ভেন্ডরের কিউ আটকে ছিল — কোনো একটা ইভেন্ট কখনোই এসে পৌঁছাল না। দিনে একবার (রাত ২টার দিকে) ভেন্ডরের রিপোর্ট API থেকে আগের দিনের লেনদেন টেনে নিজের ডেটাবেজের সঙ্গে মিলিয়ে দেখুন। যে দশটা কেস মিলবে না, ওগুলোই আপনার সাপোর্ট টিকিট হওয়ার আগেই ধরা পড়ে যাবে।
ছোট প্রজেক্টে কি এত কিছু দরকার? সিগনেচার যাচাই, টাইমআউট আর ডুপ্লিকেট চেক — এই তিনটা কখনোই বাদ দেবেন না, প্রজেক্ট যত ছোটই হোক। বাকিগুলো (কিউ, সার্কিট ব্রেকার, ড্যাশবোর্ড) দিনে একশো লেনদেন পার হওয়ার আগ পর্যন্ত অপেক্ষা করতে পারে।
API ইন্টিগ্রেশন কঠিন নয়, শুধু অধৈর্য মানুষের প্রতি নির্মম। শুরুতেই যদি ধরে নেন যে জিনিসটা ভাঙবে — এবং সেই ভাঙার দিনটার জন্য কোড লেখেন — তাহলে বাকিটা মোটামুটি সহজ। স্ট্যাক অ্যালিক্সে আমরা পেমেন্ট, কুরিয়ার আর এসএমএস ইন্টিগ্রেশন নিয়মিত বসাই এবং লাইভে যাওয়ার আগে ব্যর্থতার পথগুলো ধরে ধরে টেস্ট করি। আপনার ইন্টিগ্রেশন নিয়ে আটকে গেলে বা লাইভে যাওয়ার আগে একটা দ্বিতীয় চোখ দরকার হলে নির্দ্বিধায় নক দিন।