Phiên bản và mục đích dịch vụ
Phiên bản 1.4 ngày 1 tháng 10 năm 2026 mô tả nộp hồ sơ quyên góp qua Corppass và nền tảng APEX. Bản đầu phát hành tháng 10 năm 2024; tháng 9 năm 2025 thêm lựa chọn đại lý thuế, tháng 12 đổi mã phản hồi thành chuỗi; tháng 4 năm 2026 sửa ví dụ, tháng 10 cập nhật recordId và giải thích số định danh người quyên góp, xóa mã ví dụ và cập nhật liên kết mở tài khoản. Đây là quy cách tích hợp API, không có nghĩa mọi khoản quyên góp đều đủ điều kiện khấu trừ thuế.
Đăng ký và ủy quyền cho nhà phát triển
Nhà phát triển cần có Corppass, được quản trị viên hoặc phó quản trị viên của tổ chức cấp quyền dịch vụ điện tử APEX Cloud. Sau đó tạo ứng dụng, tạo khóa API, tạo OAuth 2.1 client và đăng ký API cho ứng dụng. Khi đăng nhập lần đầu, cần cập nhật email để nhận thông báo ngừng dịch vụ và thay đổi. Lấy Corppass token qua OAuth 2.1, với scope ủy quyền DonationSub. Khi ủy quyền, tax_agent=y nghĩa là đại diện xử lý cho khách hàng doanh nghiệp; tax_agent=n nghĩa là xử lý thuế của chính tổ chức.
Thử nghiệm trước, rồi xin sử dụng môi trường chính thức
Đăng ký sandbox không cần IRAS chấp thuận, nhưng phải dùng thực thể thử nghiệm IRAS, OAuth 2.1 sandbox client và các tình huống trong hướng dẫn thử API quyên góp. Môi trường chính thức cần IRAS chấp thuận sau khi vượt qua thử nghiệm sandbox và phải tạo OAuth client chính thức. Chỉ dùng môi trường chính thức cho dịch vụ quy định, không thử nghiệm tại đó; vi phạm có thể bị đình chỉ hoặc chấm dứt tài khoản. Cả điều khoản sử dụng API IRAS và APEX đều áp dụng.
Điểm cuối, truyền tải và tiêu đề yêu cầu
Dùng POST https://sandbox.api.gov.sg/iras/donation-records/v1/Submit hoặc https://public.api.gov.sg/iras/donation-records/v1/Submit tùy môi trường. API kết nối giữa các máy chủ, bảo vệ bằng TLS và danh sách IP cho phép; ứng dụng phải hỗ trợ HTTP/2, TLS 1.2 hoặc 1.3, cùng HTTP GET và POST. x-apex-apikey là khóa của ứng dụng đã đăng ký; Authorization dùng Bearer kèm Corppass JWT; Content-Type là application/json. Ví dụ tiêu đề yêu cầu trong tài liệu vẫn có đường dẫn cũ /iras/prod/DonationCP/submit và HTTP/1.1, khác bảng điểm cuối hiện hành và yêu cầu truyền tải, nên không dùng làm đường dẫn API đã cập nhật.
Giới hạn bản ghi, nhận toàn bộ yêu cầu và thử lại
Mỗi yêu cầu tối đa 5.000 bản ghi và 2 MB; vượt bất kỳ giới hạn nào đều thất bại, chẳng hạn 4.000 bản ghi nhưng quá 2 MB, hoặc 5.001 bản ghi. Có thể chia 8.000 bản ghi thành hai yêu cầu 5.000 và 3.000, mỗi yêu cầu vẫn phải đạt giới hạn dung lượng. Không nhận một phần trong cùng yêu cầu: mọi bản ghi phải qua kiểm tra. Nếu yêu cầu 3.500 bản ghi thành công nhưng yêu cầu 1.500 bản ghi khác thất bại, chỉ sửa và gửi lại yêu cầu thất bại. Mỗi ứng dụng tối đa 1.000 yêu cầu mỗi giờ; khi nhận HTTP 429 và Assembly Rate Limit exceeded, thử lại vào giờ tiếp theo.
Chữ hoa/thường, ký tự và kiểu trường
Tên JSON phân biệt chữ hoa/thường và thường theo camelCase. Phải có thuộc tính bắt buộc; ngoại lệ tùy chọn được ghi trong bảng trường. Chuỗi ngày theo ISO 8601, nhưng dateOfDonation được quy định riêng là số tám chữ số YYYYMMDD. Độ dài chuỗi là giới hạn tối đa; Number(n) là số nguyên tối đa n chữ số. Cho phép ASCII 32–127, ü, Ü, İ, xuống dòng LF và CR, gạch ngang en/em, cùng dấu ngoặc kép và nháy đơn cong; ký tự khác có thể làm kiểm tra thất bại.
Đối tượng thông tin tổ chức và lần nộp
orgAndSubmissionInfo chứa định danh IPC, người được ủy quyền và thông tin tổng hợp. basisYear là năm nhận quyên góp, chấp nhận ba năm trước, năm hiện tại và năm kế tiếp. organisationIDType nhận 5, 6, U, A, I, với định dạng tương ứng NNNNNNNNC, YYYYNNNNNC, TYYPQNNNNC hoặc SYYPQNNNNC, ANNNNNNNC và NNNNNNNNNC. C là ký tự kiểm tra, N là chữ số, Y là phần năm. Người nộp dùng NRIC bắt đầu S hoặc T, FIN bắt đầu F, G hoặc M, ASGD hoặc ITR. validateOnly=true chỉ kiểm tra, không nộp; false kiểm tra và nộp. Bảng dưới giữ độ dài và yêu cầu bắt buộc của trường.
| Trường | Kiểu/giới hạn | Yêu cầu |
|---|---|---|
| validateOnly | Boolean | Bắt buộc; true chỉ kiểm tra, false nộp |
| basisYear | Number(4) | Bắt buộc; năm nhận, ba năm trước/năm hiện tại/năm sau |
| organisationIDType | String(1) | Bắt buộc; 5/6/U/A/I |
| organisationIDNo | String(12) | Bắt buộc; đúng định dạng định danh |
| organisationName | String(60) | Bắt buộc |
| batchIndicator | String(1) | Bắt buộc; O/A |
| authorisedPersonIDNo | String(12) | Bắt buộc; NRIC/FIN/ASGD/ITR |
| authorisedPersonName | String(30) | Bắt buộc |
| authorisedPersonDesignation | String(30) | Tùy chọn |
| telephone | String(20) | Bắt buộc; ít nhất tám chữ số |
| authorisedPersonEmail | String(50) | Bắt buộc |
| numOfRecords | Number(7) | Bắt buộc; số lượng bản ghi là số nguyên |
| totalDonationAmount | Number(12) | Bắt buộc; tổng donationAmount |
Bản ghi người quyên góp và yêu cầu định danh đặc biệt
donationDonorDtl chứa các bản ghi người quyên góp; bảng trường ghi Object nhưng ví dụ thực tế dùng mảng. recordId bắt đầu từ 1 và phải là số thứ tự duy nhất. idType nhận 1 (NRIC), 2 (FIN), 5 (UEN doanh nghiệp), 6 (UEN công ty trong nước), A (ASGD), I (ITR) hoặc U (UEN khác), đúng định dạng định danh tương ứng, kể cả FIN bắt đầu M. Thực thể quỹ phụ VCC phải dùng ASGD do IRAS cấp. individualIndicator thường tùy chọn, nhưng loại A hoặc I phải điền IND hoặc NON. Nếu có mã bưu chính, dùng chuỗi chữ số và giữ số 0 đầu.
| Trường | Kiểu/giới hạn | Yêu cầu |
|---|---|---|
| recordId | Number(4) | Bắt buộc; số thứ tự duy nhất bắt đầu từ 1 |
| idType | String(1) | Bắt buộc; 1/2/5/6/A/I/U |
| idNumber | String(12) | Bắt buộc; khớp loại, quỹ phụ VCC dùng ASGD |
| individualIndicator | String(3) | A/I bắt buộc, loại khác tùy chọn; IND/NON |
| name | String(80) | Bắt buộc |
| addressLine1 | String(30) | Tùy chọn |
| addressLine2 | String(30) | Tùy chọn |
| postalCode | String(6) | Tùy chọn; chuỗi chữ số, giữ số 0 đầu |
| donationAmount | Number(9) | Bắt buộc; số nguyên, bản ghi gốc không bằng 0 |
| dateOfDonation | Number(8) | Bắt buộc; YYYYMMDD |
| receiptNum | String(20) | Bắt buộc; biên nhận hoặc tham chiếu duy nhất |
| typeOfDonation | String(1) | Bắt buộc; O/S/A/L/P/H |
| namingDonation | String(1) | Bắt buộc; Z/N/F |
Số tiền, loại quyên góp và hướng dẫn làm tròn không nhất quán
donationAmount phải là số nguyên tối đa chín chữ số, không để trống hoặc có khoảng trắng; bản ghi gốc không bằng 0. Tài liệu ghi làm tròn đến một đô la gần nhất nhưng lại ví dụ 101,20 thành 102, không nhất quán với làm tròn thông thường; PDF chưa giải quyết mâu thuẫn này, nên đối chiếu hướng dẫn thử nghiệm mới nhất hoặc xác nhận với IRAS trước triển khai. Loại quyên góp: O tiền mặt, S cổ phiếu hoặc quỹ tín thác đơn vị, A hiện vật, L đất hoặc tòa nhà, P điêu khắc công cộng, H Overseas Humanitarian Assistance Tax Deduction Scheme. Loại S chỉ nhận NRIC, FIN, ASGD hoặc ITR; định danh A hoặc I cũng phải đánh dấu IND. namingDonation=Z là mặc định không đặt tên; N là IPC đặt theo tên người quyên góp hoặc thành viên gia đình trực tiếp còn sống (immediate family member) của họ; F là cơ sở của tổ chức đặt theo tên người quyên góp.
Bản ghi sửa thay thế thông tin trước đó
batchIndicator=O là bản ghi gốc, A là sửa. Bản sửa thay thế thông tin quyên góp đã nộp trước đó của người quyên góp liên quan. Ví dụ giữ cùng số định danh, ngày quyên góp và số tham chiếu biên nhận, đổi S$100 thành S$50; IRAS dùng bản ghi S$50 mới nhất. numOfRecords phải khớp số bản ghi quyên góp; totalDonationAmount phải bằng tổng các donationAmount. Không nộp gốc lần nữa để lặp những yêu cầu chia lô đã được nhận thành công.
Xem mã phản hồi, không chỉ xem tiêu đề hoặc thông báo
returnCode, acknowledgementCode và messageCode đều là chuỗi. Mã "10" nghĩa là đã xử lý, "30" là chưa xử lý. Nộp thành công thực sự có mã xác nhận; phản hồi kiểm tra thành công chỉ có đối tượng data rỗng, không có nghĩa đã khai nộp. "10" có thể kèm cảnh báo như năm trước nhưng vẫn thành công. Ví dụ cảnh báo thậm chí có 850301 và Arguments Error, nên xem returnCode và mã xác nhận, không chỉ thông báo đó. PDF cũng có nhiều ví dụ lỗi với mã thực tế "30" nhưng tiêu đề gọi là thành công. Lưu mã xác nhận được nhận và kiểm tra lỗi trường ở info.fieldInfoList; có thể gộp số bản ghi liên quan thành "3,5,7".
Mã chẩn đoán và những khác biệt cần kiểm tra trước triển khai
Sáu mã lần lượt là 850300 yêu cầu rỗng, 850301 lỗi tham số, 850302 ngoại lệ dịch vụ, 850303 dịch vụ chưa kích hoạt, 850304 thông tin xác thực không có quyền và 850305 người dùng thử sandbox không hợp lệ. Chẩn đoán trường liệt kê trường, mô tả và số bản ghi liên quan. Phiên bản 1.4 cập nhật tên yêu cầu thành recordId, nhưng ví dụ vẫn dùng recordID, viết Boolean validateOnly thành chuỗi và đưa ví dụ ASGD không khớp bảng định dạng. Nơi khác lẫn Info/info, recordId/recordID; mô tả phản hồi ghi donationDtl nhưng đối tượng yêu cầu là donationDonorDtl. Chữ hoa/thường và kiểu dữ liệu ảnh hưởng API, nên giải quyết các khác biệt theo quy cách mới nhất và thử sandbox, không sao chép nguyên ví dụ.
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 ↗