Cara Hantar e-Invois LHDN Terus Tanpa Portal MyInvois (Panduan PKS Malaysia)

Ringkasnya: bagaimana cara hantar e-Invois LHDN terus?

Cara operasinya ialah sediakan invois → semak data → hantar kepada LHDN → baca status pengesahan. Dalam GetPay, empat langkah ini berlaku dalam aliran kerja invois yang sama. Sistem membina dokumen UBL 2.1, menyediakan sampul API dan menghantar dokumen menggunakan kelayakan MyInvois milik syarikat anda. Anda tidak perlu menghasilkan XML sendiri, mencari fail dalam komputer atau memuat naiknya satu demi satu melalui portal.

Namun, “berjaya dihantar” dan “sah” bukan perkara yang sama. Respons awal boleh menerima dokumen dan memberikan uuid, sedangkan LHDN masih memproses pengesahannya. Operasi hanya lengkap selepas status dokumen dibaca sebagai Valid atau tindakan susulan diambil apabila statusnya Invalid.

Aliran minimum untuk pemilik PKS ialah:

1. Lengkapkan profil syarikat dan kelayakan MyInvois bagi entiti yang betul.
2. Sediakan invois dengan butiran pembekal, pembeli, baris jualan, cukai dan jumlah.
3. Semak data sumber sebelum menekan hantar.
4. Benarkan GetPay membina dan menghantar dokumen terus kepada LHDN.
5. Simpan rujukan hantaran dan semak status sehingga keputusan pengesahan tersedia.

Mengapa aliran terus lebih praktikal daripada muat naik manual?

Kerja manual menambah beberapa titik kegagalan bagi PKS. Staf mungkin memilih fail yang salah, menaip semula nombor rujukan atau terlupa memindahkan status LHDN kembali ke rekod akaun. Apabila jumlah invois meningkat, cabaran utamanya ialah mengekalkan jejak antara invois, dokumen yang dihantar dan keputusan pengesahan.

Aliran terus mengekalkan satu rantaian rujukan:

Peringkat	Rekod yang perlu kekal bersambung
Invois	Nombor invois, pelanggan, baris, cukai dan jumlah
Dokumen LHDN	JSON UBL 2.1 yang dibina daripada invois tersebut
Sampul hantaran	codeNumber, document, documentHash dan format
Respons	submissionUid, dokumen diterima atau ditolak, dan uuid
Status	Submitted, Valid, Invalid atau Cancelled

Kelebihan ini bukan alasan untuk melangkau semakan. Automasi hanya menghantar data sumber dengan lebih konsisten. Jika TIN, nombor pendaftaran, amaun atau cukai dalam invois salah, dokumen yang dibina juga membawa kesalahan itu. Oleh sebab itu, sistem e-Invois PKS yang baik perlu menggabungkan penghantaran terus dengan disiplin semakan data.

Apakah yang perlu disediakan sebelum hantaran pertama?

1. Kelayakan MyInvois bagi setiap syarikat

GetPay tidak menggunakan satu pasangan kelayakan global untuk semua pelanggan. Setiap penyewa atau syarikat membekalkan tuple sendiri:

• clientId;
• clientSecret; dan
• env, sama ada sandbox atau production.

Pemisahan ini penting untuk perniagaan berbilang entiti. Sebelum memulakan, pastikan entiti dalam GetPay sepadan dengan entiti yang kelayakannya diberikan oleh LHDN.

2. Persekitaran yang betul

GetPay menghantar sandbox ke hos prapengeluaran MyInvois dan production ke hos pengeluaran. Sandbox ialah tempat untuk menguji pemetaan, format data dan tatacara operasi tanpa menganggapnya sebagai pemfailan sebenar. Production pula ialah laluan untuk dokumen sebenar.

Semak tetapan syarikat. Kesilapan memilih persekitaran boleh menyebabkan pasukan menyangka dokumen sebenar telah dihantar sedangkan ia hanya berada dalam ujian, atau sebaliknya.

3. Data invois yang boleh dipetakan

Bagi invois biasa, pemeta GetPay membina dokumen jenis 01, versi senarai 1.1, dalam mata wang MYR. Data utama yang dibawa termasuk:

