উদ্দেশ্য ও সংস্করণের ইতিহাস
1 নভেম্বর 2021-এ হালনাগাদ 1.2 সংস্করণে সফটওয়্যার সরবরাহকারী ও কমিশন প্রদানকারী প্রতিষ্ঠানের জন্য Corppass দিয়ে পরিচয় যাচাই করা কমিশন-রেকর্ড API বর্ণিত। কমিশনপ্রাপকের ব্যক্তিগত কর রিটার্ন আগে পূরণ করার জন্য এটি কমিশনের তথ্য যাচাই ও দাখিল করে। 1.0 সংস্করণ শুরু হয় 15 ডিসেম্বর 2020; 6 এপ্রিল 2021-এর 1.1 সংস্করণে এন্ডপয়েন্টের পদ্ধতি এবং 1.2-তে FIN-এর M সিরিজের যাচাই যোগ হয়। এটি একটি ঐতিহাসিক ইন্টারফেস-বিবরণ; প্রতিটি এন্ডপয়েন্ট বা পোর্টালের পর্দা এখনও অপরিবর্তিত আছে, তার নিশ্চয়তা নয়।
ডেভেলপার হিসাব, প্রতিষ্ঠানের নাম ও অ্যাপ নিবন্ধন
পরীক্ষামূলক Sandbox ও প্রকৃত দাখিলের Production API Marketplace-এর জন্য আলাদা ডেভেলপার হিসাব খুলে স্বয়ংক্রিয় ইমেইলের মাধ্যমে সক্রিয় করুন। লগইনের পরে Username > My Organization > Edit organization-এ প্রকৃত প্রতিষ্ঠানের নাম লিখুন; প্রযোজ্য হলে নামের পরে আন্ডারস্কোর এবং ROC/UEN দিন। Apps > Register New Application দিয়ে অ্যাপ নিবন্ধন করুন। গ্রাহকের সম্মতি চাওয়ার সময় App Title-ই দেখানো হবে। API Products-এর অধীনে প্রাসঙ্গিক Submission of Commission Records (Corppass) সেবায় ওই অ্যাপ বেছে সদস্যতা নিন। সংযুক্ত সাধারণ API ব্যবহারবিধিতে হিসাব খোলার বিস্তারিত ধাপ আছে।
পরীক্ষামূলক পরিবেশের প্রমাণ ও প্রকৃত দাখিলের অনুমোদন
আগে Sandbox-এ পরীক্ষা করুন এবং Corppass Authentication API-তেও সদস্যতা নিন। Sandbox-এর সদস্যতার জন্য আলাদা IRAS অনুমোদন লাগে না; তবে IRAS-এর প্রকাশিত পরীক্ষার পরিস্থিতি ও সত্তা ব্যবহার করতে হবে। সফল পরীক্ষামূলক দাখিলে acknowledgement code পাওয়া যায়; যাচাইয়ের জন্য প্রতিটি পরিস্থিতির কোড data_mgmt@iras.gov.sg-এ পাঠাতে বলা হয়েছে। পরীক্ষায় উত্তীর্ণ হওয়ার পরেই Production-এ সদস্যতা ও IRAS-এর অনুমোদন নেওয়া যায়। Production শুধু সেবার বর্ণিত প্রকৃত ব্যবহারের জন্য; পরীক্ষা বা অন্য ব্যবহার নিষিদ্ধ এবং API-এর ব্যবহারের শর্ত অনুযায়ী হিসাব স্থগিত বা বন্ধ হতে পারে।
সার্ভারের সংযোগ, এন্ডপয়েন্ট ও হেডার
HTTP/2, TLS 1.2/1.3 এবং HTTP GET/POST সমর্থনকারী সার্ভার-থেকে-সার্ভার সংযোগ ব্যবহার করুন। কমিশনের পদ্ধতি POST /CommissionCP/submit; Sandbox-এর মূল ঠিকানা https://apisandbox.iras.gov.sg/iras/sb এবং Production-এর মূল ঠিকানা https://apiservices.iras.gov.sg/iras/prod। হেডারগুলো হলো X-IBM-Client-Id, X-IBM-Client-Secret, access_token এবং Content-Type: application/json। আলাদা Corppass Authentication বিবরণ অনুসারে JWT access token নিতে হবে। validateOnly=true হলে token ফাঁকা থাকতে পারে, তবে ক্লায়েন্টের পরিচয়তথ্য তখনও লাগে। উৎসের নমুনা হেডারে HTTP/1.1 লেখা, অথচ নেটওয়ার্কের শর্তে HTTP/2 বলা হয়েছে; প্রযোজ্য চলমান গেটওয়ের শর্ত যাচাই করার সময় এই পার্থক্যটি মনে রাখুন।
অনুরোধের আকারের সীমা ও ঘরের গঠন
প্রতিটি অনুরোধে সর্বোচ্চ 5,000 রেকর্ড অথবা মোট 2 MB তথ্য দেওয়া যায়—যে সীমা আগে পূরণ হয় সেটি প্রযোজ্য। JSON-এ বড় ও ছোট হাতের অক্ষর আলাদা এবং ঘরের নাম camelCase-এ লেখা। স্পষ্টভাবে ঐচ্ছিক বলা না হলে প্রতিটি বৈশিষ্ট্য দিতে হবে। সাধারণ তারিখের স্ট্রিং ISO 8601 মেনে লিখতে হয়; তবে dateOfBirth স্পষ্টভাবে আট অঙ্কের সংখ্যাসূচক YYYYMMDD ঘর। স্ট্রিং যাচাইয়ে ইংরেজি অক্ষর ও সংখ্যা, ফাঁক এবং তালিকাভুক্ত বিরামচিহ্ন গ্রহণযোগ্য: ব্যাকটিক, @, #, বন্ধনী, হাইফেন, কমা, পূর্ণচ্ছেদ, স্ল্যাশ, &, + ও আন্ডারস্কোর। String(n) সর্বোচ্চ অক্ষরসংখ্যা এবং Number(n) পূর্ণসংখ্যার অঙ্কসংখ্যার সীমা বোঝায়। সব সংখ্যা স্ট্রিংয়ে বদলে না দিয়ে অনুরোধের নির্দিষ্ট তথ্যের ধরন মেনে চলুন।
শুধু যাচাইয়ের পদ্ধতি ও আয়ের ভিত্তিবর্ষ
অনুরোধে orgAndSubmissionInfo ও commissionEarnerDtl থাকে। validateOnly অবশ্যই Boolean true বা false হবে: true শুধু যাচাই করে, দাখিল করে না; false যাচাই করে IRAS-এ দাখিলও করে। basisYear হলো আয় অর্জিত হওয়ার বছর, কর নির্ধারণের বছর নয়; তাই YA 2021-এর জন্য 2020 ব্যবহার হয়। বিবরণে সেবার বছরের তুলনায় আগের দুই বছর, চলতি বছর ও পরের এক বছর গ্রহণ করার কথা আছে। মূল দাখিলের ব্যাচে O এবং সংশোধনীতে A ব্যবহার হয়। ঘোষিত রেকর্ডসংখ্যা ও মোট কমিশনের অঙ্ক ওই অনুরোধের কমিশনপ্রাপকদের তথ্যের সঙ্গে সম্পর্কিত।
প্রতিষ্ঠানের শনাক্তকারী ও দাখিলকারীর তথ্য
প্রতিষ্ঠানের পরিচয়ের ধরন: 7 হলো UEN-BUSINESS, 8 হলো UEN-LOCAL CO, U হলো UEN-OTHERS, A হলো ASGD এবং I হলো ITR। উৎসে যথাক্রমে প্রতিষ্ঠানের বিন্যাস NNNNNNNNC, YYYYNNNNNC, TYYPQNNNNC অথবা SYYPQNNNNC, ANNNNNNNC এবং NNNNNNNNNC বলা হয়েছে; C যাচাই-অঙ্ক, N সংখ্যা ও Y বছর বোঝায়। দাখিলকারী 1 NRIC, 2 FIN অথবা A ASGD ব্যবহার করতে পারেন; NRIC-এর শুরুতে S/T ও FIN-এর শুরুতে F/G/M থাকে। প্রতিষ্ঠানের ও অনুমোদিত ব্যক্তির ঘর, সর্বোচ্চ দৈর্ঘ্য ও ঐচ্ছিক পদবি সারণিতে দেওয়া আছে। টেলিফোন নম্বরে অন্তত আট অঙ্ক থাকতে হবে।
| ঘর | তথ্যের ধরন/সীমা | শর্ত |
|---|---|---|
| validateOnly | Boolean | true/false; শুধু যাচাই নাকি যাচাইসহ দাখিল |
| basisYear | Number(4) | আয়ের বছর; আগের দুই/চলতি/পরের এক বছর |
| organisationIDType | String(1) | 7,8,U,A,I |
| organisationIDNo | String(12) | প্রতিষ্ঠানের সঙ্গে মিলে এমন শনাক্তকারী |
| authorisedPersonIDType | String(1) | 1,2,A |
| authorisedPersonIDNo | String(12) | NRIC/FIN/ASGD |
| authorisedPersonName | String(30) | দাখিলকারীর নাম |
| authorisedPersonDesignation | String(30) | ঐচ্ছিক পদবি |
| organisationName | String(60) | প্রতিষ্ঠানের নাম |
| telephone | String(20) | অন্তত 8 অঙ্ক |
| authorisedPersonEmail | String(50) | ইমেইল |
| batchIndicator | String(1) | মূল দাখিলের জন্য O/সংশোধনীর জন্য A |
| numOfRecords | Number(4) | পূর্ণসংখ্যায় রেকর্ডসংখ্যা |
| totalGrossCommission | Number(15) | পূর্ণসংখ্যায় মোট স্থূল কমিশন |
কমিশনপ্রাপকের শনাক্তকারী ও শর্তসাপেক্ষ ব্যক্তিগত তথ্য
recordID 1 থেকে শুরু হয় এবং অনন্য হতে হবে। কমিশনপ্রাপকের idType হিসেবে 1 NRIC, 2 FIN, 5 মালয়েশিয়ার পরিচয়পত্র, 6 পাসপোর্ট, 7 ব্যবসার UEN, 8 স্থানীয় কোম্পানির UEN, A ASGD, I ITR অথবা U অন্য UEN গ্রহণ করা হয়। উৎসে মালয়েশিয়ার পরিচয় নম্বর সাত/আটটি অক্ষর-সংখ্যা মেশানো চিহ্ন অথবা 12 অঙ্কের সংখ্যা বলা হয়েছে। 1/2/5/6 ধরনের ক্ষেত্রে nationality, sex, designation ও জন্মতারিখ দিতে হবে; কোম্পানির উদাহরণে এই ব্যক্তিগত ঘরগুলো নেই। তালিকার প্রচলিত জাতীয়তার কোড হলো সিঙ্গাপুরের নাগরিকের জন্য 301, মালয়েশিয়ার জন্য 304 এবং চীনের জন্য 336; অন্য কোড আলাদাভাবে সংযুক্ত তালিকায় আছে। অনুরোধের সারণিতে commissionEarnerDtl-কে Object বলা হলেও নমুনা অনুরোধে স্পষ্টভাবে কমিশনপ্রাপকদের অবজেক্টের একটি array ব্যবহার করা হয়েছে।
| ঘর | তথ্যের ধরন/সীমা | শর্ত |
|---|---|---|
| recordID | Number(4) | অনন্য; 1 থেকে শুরু |
| idType | String(1) | 1,2,5,6,7,8,A,I,U |
| idNumber | String(12) | সংশ্লিষ্ট পরিচয় নম্বর |
| name | String(80) | কমিশনপ্রাপকের নাম |
| nationality | Number(3) | 1/2/5/6-এর জন্য আবশ্যক |
| sex | String(1) | 1/2/5/6-এর জন্য F/M |
| designation | Number(1) | 1/2/5/6-এর জন্য 1–9 |
| dateOfBirth | Number(8) | 1/2/5/6-এর জন্য YYYYMMDD |
| grossCommission | Number(12) | দশমিক বা ফাঁক থাকবে না; 0 নয় |
পেশার নয়টি কোড ও মোট কমিশনের অঙ্ক
পেশার কোড হলো 1 শেয়ার লেনদেনের কমিশনভিত্তিক প্রতিনিধি (remisier), 2 স্থাবর সম্পত্তির এজেন্ট, 3 বিমা এজেন্ট, 4 পরিবেশক, 5 আর্থিক উপদেষ্টা, 6 প্রশিক্ষক, 7 থেরাপিস্ট, 8 Singapore Pools-এর খুচরা বিক্রেতা এবং 9 অন্যান্য। Sex-এ F অথবা M ব্যবহার হয়। grossCommission হবে সংখ্যাসূচক, ফাঁক বা দশমিকবিহীন এবং শূন্য নয়; উৎসের S$150,000.55 উদাহরণে সেন্ট বাদ দিয়ে 150000 পাঠানো হয়েছে। ব্যাচের মোট অঙ্কও পূর্ণসংখ্যা হতে হবে। কমিশনপ্রাপকের UEN-OTHERS বর্ণনায় TyyPQnnnnC/SyyPQnnnnC এবং প্রতিষ্ঠানের সারণিতে TYYPQNNNNC/SYYPQNNNNC লেখা আছে। এই ছাপা বিন্যাসগুলো রাখা হয়েছে; প্রতিটি বিন্যাসেই 10টি অক্ষর আছে, শুধু প্রদর্শিত বড় ও ছোট হাতের অক্ষর আলাদা। ইংরেজি নিবন্ধের অক্ষরসংখ্যা অসামঞ্জস্যপূর্ণ হওয়ার দাবি মূল উদাহরণ দিয়ে সমর্থিত নয়। একে দৈর্ঘ্যের বিরোধ ধরে সার্বজনীন বিন্যাস বানাবেন না; প্রামাণ্য শনাক্তকারী-নিয়ম দিয়ে যাচাই করুন।
সাধারণ প্রত্যুত্তর-কোড ও ত্রুটি শনাক্তকরণ
returnCode 10 অর্থ সফল প্রক্রিয়াকরণ এবং 30 অর্থ ব্যর্থতা। data-তে সেবাভিত্তিক ফল এবং info-তে ত্রুটি নির্ণয়ের তথ্য থাকে। messageCode 850300 শূন্য অনুরোধ, 850301 অবৈধ আর্গুমেন্ট, 850302 সেবার সাধারণ ব্যতিক্রম, 850303 নিষ্ক্রিয় সেবা, 850304 অনুমোদনহীন পরিচয়তথ্য এবং 850305 Sandbox-এর অবৈধ পরীক্ষামূলক ব্যবহারকারী বোঝায়। fieldInfoList-এ প্রতিটি প্রভাবিত ঘর, বার্তা ও recordID চিহ্নিত হয়। একই ত্রুটি থাকা কমিশনপ্রাপকের recordID কমা দিয়ে যুক্ত স্ট্রিংয়ে দেওয়া হতে পারে, যেমন 3,5,7; ত্রুটি কমিশনপ্রাপকের অবজেক্টের ঘরে হলেই শুধু recordID থাকে। camelCase-এর নির্দেশ থাকা সত্ত্বেও সারণিতে info ও Info উভয় বানান আছে; বাস্তবায়নে প্রযোজ্য প্রত্যুত্তর-স্কিমার সঠিক বড়/ছোট হাতের অক্ষর অনুসরণ করতে হবে।
দাখিলের স্বীকৃতি ও যাচাইয়ে সফলতার পার্থক্য
validateOnly=false-এর সফল প্রত্যুত্তরে data.acknowledgementCode, returnCode 10 ও খালি fieldInfoList থাকে। শুধু যাচাইয়ে সফল হলে data একটি খালি অবজেক্ট হয়; তা থেকে দাখিল হয়েছে বলা যায় না। ব্যর্থ অনুরোধে returnCode 30 এবং ত্রুটি নির্ণয়ের তথ্য থাকে, যেমন ভুল পরিচয়ের ধরন বা নম্বর অথবা নাম না দেওয়া, সঙ্গে প্রভাবিত রেকর্ডগুলো। 15 নম্বর পৃষ্ঠার বর্ণনায় stamp certificate-এর রেফারেন্স ও অক্ষাংশের স্থানাঙ্ক বলা হয়েছে; কমিশন সেবা ও তার প্রত্যুত্তরের উদাহরণের সঙ্গে এগুলো অসামঞ্জস্যপূর্ণ। উদাহরণে দেখানো acknowledgementCode-কে কমিশনের তথ্য দাখিলের স্বীকৃতি হিসেবে বুঝুন, ভৌগোলিক তথ্য হিসেবে নয়।
উদাহরণ ও C# দিয়ে তথ্য আদান-প্রদানের ধরন
নমুনা অনুরোধে প্রতিষ্ঠানের শীর্ষস্তরের তথ্য এবং দুজন কমিশনপ্রাপকের তথ্য আছে: ব্যক্তিগত তথ্যসহ একজন ব্যক্তি ও একটি কোম্পানি; মোট কমিশনের পৃথক অঙ্ক 2000 ও 3000 এবং ব্যাচের মোট 5000। নমুনা অনুরোধ ও সফল প্রত্যুত্তরের কিছু উপাদানের পরে অতিরিক্ত কমা আছে, যা কঠোর JSON নিয়মে বৈধ নয়; হুবহু নকল না করে JSON serializer ব্যবহার করুন। C# উদাহরণে POST অনুরোধ তৈরি, JSON content type ও পরিচয়/টোকেনের তিনটি হেডার নির্ধারণ, request stream-এ JSON লেখা, প্রত্যুত্তর পড়া এবং ফেরত আসা ত্রুটির বিবরণসহ WebException সামলানো দেখানো হয়েছে। এটি তথ্য আদান-প্রদানের উদাহরণ; Sandbox-এর অনুমোদন, অনুরোধের তথ্য যাচাই বা আলাদা পরিচয়-যাচাই পদ্ধতির বিকল্প নয়। এর মন্তব্যে 3.1.1 অনুচ্ছেদের উল্লেখ থাকলেও এই নথিতে অনুরোধের ঘরগুলো 4.2-এ আছে।
সরকারি উৎস
এই নিবন্ধে মূল সরকারি PDF-এর প্রাসঙ্গিক শর্ত, পদ্ধতি ও সংযোজনীসহ গুরুত্বপূর্ণ বিষয়গুলো স্বতন্ত্রভাবে ব্যাখ্যা করা হয়েছে। মূল ভাষ্যের জন্য সংযুক্ত নথিই প্রামাণ্য উৎস; পরবর্তী পরিবর্তন আলাদাভাবে যাচাই করতে হবে।
মূল সরকারি PDF পড়ুন ↗