用途与版本沿革
2021年11月1日更新的1.2版说明经过Corppass验证的佣金记录API，供软件供应商及佣金支付机构验证和提交资料，并预填佣金收入者的个人税表。1.0版始于2020年12月15日，1.1版于2021年4月6日加入端点方法，1.2版加入FIN的M系列验证。这是历史接口规范，不代表所有端点及门户画面一直没有变化。
开发者账户、机构名称及应用
分别为测试及生产API市场建立开发者账户，并经系统电邮激活。登录后进入Username > My Organization > Edit organization，以实际机构名称加下划线，接适用ROC或UEN识别。经Apps > Register New Application注册应用，App Title是客户同意应用调用API时看到的名称。再从API Products选择Submission of Commission Records (Corppass)，订阅并选定该应用。账户详细步骤见原文链接的一般API指南。
测试证据与生产批准
须先在sandbox测试，并同时订阅Corppass Authentication API。Sandbox订阅本身不须IRAS批准，但须使用IRAS公布的测试情景和实体。成功测试提交会返回确认码，须把各情景确认码交[email protected]核实。通过测试后，才可订阅生产服务并取得IRAS批准。生产环境仅供服务说明的实际用途，禁止测试及其他用途，违反API条款可能导致暂停或终止。
服务器连接、端点与请求头
须以服务器对服务器连接，支持HTTP/2、TLS1.2或1.3，以及HTTP GET和POST。佣金方法是POST /CommissionCP/submit，测试基地址为https://apisandbox.iras.gov.sg/iras/sb，生产基地址为https://apiservices.iras.gov.sg/iras/prod。请求头包括X-IBM-Client-Id、X-IBM-Client-Secret、access_token及Content-Type: application/json。JWT令牌按独立Corppass Authentication规范取得；validateOnly=true时令牌可留空，但客户凭证仍适用。原文请求头示例用HTTP/1.1，网络要求却列HTTP/2；查阅实际网关要求时须留意两处差别。
载荷限制与字段约定
每个请求最多5,000条记录或总计2MB，以先达到者为准。JSON区分大小写，属性名称采用camelCase。除明确可选外，每个属性都须提供。一般日期字符串用ISO8601，但dateOfBirth明确是八位数值YYYYMMDD。字符串允许英文字母、数字、空格及所列标点：反引号、@、#、括号、连字符、逗号、句点、斜线、&、+和下划线。String(n)表示最多字符数，Number(n)说明整数位数。应遵守具体字段类型，而不是把所有数字转成字符串。
验证模式与基础年
请求包括orgAndSubmissionInfo和commissionEarnerDtl。validateOnly须为布尔值true或false；true仅验证而不申报，false验证并提交。basisYear是收入产生年度，不是课税年，因此YA2021对应2020。规范容许服务年度前两年、当年及后一年。原始批次用O，修正批次用A；申报记录数及总佣金应对应该请求内收入者明细。
机构识别与提交人资料
机构ID类型为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) | 至少八位数字 |
| 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。马来西亚身份证格式为七或八位字母数字，或十二位数字。类型1、2、5、6须提供国籍、性别、职业类别和出生日期，公司示例没有这些个人字段。常见国籍码为301新加坡公民、304马来西亚、336中国，其他代码见另附名单。字段表把commissionEarnerDtl写为Object，但请求示例清楚使用收入者对象数组。
| 字段 | 类型及限制 | 要求 |
|---|---|---|
| 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) | 无小数或空格，不得为零 |
九项职业码及佣金金额
职业码为1证券交易代表、2房地产代理、3保险代理、4分销商、5财务顾问、6导师、7治疗师、8Singapore Pools零售商及9其他。性别用F或M。grossCommission须为数字、无空格、无小数且不得为零；原文S$150,000.55示例传150000，即舍去分。批次总额也仅接受整数。收入者UEN-OTHERS描述用TyyPQnnnnC或SyyPQnnnnC，但机构字段用TYYPQNNNNC或SYYPQNNNNC；字符数有差异，应保留原文并按权威识别规则验证，不能从这处不一致自行推定统一格式。
返回码及错误诊断
returnCode为10表示处理成功，30表示失败。data存服务结果，info存诊断。messageCode850300为请求空值，850301为参数错误，850302为服务一般异常，850303为服务停用，850304为凭证没有授权，850305为无效sandbox测试用户。fieldInfoList列受影响字段、说明及recordID；相同错误的收入者编号可合并成3,5,7这类逗号分隔字符串，只有收入者对象错误才有recordID。字段表混用info与Info大小写，但规范又规定camelCase，应遵循实际区分大小写的回应结构。
提交确认与验证成功须区分
validateOnly=false成功回应含data.acknowledgementCode、returnCode10及空fieldInfoList。仅验证成功则data为空对象，不能证明已经申报。失败时返回30及诊断，例如ID类型或号码错误、姓名缺失，并注明记录。第15页字段说明出现印花税证书及纬度文字，与佣金服务及回应示例不一致。acknowledgementCode应按示例理解为佣金提交确认码，而不是地理数据。
示例与C#传输流程
请求示例包括机构资料和两条收入者记录：一名有个人资料的自然人及一家公司，佣金分别2000和3000，批次合计5000。请求及成功回应示例有尾随逗号，不是严格有效JSON，应以JSON序列化生成而非直接照抄。C#示例建立POST请求，设置JSON内容类型及三个凭证令牌请求头，向请求流写入JSON，读取回应，并在WebException时读取可能返回的错误正文。这仅示范传输，不能替代sandbox批准、载荷验证或独立认证流程。示例注释引用3.1.1，但本文件请求字段实际在4.2。
官方来源
本文依据官方 PDF 的实质内容独立整理，涵盖相关条件、办理步骤及附录。原文链接用于核对官方措辞；文件日期与后续修订须另行确认。
查看官方 PDF 原文 ↗