• nombor dan tarikh invois;
• TIN, nombor pendaftaran, nama dan alamat pembekal;
• nombor SST dan kod MSIC pembekal apabila tersedia;
• TIN, pendaftaran, nama dan e-mel pembeli daripada rekod invois;
• kuantiti, penerangan, harga unit dan amaun setiap baris;
• cukai setiap baris dan jumlah cukai dokumen; serta
• subtotal, jumlah termasuk cukai dan amaun perlu dibayar.

Bagi pembeli B2C Malaysia tanpa TIN, pemeta invois biasa boleh menggunakan TIN awam yang diterbitkan LHDN. Jangan gunakan peraturan sandaran itu sebagai alasan untuk mengosongkan data pembeli B2B. Jenis transaksi menentukan data yang patut dikumpulkan; semak panduan LHDN yang berkuat kuasa untuk kes anda.

Bagaimanakah GetPay menghantar e-Invois tanpa portal MyInvois?

Langkah 1 — Sediakan invois daripada transaksi sebenar

Mulakan dengan jualan sebenar, bukan dengan fail teknikal. Pilih pelanggan yang betul, masukkan penerangan barangan atau perkhidmatan, kuantiti, harga unit dan cukai yang berkenaan. Pastikan nombor invois ialah rujukan unik yang akan dikenali oleh pasukan kewangan dan pelanggan.

Semak tiga imbangan mudah sebelum hantar:

1. jumlah baris menyokong subtotal;
2. jumlah cukai baris menyokong cukai dokumen; dan
3. subtotal campur cukai menyokong jumlah perlu dibayar.

GetPay mengagihkan jumlah cukai kepada baris dengan ketepatan sen. Kaedah baki terbesar digunakan supaya setiap agihan tidak negatif dan jumlah semua baris kembali tepat kepada cukai dokumen. Ini mengelakkan perbezaan satu sen yang boleh muncul apabila setiap baris dibundarkan secara berasingan.

Langkah 2 — Semak identiti pembekal dan pembeli

Semakan ini patut berlaku sebelum sebarang panggilan API. Bagi pembekal, pastikan nama berdaftar, TIN, nombor pendaftaran, alamat dan maklumat berkaitan cukai datang daripada profil entiti yang mengeluarkan invois. Bagi pembeli, tentukan sama ada transaksi itu B2B atau B2C dan gunakan butiran yang benar-benar diberikan oleh pelanggan.

Jangan salin TIN daripada pelanggan lain untuk “melepasi” ruangan wajib. Jangan juga meneka kod MSIC, skim pendaftaran atau nombor SST. Jika fakta tidak tersedia, dapatkan pengesahan daripada rekod syarikat atau pelanggan dan rujuk panduan LHDN bagi pilihan yang dibenarkan.

Langkah 3 — GetPay membina dokumen UBL 2.1

Selepas data bersedia, GetPay menukarkan invois kepada struktur JSON UBL. Di dalam dokumen itu, pembekal ditempatkan di bawah AccountingSupplierParty, pembeli di bawah AccountingCustomerParty, dan baris jualan di bawah InvoiceLine.

Medan kewangan utama mempunyai hubungan yang jelas:

Medan UBL	Sumber operasi
ID	Nombor invois
IssueDate	Tarikh invois
InvoiceTypeCode	01 untuk invois biasa
DocumentCurrencyCode	MYR
LineExtensionAmount	Amaun baris atau subtotal
TaxAmount	Cukai baris dan cukai dokumen
TaxInclusiveAmount	Jumlah termasuk cukai
PayableAmount	Jumlah perlu dibayar

Pemilik PKS tidak perlu menaip nama medan ini dalam portal. Nilainya tetap perlu difahami kerana ralat pengesahan lazimnya perlu diselesaikan pada data sumber, bukan dengan mengubah fail selepas ia dijana.

Langkah 4 — GetPay mendapatkan token dan menyediakan sampul hantaran

Pelanggan LHDN GetPay meminta token menggunakan aliran kelayakan pelanggan dan skop InvoicingAPI. Token disimpan sementara dalam proses pelayan mengikut nilai expires_in yang dipulangkan. GetPay hanya menggunakan semula token jika baki tempohnya melebihi 60 saat; jika tidak, token baharu diminta.

