版本与服务用途
2026年10月1日的1.4版本，说明通过Corppass及APEX平台提交捐赠记录。初版于2024年10月发布；2025年9月加入税务代理选择，12月将响应代码改为字符串；2026年4月修订示例，10月更新recordId及捐赠者身份号码说明、移除示例代码并刷新开户链接。这是接口整合规范，不代表每项捐赠均符合税务扣除资格。
开发者登记与授权
开发者须具备Corppass，由所属机构的管理员或副管理员授予APEX Cloud电子服务权限。随后创建应用、生成API密钥、创建OAuth 2.1客户端，并为应用订阅接口。首次登入时应更新电邮，以接收停机及变更通知。通过OAuth 2.1取得Corppass令牌，授权scope为DonationSub。授权时，tax_agent=y表示为企业客户代理处理，tax_agent=n表示处理本机构税务。
先测试，再申请正式使用
订阅沙盒无须IRAS批准，但须使用IRAS测试实体、OAuth 2.1沙盒客户端及捐赠接口测试指南中的情景。正式环境须在通过沙盒测试后取得IRAS批准，并创建正式OAuth客户端。正式环境只用于规定服务，不得进行测试，否则可因违反条款而暂停或终止账户。IRAS接口及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，超过任何一项均失败，例如4,000条但超过2 MB，或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、短长破折号，以及弯双引号和单引号；其他字符可导致校验失败。
机构及提交资料对象
orgAndSubmissionInfo包含公益机构身份、获授权人士及合计资料。basisYear为收取捐赠的年度，可接受前三年、当年及后一年度。organisationIDType可用5、6、U、A、I，对应格式为NNNNNNNNC、YYYYNNNNNC、TYYPQNNNNC或SYYPQNNNNC、ANNNNNNNC，以及NNNNNNNNNC。C为校验位，N为数字，Y为年份部分。提交人士可用S或T开头NRIC、F或G或M开头FIN、ASGD或ITR。validateOnly=true只作校验，不提交；false则校验并提交。下表保留字段长度及必填要求。
| 字段 | 类型/上限 | 要求 |
|---|---|---|
| validateOnly | Boolean | 必填；true仅校验，false提交 |
| basisYear | Number(4) | 必填；收取年度，前三年/当年/后一年 |
| 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) | 必填；最少八位数字 |
| authorisedPersonEmail | String(50) | 必填 |
| numOfRecords | Number(7) | 必填；记录数量整数 |
| totalDonationAmount | Number(12) | 必填；donationAmount合计 |
捐赠者记录及特殊身份要求
donationDonorDtl包含捐赠者记录；字段表虽标为Object，示例实际使用数组。recordId从1开始，须为唯一流水号。idType可用1（NRIC）、2（FIN）、5（商业UEN）、6（本地公司UEN）、A（ASGD）、I（ITR）或U（其他UEN），并须符合对应身份格式，包括M开头FIN。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海外人道援助税务扣除计划。S类别只接受NRIC、FIN、ASGD或ITR；A或I身份亦须标为IND。namingDonation的Z表示默认非冠名，N表示公益机构以捐赠者或其在世直系家属命名，F表示机构设施以捐赠者命名。
更正记录覆盖原有资料
batchIndicator=O表示原始记录，A表示更正。更正会覆盖有关捐赠者此前提交的捐赠资料。示例保留同一身份号码、捐赠日期及收据参考号，将100新加坡元改为50元，IRAS便以最新50元记录。numOfRecords须与捐赠记录数量一致，totalDonationAmount须等于各donationAmount之和。不要另作原始提交来重复已经成功接受的分批请求。
应看响应代码，不要只看标题或提示
returnCode、acknowledgementCode及messageCode均为字符串。代码"10"表示已处理，"30"表示未处理。真正成功提交带有确认码；只作校验的成功响应则为data空对象，不代表已申报。"10"可以附带早前年度等警告，但仍属成功。警告示例甚至带有850301及Arguments Error，因此应看returnCode和确认码，而不是单独看该提示。PDF亦有多个实际代码"30"的错误例子，却被标题称为成功。应保存已接受确认码，并检查info.fieldInfoList字段错误；相关记录号码可合并为"3,5,7"。
诊断代码与实施前须核对的不一致
六项代码分别为850300空请求、850301参数错误、850302服务异常、850303服务未启用、850304凭证无权限，以及850305沙盒测试用户无效。字段诊断列出字段、说明及有关记录号码。1.4版本把请求名称更新为recordId，但示例仍用recordID，亦将布尔validateOnly写成字符串，并提供与格式表不一致的ASGD示例。其他位置有Info与info、recordId与recordID混用，响应说明亦写donationDtl，而请求对象为donationDonorDtl。由于大小写和类型会影响接口，须按最新规范及沙盒测试解决这些差异，不应直接照抄示例。
官方来源
本文依据官方 PDF 的实质内容独立整理，涵盖相关条件、办理步骤及附录。原文链接用于核对官方措辞；文件日期与后续修订须另行确认。
查看官方 PDF 原文 ↗