সংস্করণ 2.6 ও এই স্পেসিফিকেশনের উদ্দেশ্য
11 সেপ্টেম্বর 2026 তারিখের বাইশ পৃষ্ঠার স্পেসিফিকেশনে বেতন-সফটওয়্যার নির্মাতাদের HTTP/JSON দিয়ে IR8A, Appendix 8A ও Appendix 8B যাচাই ও জমা দেওয়ার ব্যবস্থা আছে। এতে অন্তর্ভুক্তি, নিরাপত্তা, সীমা, নমুনা অবজেক্টের সব শ্রেণি এবং প্রতিক্রিয়া সামলানো ব্যাখ্যা করা হয়েছে। পৃথক Data Items and Validation Rules ওয়ার্কবুক তথ্যসূত্রের সংযুক্তি, PDF-এর অধ্যায় নয়; উৎসে অনুপস্থিত ওয়ার্কবুকের নিয়ম এই প্রবন্ধে বানিয়ে দেওয়া হয়নি।
সংস্করণের ইতিহাস ও সামঞ্জস্যের পরিবর্তন
প্রাথমিক সংস্করণ আগস্ট 2024; নেটওয়ার্ক/বার্তা নিরাপত্তা নভেম্বর 2024। মে 2025-এর চূড়ান্ত সংস্করণে OAuth 2.1 ও সংশোধিত এন্ডপয়েন্ট যোগ হয়, ERIS-এর B/C/D অংশ বাদ যায় এবং উদাহরণ হালনাগাদ হয়। জুন 2025-এ postalCode স্ট্রিং হয়। জুলাই/সেপ্টেম্বর/ডিসেম্বর 2025-এ অক্ষর যাচাই সংশোধিত হয়; ডিসেম্বরে returnCode, acknowledgementCode ও messageCode-ও স্ট্রিং হয়। জুন 2026-এ অব্যবহৃত messageCode সরিয়ে প্রতিক্রিয়া হালনাগাদ করা হয়; সেপ্টেম্বর 2026-এ লিঙ্ক বদলায়। পুরোনো সংখ্যাভিত্তিক প্রতিক্রিয়ার ধরন নতুন নমুনার সঙ্গে মিশিয়ে না দিয়ে নির্বাচিত সংস্করণ বাস্তবায়ন করুন।
অন্তর্ভুক্তি: প্রথমে Corppass, অ্যাপ্লিকেশন ও স্যান্ডবক্স
সাবস্ক্রাইব করার আগে নির্মাতার Corppass দরকার। APEX-এ অ্যাপ্লিকেশন তৈরি, API কী তৈরি, OAuth 2.1 ক্লায়েন্ট তৈরি এবং কাঙ্ক্ষিত API-তে সাবস্ক্রাইব করতে হয়। প্রোডাকশনের আগে স্যান্ডবক্স পরীক্ষা হয়। IRAS-এর পরীক্ষার সত্তা ও স্যান্ডবক্স OAuth ক্লায়েন্ট ব্যবহার করুন; বার্ষিক যাচাই-পরীক্ষায় সফটওয়্যারের সামঞ্জস্য দেখা হয়। প্রোডাকশন অ্যাক্সেসে সফল পরীক্ষা ও IRAS-এর অনুমোদন লাগে এবং প্রোডাকশন OAuth ক্লায়েন্টও দরকার।
অনুমোদনের প্রবাহ ও এন্ডপয়েন্ট
OAuth 2.1 দিয়ে Corppass অনুমোদন টোকেন নিন। অনুমোদনের tax_agent=y প্যারামিটার গ্রাহকের পক্ষে এবং n নিজ প্রতিষ্ঠানের বিষয় পরিচালনা বোঝায়। স্যান্ডবক্সে POST করুন https://sandbox.api.gov.sg/iras/employment-income-records/v2/Submit-এ এবং প্রোডাকশনে https://public.api.gov.sg/iras/employment-income-records/v2/Submit-এ। হেডারের নমুনায় এখনও পুরোনো /iras/prod/EmpIncomeRecords/submit পথ আছে; নমুনাটিকে বিকল্প এন্ডপয়েন্ট না ধরে বর্তমান এন্ডপয়েন্ট টেবিল অনুসরণ করুন।
সার্ভারের নিরাপত্তা ও প্রয়োজনীয় সব হেডার
সার্ভার-টু-সার্ভার সংযোগে TLS ও অনুমোদিত IP তালিকা ব্যবহার হয়। HTTP/2, TLS 1.2/1.3 এবং GET/POST সমর্থন করুন; সাইফার হলো ECDHE-RSA-AES256-GCM-SHA384 অথবা ECDHE-RSA-AES128-GCM-SHA256। x-apex-apikey, Bearer-এর পরে JWT Corppass অ্যাক্সেস টোকেনসহ Authorization এবং Content-Type application/json দিন; নমুনায় Accept application/json-ও আছে। EmpIncomeSub স্কোপ চাইতে হয়। নমুনার পরিচয়তথ্য কেবল উদাহরণ; প্রকৃত কী হিসেবে ব্যবহার করা যাবে না।
ব্যাচের সীমা, নির্দিষ্ট ব্যাচ পুনর্জমা ও অনুরোধের সীমা
একটি অনুরোধে সর্বোচ্চ 2000 কর্মচারীর রেকর্ড ও 8 MB। তোলা পাঠে দেখা 20001 আসলে 2000-এর পাশে পাদটীকা 1; প্রত্যাখ্যাত 2001 রেকর্ডের উদাহরণ তা নিশ্চিত করে। 3000 কর্মচারীকে আকারসীমার মধ্যে 2000 ও 1000-এর ভাগে ভাগ করুন। শুধু দ্বিতীয় ভাগ ব্যর্থ হলে সেটিই সংশোধন করে পুনরায় পাঠান, গৃহীত প্রথমটি নয়। 1000 রেকর্ডের ব্যাচও 8 MB ছাড়ালে ব্যর্থ হয়। রেকর্ডের সীমা কনফিগারযোগ্য রাখুন। প্রতি অ্যাপ্লিকেশনে ঘণ্টায় 3000 অনুরোধের সীমা; HTTP 429 মানে ওই সীমা শেষ এবং উৎসে পরের ঘণ্টায় আবার চেষ্টা করতে বলা হয়েছে।
প্রোডাকশনের বিধিনিষেধ ও সাধারণ ডেটা ফরম্যাট
প্রোডাকশন প্রকৃত AIS জমার জন্য; সেখানে পরীক্ষা নিষিদ্ধ এবং অ্যাক্সেস স্থগিত/বাতিল হতে পারে। JSON-এ বড়/ছোট অক্ষর গুরুত্বপূর্ণ; প্রপার্টি camel-case এবং ISO 8601 তারিখ YYYY-MM-DD ব্যবহার করে। স্পষ্টভাবে ঐচ্ছিক বলা না থাকলে সব প্রপার্টি দিন। String(n) সর্বোচ্চ দৈর্ঘ্য বোঝায়; Number(4)-এ চারটি পূর্ণসংখ্যার অঙ্ক এবং Decimal(13,2)-এ পূর্ণাংশে তেরো ও দশমিকের পরে দুই অঙ্ক থাকে। অনুমোদিত স্ট্রিং অক্ষর ASCII 32–127, ü/Ü/İ, LF/CR, en/em dash এবং smart quote। বাতিল হয়ে যাওয়া কালোতালিকার সংশোধন না ধরে অনুমোদিত অক্ষরের তালিকা ব্যবহার করুন।
জমার হেডার: তথ্যের প্রতিটি শ্রেণি
orgAndSubmissionInfo-তে থাকে validateOnly ও bypassWarning; incomeYear, employerTaxRefNumber ও submissionType; authorisedPersonName/contactNumber/emailAddress; softwareCompanyName/softwareName; totalNumberIR8A/amountTotalIncomeOfIR8A এবং totalNumberOfApp8A/totalNumberOfApp8B। হেডারের রেকর্ডসংখ্যা ও আয় কর্মচারীর অ্যারের সঙ্গে মিলিয়ে দেখুন। ঘরগুলির বিস্তারিত বাধ্যতামূলক মান ও যাচাই উৎসে পৃথক ওয়ার্কবুকে রাখা হয়েছে।
কর্মচারীর পরিচয় ও চাকরির ঘর
employeePersonalParticulars একটি অ্যারে। প্রতিটি আইটেমে থাকে recordId, idType/idNumber, name/dateOfBirth/sex, addressType ও ঠিকানার তিন লাইন, স্ট্রিং postalCode ও বিদেশি দেশের কোড, designation/bankCode, commencementDate/cessationDate এবং ভেতরে ir8a/appendix8A/appendix8B। ঘরের নাম হুবহু রাখুন: সারসংক্ষেপের iR8A লেবেল নমুনার ir8a কী থেকে আলাদা। একাধিক সংযোজনীর নমুনা থেকে addressType-এর বৈধ মান ধরে নেবেন না; সেখানে ভুল করে চাকরির পদবি বসানো হয়েছে, অথচ আগের নমুনায় L/F আছে।
IR8A-এর ঘর: বেতন, অন্যান্য আয় ও কর্তন
অবজেক্টে অর্থপ্রদানের সময়কালের তারিখ; বেতন/বোনাস ও চুক্তিবহির্ভূত বোনাস দেওয়ার তারিখ; পরিচালক ফি/অনুমোদনের তারিখ/section 45 সূচক; ভাতা, কমিশন, গ্র্যাচুইটি/নোটিশের বদলে অর্থ/ex-gratia, চাকরির পদ হারানোর ক্ষতিপূরণ ও সূচক; 1993-পরবর্তী পেনশন সুবিধা ও তহবিলের নাম; বিদেশি নিয়োগকর্তার পেনশন অবদান, অতিরিক্ত/স্বেচ্ছামূলক CPF; 10(1)(b)/(g)-এর শেয়ার-অপশন/শেয়ার-পুরস্কারের লাভ, অ-নগদ সুবিধা, অন্যান্য আয় ও মোট থাকে। করমুক্ত/রেমিশনের অঙ্ক ও সূচক, নিয়োগকর্তার কর বহনের সূচক এবং নিয়োগকর্তা/কর্মচারীর সংশ্লিষ্ট বহন করা অঙ্ক, CPF/নির্ধারিত তহবিলের অবদান, বেতন থেকে দান, Mosque Building Fund এবং বেতন থেকে জীবনবীমার প্রিমিয়ামও অন্তর্ভুক্ত করুন।
Appendix 8A: আবাসন ও সুবিধার সব বিভাগ
accommodationRecords-এ পুনরাবৃত্ত রেকর্ডে থাকে accommodationId, ঠিকানা, বসবাসের তারিখ/দিন, কর্মচারীর ভাগ করে থাকা, বার্ষিক মূল্য, আসবাবের সূচক/মূল্য, নিয়োগকর্তার ভাড়া ও বাসার করযোগ্য মূল্য, কর্মচারীর ভাড়ার অবদান, ইউটিলিটি/ঘর-পরিচর্যা, ড্রাইভার এবং গৃহকর্মী/মালি/রক্ষণাবেক্ষণ। ওই অ্যারের বাইরে থাকে হোটেল/সার্ভিসড অ্যাপার্টমেন্টের প্রকৃত ব্যয়, কর্মচারীর দেওয়া অঙ্ক ও করযোগ্য মূল্য; ছুটির ভ্রমণ/আনুষঙ্গিক সুবিধা; সুদ, বীমা, ছুটি, শিক্ষা, ক্লাবে প্রবেশ/সদস্যতা হস্তান্তর ফি, সম্পদের লাভ, গাড়ির পূর্ণ ব্যয়, গাড়ির সুবিধা, অন্যান্য অ-নগদ সুবিধা এবং মোট অ-নগদ সুবিধা।
Appendix 8B: ইকুইটি পারিশ্রমিক ও দুটি মোট অঙ্ক
eebrRecords-এ পুনরাবৃত্ত রেকর্ডে থাকে eebrId, কোম্পানির কর-শনাক্তকারী/নাম, পরিকল্পনার ধরন, প্রদান/প্রয়োগ বা অধিকার পাকা হওয়ার তারিখ, প্রয়োগমূল্য, শেয়ারপ্রতি বাজারমূল্য, শেয়ারের সংখ্যা ও মোট লাভ। মোট অঙ্কে 2003-পরবর্তী section 10(1)(b) ও 2003-পূর্ব section 10(1)(g)-এর লাভ পৃথক। সংস্করণ 2.0-তে ERIS-এর B/C/D অংশ বাদ দেওয়া হয়েছে; পুরোনো পেলোড থেকে সেগুলি যোগ করা উচিত নয়।
শুধু IR8A-এর উদাহরণ: তিন কর্মচারী ও মিলিয়ে দেখা আয়
2024-এর মূল জমার উদাহরণে তিনটি IR8A রেকর্ডের মোট S$165000 এবং সংযোজনীর সংখ্যা শূন্য। A-এর বেতন S$36000 ও বোনাস S$3000 = S$39000, CPF 7800 ও দান 12। B-এর বেতন 24000 ও বোনাস 2000 = 26000 এবং চাকরি শেষ 30 জুন 2024। C বিদেশি ঠিকানার পরিচালক, যার ফি 100000, অনুমোদন 30 জুন 2024 এবং section 45 সূচক Y। প্রতিটি কর্মচারীর রেকর্ডে ফাঁকা সংযোজনী অবজেক্টও থাকে। উদাহরণের শনাক্তকারী নম্বর প্রকৃত করদাতার তথ্য প্রতিষ্ঠা করে না।
একাধিক সংযোজনীর উদাহরণ ও নমুনার অভ্যন্তরীণ অসামঞ্জস্য
এক কর্মচারীর মোট আয় 77000, সঙ্গে একটি 8A ও একটি 8B। আবাসনের দুটি সারিতে প্রথমে ভাড়া 1000, কর্মচারীর অবদান নেই; পরে ভাড়া 1500 থেকে 800 বাদ দিয়ে 700। প্রতিটিতে ইউটিলিটি/ড্রাইভার/রক্ষণাবেক্ষণ 300 যোগ হয়। লিপ-ইয়ারের ক্যালেন্ডার সত্ত্বেও নমুনায় 1 জানুয়ারি–30 জুন 2024-কে 181 দিন বলা হয়েছে; ওই সংখ্যা কপি না করে প্রকৃত তারিখ যাচাই করুন। শূন্য প্রয়োগমূল্যে ESOW-এর 500 শেয়ার × 4 থেকে 2000 হয়; 2003-পূর্ব ESOP-এর 1000 শেয়ার × 1 থেকে 1000। নমুনার একাধিক মোট/সময়কাল ওয়ার্কবুক দিয়ে যাচাই করতে হয়; প্রতিটি নমুনামানকে করগণনা ধরে নেওয়া ঠিক নয়।
সব প্রতিক্রিয়া কোড ও সমস্যা-নির্ণয়ের ঘর
returnCode স্ট্রিং: 10 সফলভাবে প্রক্রিয়াকৃত; 20 গুরুতর নয় এমন সতর্কবার্তাসহ গৃহীত; 30 ত্রুটি/প্রক্রিয়াকৃত নয়; 40 সতর্কবার্তা/প্রক্রিয়াকৃত নয়। সফল জমায় data.acknowledgementCode স্ট্রিং ফেরত আসে। info-তে messageCode/message, warnings ও fieldInfoList থাকে; সমস্যা-নির্ণয়ে বিভাগ, ঘর, বার্তা ও প্রভাবিত রেকর্ড নম্বর শনাক্ত হয় এবং একই ধরনের ব্যর্থতা একসঙ্গে থাকে। 850301 আর্গুমেন্টের ত্রুটি, 850302 সেবার ভেতরের ব্যতিক্রম এবং 850305 অবৈধ স্যান্ডবক্স পরীক্ষার ব্যবহারকারী বোঝায়। টেবিলে Info/info এবং record ID-এর মিশ্র ব্যবহার আছে, নমুনায় recordId; তাই টেবিল অন্ধভাবে কপি না করে কার্যকর ব্যবস্থায় বড়/ছোট অক্ষরের সঠিক ব্যবহার নিশ্চিত করুন।
সতর্কবার্তা বনাম শুধু যাচাই: গ্রহণের অর্থ আলাদা
bypassWarning=true হলে সতর্কবার্তাসহ গ্রহণ এবং কোড 20 সম্ভব; false অবস্থায় সতর্কবার্তা থাকলে 40 হয় এবং জমা গৃহীত হয় না। নির্ভুল অনুরোধে 10 আসে। validateOnly=true হলে পরীক্ষা হয়, কিন্তু কোড 10 এলেও জমা হয় না এবং acknowledgementCode আসে না; বৈধ অ্যাক্সেস টোকেন তখনও দরকার। গৃহীত প্রোডাকশন জমার ইমেইল কোম্পানির যোগাযোগব্যক্তি এবং জমার মধ্যে দেওয়া ঠিকানা উভয়টিতে যায়। ইমেইলের ছবিটি প্রাপ্তি বোঝানোর উদাহরণ; ফেরত আসা acknowledgement-এর বিকল্প নয়।
ত্রুটির উদাহরণ ও ব্যবহারিক সমন্বয়-যাচাইতালিকা
অনুমোদিত ব্যক্তির নাম, জন্মতারিখ বা অর্থপ্রদান শুরুর তারিখ না থাকলে ঘরভিত্তিক সমস্যা-বার্তা আসে। অবৈধ শেষ তারিখের ক্ষেত্রে আয়বর্ষের 31 ডিসেম্বর অথবা চাকরি শেষের তারিখ লাগতে পারে। উৎসের উদাহরণে 2024-এর আয়ের সঙ্গে 2025-এর শেষ-তারিখের বার্তা মিশেছে; তাই স্থির নমুনাবছর নয়, প্রকৃত আয়বর্ষ ও ওয়ার্কবুকের নিয়ম প্রয়োগ করুন। bypassWarning=false-সহ সংশোধন 40-এ থেমে যেতে পারে। সাধারণ ব্যতিক্রম 30/850302 হলে API_SUPPORT@iras.gov.sg-এ যোগাযোগের নির্দেশ আছে। যাচাই ও জমা পৃথক রাখুন, acknowledgement সংরক্ষণ করুন, গৃহীত ব্যাচ মিলিয়ে দেখুন, কেবল ব্যর্থ ভাগ সংশোধন করুন এবং সরকারি স্পেসিফিকেশন/ওয়ার্কবুকের লিঙ্ক রাখুন।
সরকারি উৎস
এই প্রবন্ধে প্রাসঙ্গিক শর্ত, প্রক্রিয়া ও সংযোজনীসহ সরকারি PDF-এর মূল বিষয়বস্তুর স্বতন্ত্র ব্যাখ্যা দেওয়া হয়েছে। মূল ভাষার জন্য সংযুক্ত নথিই প্রামাণ্য উৎস; পরবর্তী পরিবর্তন আলাদাভাবে যাচাই করা উচিত।
সরকারি মূল PDF পড়ুন ↗