Dokumen UBL kemudian ditukar kepada satu rentetan JSON. Bait yang sama digunakan untuk dua hasil:

1. hash SHA-256 dalam bentuk heksadesimal sebagai documentHash; dan
2. dokumen berkod Base64 sebagai document.

Sampul akhir mengandungi:

format: "JSON"
document: <JSON UBL yang dikodkan Base64>
documentHash: <hash SHA-256 bagi JSON yang sama>
codeNumber: <nombor invois syarikat>

Prinsipnya penting: hash dan Base64 mesti datang daripada rentetan yang sama. Jika objek diubah selepas hash dikira, hash itu tidak lagi mewakili dokumen yang dihantar.

Langkah 5 — Hantar sekali, kemudian baca respons

GetPay menghantar sampul dokumen kepada operasi hantaran MyInvois. Respons berjaya mempunyai submissionUid dan boleh mengandungi dua kumpulan:

• acceptedDocuments, dengan invoiceCodeNumber dan uuid; atau
• rejectedDocuments, dengan nombor invois serta objek ralat code dan message yang dipulangkan LHDN.

Perkataan “accepted” pada tahap ini merujuk kepada penerimaan dalam respons hantaran, bukan pengesahan akhir kandungan. Simpan uuid dokumen yang diterima kerana nilai itulah yang digunakan untuk membaca butiran dokumen selepas hantaran.

Bagaimanakah status e-Invois perlu dibaca?

GetPay mengenali empat status dokumen daripada pelanggan LHDN:

Status LHDN	Makna operasi dalam GetPay
Submitted	Dipetakan kepada PENDING; pengesahan belum muktamad
Valid	Dipetakan kepada VALID; dokumen melepasi pengesahan
Invalid	Dipetakan kepada INVALID; semak keputusan pengesahan
Cancelled	Dipetakan kepada CANCELLED

Semakan status ialah permintaan baca dan boleh dicuba semula dengan sela masa apabila gangguan rangkaian berlaku. Respons butiran boleh membawa validationResults, termasuk langkah pengesahan, status langkah dan ralat dengan code serta message apabila LHDN menyediakannya.

Prosedur staf yang ringkas ialah:

1. selepas hantar, pastikan nombor invois mempunyai rujukan uuid;
2. baca status dokumen;
3. jika Submitted, tunggu dan semak semula kemudian;
4. jika Valid, rekodkan bahawa pengesahan selesai;
5. jika Invalid, baca langkah dan mesej sebenar sebelum membetulkan data; dan
6. jika status tidak dikenali, jangan menukarnya kepada “berjaya” secara andaian.

Apakah yang perlu dibuat apabila hantaran gagal atau tamat masa?

Kegagalan token, penolakan dokumen dan tamat masa penghantaran ialah tiga keadaan yang berbeza.

Jika token gagal, semak persekitaran, ID pelanggan, rahsia pelanggan dan respons sebenar. Permintaan token tidak memfailkan dokumen, jadi pelanggan GetPay boleh mencubanya semula dengan sela masa.

Jika dokumen disenaraikan dalam rejectedDocuments, baca code dan message yang benar-benar dipulangkan. Betulkan data punca yang berkaitan, jana semula dokumen dan ikut prosedur operasi yang sesuai. Jangan cipta tafsiran kod hanya berdasarkan tekaan.

Jika penghantaran tamat masa, hasilnya belum diketahui. LHDN mungkin telah menerima dokumen tetapi responsnya hilang dalam perjalanan. Atas sebab itu, GetPay meletakkan had masa pada permintaan hantaran tetapi tidak mengulangnya secara automatik. Hantaran kedua secara membuta tuli boleh menghasilkan dokumen pendua.

Gunakan urutan pemulihan ini:

1. jangan tekan hantar berulang kali;
2. simpan nombor invois dan bukti operasi;
3. cari submissionUid atau uuid jika respons separa telah direkodkan;
4. jika uuid tersedia, baca butiran dokumen;
5. jika tiada rujukan, selaraskan rekod operasi sebelum membuat keputusan; dan
6. hanya hantar semula selepas anda memastikan dokumen pertama tidak berada dalam proses atau telah difailkan.

