সংস্করণ ও সেবার উদ্দেশ্য
1 অক্টোবর 2026-এর সংস্করণ 1.4-এ Corppass ও APEX দিয়ে অনুদানের রেকর্ড জমা দেওয়া বর্ণিত হয়েছে। মূল সংস্করণ অক্টোবর 2024-এর; সেপ্টেম্বর 2025-এ কর এজেন্ট নির্বাচন যোগ, ডিসেম্বর 2025-এ রেসপন্স কোড স্ট্রিংয়ে পরিবর্তন, এপ্রিল 2026-এ উদাহরণ সংশোধন এবং অক্টোবর 2026-এ recordId ও দাতার পরিচয়ের বর্ণনা হালনাগাদ, নমুনা কোড অপসারণ ও যুক্ত হওয়ার লিংক নবায়ন করা হয়েছে। এটি সংযুক্তির কারিগরি নির্দিষ্টকরণ, সব অনুদান কর-বাদ পাওয়ার যোগ্য—এমন সাধারণ সিদ্ধান্ত নয়।
ডেভেলপার হিসেবে যুক্ত হওয়া ও অনুমোদন
ডেভেলপারদের Corppass প্রয়োজন। প্রতিষ্ঠানের Admin বা Sub-Admin-কে APEX Cloud e-Service বরাদ্দ দিতে হবে। অ্যাপ্লিকেশন নিবন্ধন, API কী তৈরি, OAuth 2.1 ক্লায়েন্ট তৈরি ও API-তে অ্যাপ্লিকেশন সাবস্ক্রাইব করুন। সেবা বন্ধ বা পরিবর্তনের খবরের জন্য প্রথম লগইনের ইমেইল হালনাগাদ করুন। DonationSub scope দিয়ে OAuth 2.1-এর মাধ্যমে Corppass টোকেন নিন। অনুমোদনের সময় tax_agent=y মানে ব্যবসায়িক ক্লায়েন্টের হয়ে কাজ করা; tax_agent=n মানে প্রতিষ্ঠানের নিজস্ব করের বিষয়।
প্রথমে স্যান্ডবক্স, পরে অনুমোদিত উৎপাদন পরিবেশ
স্যান্ডবক্স সাবস্ক্রিপশনে IRAS অনুমোদন লাগে না। IRAS পরীক্ষামূলক সত্তা, OAuth 2.1 Sandbox Client এবং Donation API Test Guide-এর পরিস্থিতি ব্যবহার করুন। উৎপাদন পরিবেশে সফল স্যান্ডবক্স পরীক্ষা ও IRAS অনুমোদন, সঙ্গে উৎপাদন OAuth ক্লায়েন্ট চাই। উৎপাদন পরিবেশ শুধু উল্লিখিত সেবার জন্য; সেখানে পরীক্ষা শর্তভঙ্গ এবং স্থগিত বা বাতিলের কারণ হতে পারে। IRAS API ও APEX—উভয়ের শর্ত প্রযোজ্য।
এন্ডপয়েন্ট, তথ্য পরিবহন ও হেডার
উপযুক্ত পরিবেশ অনুযায়ী POST https://sandbox.api.gov.sg/iras/donation-records/v1/Submit বা https://public.api.gov.sg/iras/donation-records/v1/Submit ব্যবহার করুন। সার্ভার-টু-সার্ভার সংযোগে TLS ও IP অনুমোদন তালিকা ব্যবহৃত হয়; অ্যাপ্লিকেশনে HTTP/2, TLS 1.2/1.3 এবং HTTP GET/POST সমর্থন থাকতে হবে। x-apex-apikey-তে সাবস্ক্রাইব করা অ্যাপ্লিকেশনের কী, Authorization-এ Bearer-এর পর Corppass JWT এবং Content-Type-এ application/json দিন। ছাপা হেডারের উদাহরণে এখনও পুরোনো /iras/prod/DonationCP/submit ও HTTP/1.1 আছে; এগুলো বর্তমান এন্ডপয়েন্ট সারণি ও পরিবহন শর্তের সঙ্গে মেলে না, তাই হালনাগাদ পথ হিসেবে ধরা উচিত নয়।
পেলোডের সীমা, সম্পূর্ণ গ্রহণ ও পুনঃচেষ্টা
প্রতি অনুরোধের সীমা 5,000 রেকর্ড ও 2 MB। যেকোনো একটি অতিক্রম করলে ব্যর্থ হবে: 2 MB-এর বেশি 4,000 রেকর্ড ও 5,001 রেকর্ড—উভয়ই প্রত্যাখ্যাত। 8,000 রেকর্ডকে 5,000 ও 3,000-এর অনুরোধে ভাগ করুন এবং প্রতিটির আকারসীমা বজায় রাখুন। পেলোড আংশিক গ্রহণ করা হয় না: প্রতিটি রেকর্ডকে উত্তীর্ণ হতে হবে। 3,500 রেকর্ডের অনুরোধ সফল কিন্তু পৃথক 1,500 রেকর্ডের অনুরোধ ব্যর্থ হলে শুধু ব্যর্থ অনুরোধ ঠিক করে আবার দিন। প্রতি অ্যাপ্লিকেশনে ঘণ্টায় 1,000 অনুরোধ সীমা; HTTP 429 এবং Assembly Rate Limit exceeded এলে পরের ঘণ্টায় পুনরায় চেষ্টা করতে হয়।
বড়/ছোট অক্ষর, অনুমোদিত চিহ্ন ও তথ্যের ধরন
JSON নাম বড়/ছোট অক্ষরনির্ভর এবং সাধারণত camelCase। আবশ্যিক বৈশিষ্ট্য থাকতে হবে; ঐচ্ছিক ব্যতিক্রম সারণিতে চিহ্নিত। তারিখের স্ট্রিং ISO 8601 মেনে চলে, তবে dateOfDonation স্পষ্টভাবে আট অঙ্কের সংখ্যাসূচক YYYYMMDD। স্ট্রিংয়ের দৈর্ঘ্য সর্বোচ্চ সীমা; Number(n) সর্বোচ্চ nটি পূর্ণসংখ্যার অঙ্ক বোঝায়। অনুমোদিত অক্ষর হলো ASCII 32–127, ü, Ü, İ, LF ও CR, en/em ড্যাশ এবং বাঁকানো দ্বৈত/একক উদ্ধৃতিচিহ্ন। অন্য অক্ষর যাচাইয়ে ব্যর্থ হতে পারে।
প্রতিষ্ঠান ও জমার অবজেক্ট
orgAndSubmissionInfo-তে IPC পরিচয়, অনুমোদিত ব্যক্তি ও মোট অঙ্ক থাকে। basisYear হলো অনুদান পাওয়ার বছর; আগের তিন বছর, চলতি বছর ও পরের এক বছর গ্রহণযোগ্য। organisationIDType-এ 5,6,U,A,I চলে; সংশ্লিষ্ট বিন্যাস NNNNNNNNC, YYYYNNNNNC, TYYPQNNNNC/SYYPQNNNNC, ANNNNNNNC ও NNNNNNNNNC। C পরীক্ষাসূচক অঙ্ক, N একটি অঙ্ক ও Y বছরের অংশ বোঝায়। জমাদানকারীর পরিচয়ে NRIC S/T, FIN F/G/M, ASGD বা ITR চলে। validateOnly=true শুধু যাচাই করে, জমা দেয় না; false যাচাই করে জমা দেয়। নিচের কাঠামোর সারণিতে ঘরের আকার ও ঐচ্ছিকতা অক্ষুণ্ণ রাখা হয়েছে।
| তথ্যের ঘর | ধরন/সর্বোচ্চ সীমা | শর্ত |
|---|---|---|
| validateOnly | Boolean | আবশ্যিক; true শুধু যাচাই করে, false জমা দেয় |
| basisYear | Number(4) | আবশ্যিক; পাওয়ার বছর, আগের 3/চলতি/পরের 1 বছর |
| organisationIDType | String(1) | আবশ্যিক;5/6/U/A/I |
| organisationIDNo | String(12) | আবশ্যিক; সংশ্লিষ্ট পরিচয়ের বিন্যাস |
| organisationName | String(60) | আবশ্যিক |
| batchIndicator | String(1) | আবশ্যিক;O/A |
| authorisedPersonIDNo | String(12) | আবশ্যিক;NRIC/FIN/ASGD/ITR |
| authorisedPersonName | String(30) | আবশ্যিক |
| authorisedPersonDesignation | String(30) | ঐচ্ছিক |
| telephone | String(20) | আবশ্যিক; অন্তত 8 অঙ্ক |
| authorisedPersonEmail | String(50) | আবশ্যিক |
| numOfRecords | Number(7) | আবশ্যিক; পূর্ণসংখ্যায় রেকর্ডের সংখ্যা |
| totalDonationAmount | Number(12) | আবশ্যিক; donationAmount-এর যোগফল |
দাতার রেকর্ড ও বিশেষ পরিচয়ের শর্ত
donationDonorDtl-এ দাতার রেকর্ড থাকে; অনুরোধের সারণিতে Object লেখা থাকলেও উদাহরণে অ্যারে ব্যবহৃত। recordId হলো 1 থেকে শুরু হওয়া স্বতন্ত্র চলতি ক্রমসংখ্যা। idType-এ 1 NRIC,2 FIN,5 UEN-business,6 UEN-local company,A ASGD,I ITR,U UEN-others চলে। FIN-এর M উপসর্গসহ সংশ্লিষ্ট পরিচয়ের বিন্যাস যাচাই করুন। VCC উপ-তহবিল সত্তার জন্য IRAS বরাদ্দকৃত ASGD নম্বর ব্যবহার করুন। অন্যথায় individualIndicator ঐচ্ছিক, তবে A বা I হলে IND বা NON বাধ্যতামূলক। সংখ্যাসূচক পোস্টাল কোড দিলে শুরুর শূন্যগুলো রাখুন।
| তথ্যের ঘর | ধরন/সর্বোচ্চ সীমা | শর্ত |
|---|---|---|
| recordId | Number(4) | আবশ্যিক;1 থেকে শুরু স্বতন্ত্র চলতি ক্রম |
| idType | String(1) | আবশ্যিক;1/2/5/6/A/I/U |
| idNumber | String(12) | আবশ্যিক; ধরনের সঙ্গে মেলা বৈধ পরিচয়;VCC উপ-তহবিলের ASGD |
| individualIndicator | String(3) | A/I ছাড়া ঐচ্ছিক;IND/NON |
| name | String(80) | আবশ্যিক |
| addressLine1 | String(30) | ঐচ্ছিক |
| addressLine2 | String(30) | ঐচ্ছিক |
| postalCode | String(6) | ঐচ্ছিক; অঙ্ক,শুরুর শূন্য রাখুন |
| donationAmount | Number(9) | আবশ্যিক; পূর্ণসংখ্যা,মূল রেকর্ডে অশূন্য |
| dateOfDonation | Number(8) | আবশ্যিক;YYYYMMDD |
| receiptNum | String(20) | আবশ্যিক; রসিদ/স্বতন্ত্র রেফারেন্স |
| typeOfDonation | String(1) | আবশ্যিক;O/S/A/L/P/H |
| namingDonation | String(1) | আবশ্যিক;Z/N/F |
অনুদানের অঙ্ক, শ্রেণি ও রাউন্ডিংয়ের অসংগতি
donationAmount সর্বোচ্চ নয় অঙ্কের পূর্ণসংখ্যা; খালি বা স্পেসযুক্ত হতে পারবে না। মূল রেকর্ডে শূন্য চলে না। উৎসে নিকটতম ডলারে রাউন্ড করতে বলা হলেও 101.20→102 উদাহরণ দেওয়া, যা স্বাভাবিক নিকটতম ডলারে রাউন্ডিংয়ের সঙ্গে অসংগত; PDF এই দ্বন্দ্ব মেটায় না, তাই বাস্তবায়নের আগে বর্তমান পরীক্ষার নির্দেশিকা বা IRAS-এর কাছে সঠিক আচরণ নিশ্চিত করুন। ধরন O নগদ,S শেয়ার/ইউনিট ট্রাস্ট,A শিল্পবস্তু,L জমি/ভবন,P প্রকাশ্য ভাস্কর্য,H Overseas Humanitarian Assistance Tax Deduction Scheme। S-এর জন্য দাতাকে NRIC, FIN, ASGD বা ITR ব্যবহার করতে হয়; A/I হলে IND-ও চাই। namingDonation-এর Z ডিফল্ট নামকরণবিহীন অনুদান,N দাতা বা নিকটাত্মীয় জীবিত সদস্যের নামে IPC,F দাতার নামে IPC-এর স্থাপনা।
সংশোধন দাতার বিদ্যমান রেকর্ড প্রতিস্থাপন করে
batchIndicator=O মূল এবং A সংশোধন বোঝায়। সংশোধন নির্দিষ্ট দাতার আগে জমা দেওয়া অনুদানের তথ্য প্রতিস্থাপন করে। উদাহরণে দাতার পরিচয়, অনুদানের তারিখ ও রসিদের রেফারেন্স একই রেখে S$100 থেকে S$50 করা হয়; সর্বশেষ S$50-ই IRAS-এর রেকর্ডকৃত অঙ্ক হয়। numOfRecords-কে দাতার রেকর্ডসংখ্যা এবং totalDonationAmount-কে জমা দেওয়া donationAmount-এর যোগফলের সঙ্গে মিলতে হবে। সফলভাবে গৃহীত অংশ আবার পাঠাতে নতুন মূল রেকর্ড ব্যবহার করবেন না।
শুধু শিরোনাম বা বার্তা নয়, রেসপন্স কোড পড়ুন
returnCode, acknowledgementCode ও messageCode হলো স্ট্রিং। কোড "10" প্রক্রিয়াকৃত এবং "30" প্রক্রিয়াকৃত নয় বোঝায়। সফল প্রকৃত জমায় প্রাপ্তিস্বীকার থাকে; সফল শুধু-যাচাইয়ে খালি data অবজেক্ট আসে এবং তা জমা নয়। "10"-এর সঙ্গে আগের ভিত্তিবছরের মতো সতর্কবার্তাও থাকতে পারে, তবু গৃহীত হয়। সতর্কতার উদাহরণে messageCode 850301 ও Arguments Error-ও আছে: শুধু ওই বার্তা নয়, returnCode ও প্রাপ্তিস্বীকার পরীক্ষা করুন। PDF-এর কিছু ত্রুটির উদাহরণে শিরোনামে সফল বলা হলেও আসল returnCode "30"। গৃহীত প্রাপ্তিস্বীকার রাখুন এবং ঘরভিত্তিক ত্রুটির জন্য info.fieldInfoList দেখুন; সংশ্লিষ্ট রেকর্ডের ID "3,5,7" আকারে একত্র হতে পারে।
ডায়াগনস্টিক কোড ও সমাধানযোগ্য অসংগতি
ছয় কোড হলো 850300 খালি অনুরোধ,850301 ভুল আর্গুমেন্ট,850302 সেবার ব্যতিক্রম,850303 নিষ্ক্রিয় সেবা,850304 অনুমোদনহীন পরিচয়প্রমাণ ও850305 অবৈধ স্যান্ডবক্স পরীক্ষামূলক ব্যবহারকারী। ঘরভিত্তিক ত্রুটিতে ঘরের নাম, বার্তা ও সংশ্লিষ্ট রেকর্ড নম্বর থাকে। সংস্করণ 1.4-এ অনুরোধের নাম recordId করা হলেও নমুনায় এখনও recordID, Boolean validateOnly-কে স্ট্রিং হিসেবে উদ্ধৃত এবং বিন্যাসের সারণির সঙ্গে অসংগত ASGD উদাহরণ আছে। অন্য ক্ষেত্রেও Info/info ও recordId/recordID-এর অক্ষরের পার্থক্য আছে; রেসপন্সের বর্ণনায় donationDtl বলা হলেও অনুরোধের অবজেক্ট donationDonorDtl। অক্ষরের ধরন ও তথ্যের ধরন গুরুত্বপূর্ণ বলে উদাহরণ অপরিবর্তিত কপি না করে বর্তমান নির্দিষ্টকরণ ও স্যান্ডবক্স পরীক্ষা দিয়ে এই অসংগতি মেটান।
সরকারি উৎস
এই প্রবন্ধে সরকারি PDF-এর মূল বিষয়বস্তু, প্রাসঙ্গিক শর্ত, পদ্ধতি ও সংযোজনীগুলো নিজস্বভাবে ব্যাখ্যা করা হয়েছে। মূল বক্তব্যের প্রামাণ্য উৎস হলো সংযুক্ত নথি; পরবর্তী পরিবর্তন আলাদাভাবে যাচাই করা উচিত।
সরকারি PDF পড়ুন ↗