Aplikasi Web Tersuai & Middleware LHDN
Seni Bina Laman Web LHDN MyInvois: Cara Checkout Dalam Talian Menjana e-Invois Patuh
Pecahan teknikal bagaimana checkout e-Dagang mengesahkan TIN/BRN pembeli, menyambung ke API LHDN MyInvois, dan menjana kod QR disahkan.
Transformasi e-Invois LHDN: Realiti Baharu e-Dagang Malaysia
Penguatkuasaan mandat e-Invois Lembaga Hasil Dalam Negeri (LHDN / hasil.gov.my) telah mengubah secara asas cara platform e-dagang dan laman web korporat di Malaysia mengendalikan transaksi checkout pelanggan.
Hari-hari di mana laman web anda sekadar menghantar fail resit PDF biasa melalui e-mel selepas pembayaran FPX atau kad kredit telah berakhir — sekurang-kurangnya bagi perniagaan yang tergolong dalam skop mandat. Mandat e-Invois telah dilaksanakan secara berperingkat mengikut perolehan tahunan sejak Ogos 2024, dan menjelang 2026 merangkumi perniagaan sehingga ambang RM1 juta perolehan tahunan; perniagaan di bawah ambang itu masih dikecualikan (walaupun boleh menyertai secara sukarela) (Crowe Malaysia — Garis Masa Pelaksanaan e-Invois Terkini). Bagi perniagaan yang tergolong dalam skop, setiap transaksi mesti didokumenkan dalam struktur data elektronik piawai UBL 2.1 (Universal Business Language) berasaskan format XML atau JSON, dan divalidasi secara masa nyata oleh sistem pelayan berpusat LHDN.
Bagi perniagaan B2B dan transaksi nilai tinggi B2C, kegagalan menyediakan e-Invois yang disahkan berserta kod QR rasmi boleh menyebabkan pelanggan korporat anda tidak dapat menuntut potongan cukai perniagaan yang sah, sekali gus menjejaskan jualan perniagaan anda.
Berikut adalah pecahan seni bina kejuruteraan (architectural breakdown) bagaimana proses checkout laman web moden disepadukan secara selamat dengan API LHDN MyInvois.
Gambar Rajah Seni Bina: Aliran Data Checkout ke API MyInvois
Menyambungkan proses checkout e-dagang terus ke API MyInvois secara sekegerak (synchronous blocking call) adalah kesilapan seni bina yang amat berbahaya. Jika pelayan LHDN mengalami kependaman (latency) atau penyelenggaraan sistem, pelanggan anda akan mengalami ralat tamat masa (timeout) dan pesanan gagal disempurnakan.
Oleh itu, seni bina perusahaan mesti menggunakan corak Baris Gilir Mesej Tak Segerak (Asynchronous Message Queue Pattern):
+------------------+ (1) Submit Order & Tax Info +-------------------------------+
| | ─────────────────────────────────────> | |
| Pelanggan Web | | Platform Web (Woo / Next.js) |
| (Pelayar/Mobile) | <───────────────────────────────────── | |
+------------------+ (2) Pengesahan Bayaran Segera +-------------------------------+
│
│ (3) Dispatch Job
▼
+-------------------------------+
| Sistem Baris Gilir (Queue) |
| (Redis / BullMQ / DB Queue) |
+-------------------------------+
│
│ (4) Worker Process
▼
+-------------------------+ (5) OAuth 2.0 & UBL Payload +-------------------------------+
| | <────────────────────────────── | |
| Pelayan LHDN MyInvois | | Middleware Integrasi LHDN |
| (api.myinvois.hasil.gov)| ──────────────────────────────> | |
+-------------------------+ (6) UUID & Validated QR +-------------------------------+
│
│ (7) Kemas Kini Status
▼
+-------------------------------+
| Pangkalan Data Pesanan & |
| Hantar E-mel Berserta Kod QR |
+-------------------------------+
4 Fasa Aliran Kejuruteraan Transaksi e-Dagang
Fasa 1: Pengesahan Input Pembeli Pada Halaman Checkout
Pada halaman pembayaran, borang checkout mesti menyokong medan data tambahan khusus yang diwajibkan oleh LHDN:
- TIN Pembeli (Tax Identification Number): Nombor pengenalan cukai LHDN (contoh: format
C25891234020untuk syarikat atauIG10234567080untuk pembayar cukai individu). - Nombor Pendaftaran Perniagaan (BRN): Format nombor SSM 12-digit baharu untuk entiti korporat Malaysia (contoh:
202401012345). - Nombor Pendaftaran SST: Sekiranya pembeli menuntut pengecualian atau pengkreditan cukai perkhidmatan 8%.
- Alamat E-mel & Nombor Telefon: Digunakan untuk pemberitahuan status dokumen oleh LHDN.
Sistem checkout mesti melaksanakan fungsi pengesahan format (regex validation) di bahagian klien dan pelayan sebelum pesanan dihantar ke gerbang pembayaran:
// Contoh fungsi pengesahan format TIN & SSM di bahagian pelayan
export function validateMalaysianTaxIdentifiers(tin: string, brn: string): boolean {
// Corak nombor TIN LHDN: [C|IG|OG|PT] diikuti digit berangka
const tinRegex = /^(C|IG|OG|PT|TC|CS|TR|D)d{10,11}$/;
// Corak nombor pendaftaran perniagaan SSM baharu (12 digit)
const ssmRegex = /^d{12}$/;
return tinRegex.test(tin.trim()) && ssmRegex.test(brn.trim());
}
Fasa 2: Pembayaran Berjaya & Pengkapsulan Dokumen UBL 2.1
Sebaik sahaja pelanggan melengkapkan pembayaran melalui FPX, kad kredit, atau DuitNow QR (melalui gerbang pembayaran seperti Curlec, senangPay, atau Stripe), sistem menyimpan pesanan dengan status Payment Received dan mencipta rekod tugas dalam baris gilir latar belakang.
Pekerja baris gilir (queue worker) menyusun maklumat pesanan ke dalam format dokumen standard JSON UBL 2.1 MyInvois:
- Kod Klasifikasi Produk/Perkhidmatan (Product Classification Code): Setiap item pesanan mesti dipetakan ke kod klasifikasi LHDN yang tepat (contohnya kod
022untuk perisian komputer dan perkhidmatan IT). - Kadar Cukai & Pengecualian: Pemisahan jelas antara barangan berkadar standard, barangan berkadar sifar, atau caj cukai perkhidmatan (SST 8%).
Fasa 3: Autentikasi OAuth 2.0 & Pengesahan API LHDN
Sistem middleware menyambung ke titik akhir API LHDN MyInvois menggunakan kelayakan rasmi (Client ID dan Client Secret) yang didaftarkan melalui portal MyInvois:
# 1. Permintaan Token Akses OAuth 2.0
curl -X POST https://api.myinvois.hasil.gov.my/connect/token -H "Content-Type: application/x-www-form-urlencoded" -d "client_id=CLIENT_ID_ANDA" -d "client_secret=CLIENT_SECRET_ANDA" -d "grant_type=client_credentials" -d "scope=InvoicingAPI"
Dengan token bearer yang sah, sistem menghantar dokumen transaksi berformat JSON yang telah ditandatangani secara digital (Digital Signature berasaskan X.509 SHA-256).
Fasa 4: Pengembalian Kod QR & UUID LHDN
Pelayan LHDN MyInvois memproses dokumen:
- Memvalidasi skema data dan ketepatan nombor TIN/BRN.
- Menjana nombor unik UUID (Universally Unique Identifier) bagi transaksi tersebut.
- Menandatangani dokumen dan mengembalikan Pautan Pengesahan Rasmi (Validation Link) berserta Kod QR.
Middleware mengemas kini rekod pesanan dalam pangkalan data e-dagang, menyimpan UUID LHDN, dan menyematkan kod QR rasmi pada resit/invois pelanggan.
+-------------------------------------------------------------------+
| CONTOH DATA INVOIS YANG DIKEMBALIKAN |
| |
| Status LHDN : Validated |
| UUID : 9c8b7f21-4a5e-4c31-9876-123456789abc |
| Tarikh/Masa : 2026-09-26T14:32:00Z |
| Kod QR URL : https://myinvois.hasil.gov.my/validate/9c8b7f21... |
+-------------------------------------------------------------------+
Pelanggan boleh mengimbas kod QR tersebut menggunakan telefon pintar mereka untuk menyemak dokumen yang disimpan di portal rasmi kerajaan secara masa nyata.
Konsolidasi e-Invois B2C: Pilihan Fleksibel Untuk Peniaga Runcit
Bagi perniagaan e-dagang yang menjual produk nilai rendah terus kepada pengguna umum (B2C), pelanggan individu lazimnya tidak memerlukan e-Invois rasmi untuk tujuan cukai.
Di bawah peraturan LHDN:
- Peniaga dibenarkan mengeluarkan resit atau invois biasa kepada pembeli pada masa checkout.
- Keseluruhan transaksi runcit B2C yang tidak meminta e-Invois individu boleh diagregatkan ke dalam satu Invois Konsolidasi (Consolidated e-Invoice) bulanan dan dihantar ke API MyInvois dalam tempoh 7 hari selepas hujung setiap bulan kalendar.
- Walau bagaimanapun, seni bina laman web anda tetap mesti menyediakan pilihan bagi mana-mana pembeli yang memilih untuk memasukkan nombor TIN mereka untuk menerima invois individu yang disahkan serta-merta.
Keperluan Arkib Digital 7 Tahun (Seksyen 82 ACP 1967)
Di bawah Seksyen 82 Akta Cukai Pendapatan 1967, setiap perniagaan diwajibkan menyimpan rekod perakaunan dan dokumen transaksi e-Invois lengkap selama sekurang-kurangnya tujuh (7) tahun.
Platform e-dagang SaaS antarabangsa (seperti Shopify peringkat asas) tidak direka secara asli untuk arkib audit percukaian Malaysia. Sandaran pangkalan data tempatan dan fail JSON dokumen sah LHDN mesti disimpan dalam storan selamat yang tidak boleh diubah (immutable storage / WORM storage) bagi memenuhi piawaian pemeriksaan audit LHDN.
Bagaimana JagaWeb Membina Penyelesaian e-Dagang Patuh LHDN
Sistem e-dagang bukan sekadar susunan katalog gambar produk yang menarik; ia adalah enjin kewangan yang mesti beroperasi dengan ketepatan perakaunan mutlak.
- Pelan Penjagaan Laman Web (JagaWeb Care - RM450/bulan): Kami memastikan sistem WooCommerce atau CMS anda sentiasa stabil, mengawasi baris gilir mesej transaksi, dan memastikan pemalam penyegerakan tidak terhenti akibat ralat skrip.
- Pembangunan Web & Peningkatan Sistem Bulanan (Bermula RM13,000/bulan): Untuk perusahaan dengan volum pesanan tinggi atau sistem ERP sedia ada, pasukan jurutera JagaWeb membina middleware API tersuai yang menghubungkan platform e-dagang anda terus ke gerbang LHDN MyInvois secara automatik dan stabil.
- Projek Skop Tetap (Bermula RM30,000): Pembangunan penuh aplikasi web tersuai lengkap dengan seni bina e-dagang berdaya tahan tinggi, reka bentuk sistem pangkalan data selamat, dan integrasi MyInvois menyeluruh.
Bincangkan keperluan teknikal e-invois platform anda bersama jurutera kami di JagaWeb.