Sandbox atau production: yang mana patut digunakan?

Gunakan sandbox untuk membuktikan bahawa profil syarikat, pemetaan pembeli, baris, cukai dan proses semakan status berfungsi seperti yang dijangka. Gunakan production hanya untuk operasi sebenar dengan kelayakan production milik entiti tersebut.

Sebelum menukar persekitaran, lakukan pemeriksaan serahan:

• pasukan tahu siapa yang dibenarkan menghantar;
• profil entiti dan TIN telah disahkan;
• sampel invois B2B dan B2C yang relevan telah diuji;
• cukai serta pembundaran hingga sen telah diperiksa;
• staf tahu beza PENDING, VALID dan INVALID;
• ada prosedur untuk tamat masa tanpa hantaran pendua; dan
• status LHDN boleh dijejak kembali kepada nombor invois asal.

Kawalan operasi masih milik perniagaan. Pisahkan data ujian daripada data sebenar dan jangan gunakan production sebagai tempat mencuba format.

Senarai semak harian untuk PKS

Sebelum hantar:

• entiti, persekitaran dan kelayakan adalah betul;
• invois dikeluarkan oleh syarikat yang betul;
• nombor serta tarikh invois tepat;
• pembeli dan jenis transaksi dikenal pasti;
• TIN serta pendaftaran tidak diteka;
• penerangan, kuantiti, harga, cukai dan jumlah telah disemak;
• amaun mempunyai ketepatan sen; dan
• staf memahami bahawa hantaran kepada LHDN ialah tindakan sebenar.

Selepas hantar:

• simpan submissionUid dan uuid apabila tersedia;
• bezakan dokumen diterima daripada dokumen Valid;
• semak PENDING sehingga keputusan tersedia;
• baca ralat sebenar bagi Invalid atau dokumen ditolak;
• jangan ulang hantaran selepas tamat masa tanpa penyelarasan; dan
• kekalkan pautan antara invois, respons dan status LHDN.

Soalan lazim

Adakah “tanpa portal” bermaksud portal MyInvois tidak diperlukan langsung?

Tidak semestinya. Maksudnya ialah kerja rutin menjana dan menghantar setiap e-Invois boleh dilakukan terus dalam GetPay tanpa muat naik fail XML secara manual. Akses kepada saluran rasmi LHDN masih berguna untuk pentadbiran, rujukan atau penyiasatan yang memerlukannya.

Adakah respons hantaran berjaya bermaksud e-Invois sudah sah?

Belum tentu. Respons boleh menerima dokumen dan memberikan uuid, tetapi status dokumen masih Submitted. GetPay memetakannya kepada PENDING. Tunggu sehingga bacaan status menjadi Valid sebelum menganggap pengesahan selesai.

Mengapa GetPay tidak mencuba semula hantaran secara automatik?

Kerana penghantaran ialah tindakan yang boleh memfailkan dokumen. Jika LHDN menerima permintaan tetapi respons hilang, cubaan kedua boleh mewujudkan pendua. Sebaliknya, permintaan token dan bacaan status selamat dicuba semula kerana operasi tersebut tidak memfailkan dokumen baharu.

Bolehkah satu kelayakan LHDN digunakan untuk semua syarikat?

Aliran GetPay direka dengan kelayakan per syarikat atau penyewa. Setiap panggilan menerima ID pelanggan, rahsia pelanggan dan persekitaran bagi entiti berkenaan. Ini mengurangkan risiko invois satu entiti dihantar di bawah identiti entiti lain.

Apakah perkara pertama yang perlu diperiksa apabila status Invalid?

Baca validationResults, langkah pengesahan dan mesej sebenar yang dipulangkan LHDN. Kemudian jejak nilai itu kembali kepada data sumber seperti TIN, pendaftaran, butiran pihak, baris, cukai atau jumlah. Jangan menukar beberapa medan secara rawak kerana itu menghapuskan bukti punca.

Sumber

Panduan ini berpandukan format Invois versi 1.1 dan contoh JSON UBL yang diterbitkan dalam SDK MyInvois LHDN. Bagi keperluan khusus mengikut jenis transaksi atau perubahan dasar, rujuk panduan terkini yang diterbitkan oleh LHDN sebelum menghantar dokumen production.