Mục đích và lịch sử phiên bản
Bản 1.2 cập nhật ngày 1 tháng 11 năm 2021 mô tả API hồ sơ hoa hồng xác thực Corppass, cho nhà cung cấp phần mềm và tổ chức trả hoa hồng kiểm tra/nộp để điền sẵn tờ khai thuế cá nhân người nhận. Bản 1.0 bắt đầu ngày 15 tháng 12 năm 2020; 1.1 ngày 6 tháng 4 năm 2021 thêm phương thức điểm cuối; 1.2 thêm kiểm tra FIN loạt M. Đây là quy cách API lịch sử, không có nghĩa mọi điểm cuối và giao diện cổng luôn không đổi.
Tài khoản nhà phát triển, tên tổ chức và ứng dụng
Tạo tài khoản nhà phát triển riêng cho chợ API thử nghiệm và chính thức, kích hoạt qua email hệ thống. Đăng nhập rồi vào Username > My Organization > Edit organization, dùng tên tổ chức thực kèm gạch dưới và ROC hoặc UEN phù hợp. Đăng ký ứng dụng qua Apps > Register New Application; App Title là tên khách hàng thấy khi đồng ý cho ứng dụng gọi API. Chọn Submission of Commission Records (Corppass) trong API Products, đăng ký và chọn ứng dụng đó. Các bước tài khoản chi tiết ở hướng dẫn API chung được nguyên bản liên kết.
Chứng cứ thử nghiệm và chấp thuận môi trường chính thức
Phải thử sandbox trước và đồng thời đăng ký Corppass Authentication API. Đăng ký sandbox tự nó không cần IRAS chấp thuận, nhưng phải dùng tình huống và thực thể thử IRAS công bố. Nộp thử thành công trả mã xác nhận; gửi mã từng tình huống đến data_mgmt@iras.gov.sg để xác minh. Qua thử nghiệm mới đăng ký dịch vụ chính thức và được IRAS chấp thuận. Môi trường chính thức chỉ dùng mục đích thực mà dịch vụ mô tả, cấm thử nghiệm hoặc dùng khác; vi phạm điều khoản có thể bị đình chỉ hoặc chấm dứt.
Kết nối máy chủ, điểm cuối và tiêu đề yêu cầu
Kết nối giữa máy chủ phải hỗ trợ HTTP/2, TLS 1.2 hoặc 1.3 và HTTP GET/POST. Phương thức hoa hồng là POST /CommissionCP/submit; địa chỉ cơ sở thử là https://apisandbox.iras.gov.sg/iras/sb, chính thức là https://apiservices.iras.gov.sg/iras/prod. Tiêu đề gồm X-IBM-Client-Id, X-IBM-Client-Secret, access_token và Content-Type: application/json. Lấy JWT theo quy cách Corppass Authentication riêng; token được để trống khi validateOnly=true, nhưng thông tin xác thực ứng dụng vẫn áp dụng. Mẫu tiêu đề dùng HTTP/1.1 trong khi yêu cầu mạng ghi HTTP/2; lưu ý khác biệt khi kiểm tra yêu cầu cổng thực tế.
Giới hạn dữ liệu và quy ước trường
Mỗi yêu cầu tối đa 5.000 bản ghi hoặc tổng 2 MB, giới hạn nào đạt trước. JSON phân biệt chữ hoa/thường, tên thuộc tính theo camelCase; phải có mọi thuộc tính trừ khi ghi tùy chọn. Chuỗi ngày thông thường theo ISO 8601, nhưng dateOfBirth quy định riêng là số tám chữ số YYYYMMDD. Chuỗi cho chữ cái tiếng Anh, số, khoảng trắng và dấu liệt kê: dấu huyền ngược, @, #, ngoặc, gạch nối, phẩy, chấm, gạch chéo, &, + và gạch dưới. String(n) là tối đa ký tự; Number(n) là số chữ số nguyên. Theo kiểu trường cụ thể, không đổi mọi số thành chuỗi.
Chế độ kiểm tra và năm cơ sở
Yêu cầu gồm orgAndSubmissionInfo và commissionEarnerDtl. validateOnly phải là Boolean true hoặc false: true chỉ kiểm tra không khai nộp; false kiểm tra và nộp. basisYear là năm phát sinh thu nhập, không phải năm tính thuế: YA2021 tương ứng 2020. Quy cách cho hai năm trước, năm hiện tại và một năm sau. Lô gốc dùng O, sửa dùng A; số bản ghi và tổng hoa hồng phải khớp chi tiết người nhận trong yêu cầu.
Định danh tổ chức và người nộp
Loại ID tổ chức là 7 UEN-BUSINESS, 8 UEN-LOCAL CO, U UEN-OTHERS, A ASGD và I ITR. Định dạng tương ứng NNNNNNNNC, YYYYNNNNNC, TYYPQNNNNC hoặc SYYPQNNNNC, ANNNNNNNC và NNNNNNNNNC; C là ký tự kiểm tra, N là số, Y là năm. Người nộp dùng 1 NRIC, 2 FIN hoặc A ASGD; NRIC bắt đầu S/T, FIN F/G/M. Bảng giữ trường tổ chức/người nộp, độ dài tối đa và chức danh tùy chọn; điện thoại ít nhất tám chữ số.
| Trường | Kiểu và giới hạn | Yêu cầu |
|---|---|---|
| validateOnly | Boolean | true chỉ kiểm tra, false kiểm tra và nộp |
| basisYear | Number(4) | Năm thu nhập; hai năm trước/năm hiện tại/năm sau |
| organisationIDType | String(1) | 7, 8, U, A, I |
| organisationIDNo | String(12) | Số định danh tổ chức khớp loại |
| authorisedPersonIDType | String(1) | 1, 2, A |
| authorisedPersonIDNo | String(12) | NRIC, FIN hoặc ASGD |
| authorisedPersonName | String(30) | Tên người nộp |
| authorisedPersonDesignation | String(30) | Chức danh tùy chọn |
| organisationName | String(60) | Tên tổ chức |
| telephone | String(20) | Ít nhất tám chữ số |
| authorisedPersonEmail | String(50) | |
| batchIndicator | String(1) | O bản gốc, A sửa |
| numOfRecords | Number(4) | Số bản ghi nguyên |
| totalGrossCommission | Number(15) | Tổng hoa hồng là số nguyên |
Định danh người nhận và trường cá nhân có điều kiện
recordID bắt đầu 1 và duy nhất. idType người nhận cho 1 NRIC, 2 FIN, 5 căn cước Malaysia, 6 hộ chiếu, 7 UEN doanh nghiệp, 8 UEN công ty trong nước, A ASGD, I ITR hoặc U UEN khác. Căn cước Malaysia gồm bảy/tám ký tự chữ-số hoặc 12 chữ số. Loại 1, 2, 5, 6 phải có quốc tịch, giới tính, nghề và ngày sinh; ví dụ công ty không có các trường cá nhân đó. Mã quốc tịch thường gặp: 301 công dân Singapore, 304 Malaysia, 336 Trung Quốc; mã khác xem danh sách đính kèm. Bảng ghi commissionEarnerDtl là Object nhưng ví dụ yêu cầu rõ ràng dùng mảng đối tượng người nhận.
| Trường | Kiểu và giới hạn | Yêu cầu |
|---|---|---|
| recordID | Number(4) | Bắt đầu 1, phải duy nhất |
| idType | String(1) | 1, 2, 5, 6, 7, 8, A, I, U |
| idNumber | String(12) | Số định danh tương ứng |
| name | String(80) | Tên người nhận |
| nationality | Number(3) | Bắt buộc với loại 1, 2, 5, 6 |
| sex | String(1) | Loại 1, 2, 5, 6 dùng F hoặc M |
| designation | Number(1) | Loại 1, 2, 5, 6 dùng 1–9 |
| dateOfBirth | Number(8) | Loại 1, 2, 5, 6 dùng YYYYMMDD |
| grossCommission | Number(12) | Không thập phân/khoảng trắng, không bằng 0 |
Chín mã nghề và số tiền hoa hồng
Mã nghề là 1 đại diện giao dịch chứng khoán, 2 môi giới bất động sản, 3 đại lý bảo hiểm, 4 nhà phân phối, 5 tư vấn tài chính, 6 người hướng dẫn, 7 chuyên viên trị liệu, 8 nhà bán lẻ Singapore Pools, 9 khác. Giới tính F/M. grossCommission là số, không khoảng trắng/thập phân và không bằng 0; ví dụ S$150.000,55 gửi 150000, tức bỏ phần lẻ. Tổng lô cũng chỉ nhận số nguyên. Mô tả UEN-OTHERS của người nhận dùng TyyPQnnnnC hoặc SyyPQnnnnC, còn trường tổ chức dùng TYYPQNNNNC hoặc SYYPQNNNNC. Hai cách viết này đều có 10 ký tự, chỉ khác chữ hoa/thường của ký hiệu mẫu; nhận định độ dài khác nhau trong bài tiếng Trung không đúng. Giữ cả cách viết nguyên bản và kiểm tra theo quy tắc định danh có thẩm quyền, không tự suy ra một định dạng khác.
Mã trả về và chẩn đoán lỗi
returnCode=10 nghĩa là xử lý thành công, 30 là thất bại. data chứa kết quả, info chứa chẩn đoán. messageCode 850300 là yêu cầu rỗng, 850301 lỗi tham số, 850302 ngoại lệ chung dịch vụ, 850303 dịch vụ dừng, 850304 thông tin xác thực không có quyền, 850305 người thử sandbox không hợp lệ. fieldInfoList liệt kê trường, mô tả và recordID bị ảnh hưởng; số người nhận cùng lỗi có thể gộp thành chuỗi phẩy như 3,5,7. Chỉ lỗi đối tượng người nhận mới có recordID. Bảng lẫn info/Info dù quy cách nói camelCase, nên theo cấu trúc phản hồi thực phân biệt hoa/thường.
Phân biệt xác nhận nộp với kiểm tra thành công
Phản hồi thành công validateOnly=false có data.acknowledgementCode, returnCode10 và fieldInfoList rỗng. Chỉ kiểm tra thành công có data rỗng, không chứng minh đã khai nộp. Thất bại trả 30 và chẩn đoán như sai loại/số ID, thiếu tên, kèm bản ghi. Mô tả trường trang 15 lại có chứng nhận thuế tem và tọa độ vĩ độ, không khớp dịch vụ hoa hồng và ví dụ phản hồi. Hiểu acknowledgementCode theo ví dụ là mã xác nhận nộp hoa hồng, không là dữ liệu địa lý.
Ví dụ và quy trình truyền C#
Ví dụ yêu cầu có thông tin tổ chức và hai bản ghi người nhận: một thể nhân có trường cá nhân và một công ty, hoa hồng lần lượt 2000 và 3000, tổng lô 5000. Ví dụ yêu cầu và phản hồi thành công có dấu phẩy cuối, không là JSON nghiêm ngặt hợp lệ; tạo bằng bộ tuần tự hóa JSON thay vì sao chép thẳng. Ví dụ C# tạo POST, đặt kiểu nội dung JSON cùng ba tiêu đề thông tin xác thực/token, ghi JSON vào luồng yêu cầu, đọc phản hồi và đọc thân lỗi có thể có khi WebException. Đây chỉ minh họa truyền tải, không thay chấp thuận sandbox, kiểm tra dữ liệu hoặc xác thực riêng. Chú thích dẫn 3.1.1, nhưng trường yêu cầu thực ở 4.2.
Nguồn chính thức
Bản dịch tiếng Việt giữ đầy đủ nội dung bài viết tiếng Trung, gồm mọi điều kiện, bước, bảng và phụ lục trong phạm vi bài; các thông tin thực chất được đối chiếu PDF chính thức bằng tiếng Anh. Đây không phải bản dịch nguyên văn toàn bộ mọi tài liệu được liên kết. Xem bản gốc để kiểm cách diễn đạt, ngày và cập nhật về sau.
Xem PDF gốc chính thức ↗