Cara Menyiasat Ralat API LHDN MyInvois Tanpa Meneka

Mulakan dengan operasi yang gagal

Siasatan ralat e-Invois perlu bermula daripada bukti, bukan nama kod yang diandaikan:

1. Tentukan sama ada kegagalan berlaku semasa mendapatkan token, menghantar dokumen, membaca status atau membatalkan/menolak dokumen.
2. Simpan status HTTP dan teks jawapan sebenar.
3. Bandingkan dokumen UBL yang dikira hash dengan bait yang dienkodkan kepada Base64.
4. Baiki data atau peraturan pemetaan hanya selepas punca operasi dikenal pasti.

GetPay tidak memadankan setiap kegagalan kepada senarai kod ciptaan sendiri. Pelanggan HTTP asal mengekalkan bukti yang dipulangkan oleh LHDN, tetapi mengehadkan panjang teks supaya catatan operasi kekal terkawal.

Operasi GetPay	Kaedah dan laluan	Dasar cubaan semula	Bukti kegagalan
Token akses	POST /connect/token	Cubaan semula dengan sela masa	Status dan 200 aksara pertama
Hantar dokumen	POST /api/v1.0/documentsubmissions	Had masa sahaja; tiada cubaan semula	Status dan 500 aksara pertama
Baca butiran dokumen	GET /api/v1.0/documents/{uuid}/details	Cubaan semula dengan sela masa	Status dan 300 aksara pertama
Batal atau tolak	PUT /api/v1.0/documents/state/{uuid}/state	Had masa sahaja; tiada cubaan semula	Status dan 300 aksara pertama

Pengesahan: gunakan nilai expires_in

GetPay memohon token kelayakan pelanggan dengan skop InvoicingAPI. Tempoh sah token tidak diandaikan sebagai nombor tetap. Sistem menggunakan nilai expires_in daripada LHDN dan menyimpan token itu dalam proses pelayan.

Token simpanan hanya digunakan apabila baki tempohnya melebihi 60 saat:

const cached = tokenCache.get(key)
if (cached && cached.exp > Date.now() + 60_000) return cached.token

tokenCache.set(key, {
  token: json.access_token,
  exp: Date.now() + json.expires_in * 1000,
})

Permintaan token boleh dicuba semula kerana ia tidak memfailkan dokumen perakaunan. Jika permintaan token gagal, semak status dan teks jawapan sebelum menukar kelayakan atau skop.

Satu rentetan untuk hash dan Base64

Fungsi buildSubmissionDocument() menghasilkan satu rentetan JSON. Rentetan yang sama digunakan untuk hash SHA-256 dan pengekodan Base64:

const canonical = JSON.stringify(ublDoc)
const bytes = new TextEncoder().encode(canonical)
const hashBuf = await crypto.subtle.digest("SHA-256", bytes)
const documentHash = [...new Uint8Array(hashBuf)]
  .map((byte) => byte.toString(16).padStart(2, "0"))
  .join("")
const document = Buffer.from(canonical, "utf8").toString("base64")

Jangan kira hash daripada satu versi JSON tetapi menghantar versi yang telah diubah. Perbezaan satu bait pun menyebabkan documentHash tidak lagi menerangkan dokumen yang dihantar.

Sampul hantaran GetPay mengandungi format: "JSON", document, documentHash dan nombor invois syarikat sebagai codeNumber. Jawapan berjaya dijangka membawa submissionUid, senarai dokumen diterima berserta uuid, serta senarai dokumen ditolak dengan objek ralat sebenar daripada LHDN.

Semak pemetaan UBL sebelum menyalahkan rangkaian

Bagi invois biasa, GetPay membina dokumen jenis 01 versi 1.1 dalam mata wang MYR. Maklumat pihak pembekal merangkumi TIN dan nombor pendaftaran perniagaan. Bagi pembeli B2C tempatan tanpa TIN, pemeta boleh menggunakan EI00000000010.

EI00000000030 bukan TIN sandaran umum bagi semua pembeli. Dalam GetPay, nilai itu hanya digunakan dalam aliran bil kendiri apabila pembekal individu berada di luar Malaysia dan tidak memberikan TIN Malaysia.

Aliran bil kendiri turut mengesahkan:

• jenis dan nilai pengenalan pembekal;
• kod negara, negeri, pos dan MSIC;
• nombor telefon dalam format E.164;
• amaun positif dengan ketepatan sen; dan
• jumlah baris yang sama tepat dengan jumlah baucar bayaran.

Agihan cukai yang tepat hingga sen

GetPay menggunakan kaedah baki terbesar Hamilton supaya setiap bahagian cukai baris tidak negatif dan jumlahnya sama tepat dengan cukai dokumen:

const exact = weights.map((weight) => (totalCents * weight) / totalWeight)
exact.forEach((share, index) => {
  cents[index] = Math.floor(share)
})
let remainder = totalCents - cents.reduce((sum, value) => sum + value, 0)

Kaedah ini mengelakkan pembundaran berasingan pada setiap baris daripada terlebih mengagihkan cukai kecil lalu menghasilkan nilai negatif pada baris terakhir.

Tamat masa bermaksud hasil belum diketahui

Hantaran dokumen menggunakan fetchWithTimeout, bukan fungsi cubaan semula. Sebelum panggilan keluar, aliran GetPay membuat tuntutan pangkalan data yang atomik dengan menetapkan status LHDN invois kepada SUBMITTING. Tuntutan itu menghalang dua pemanggil serentak, tetapi tidak membuktikan sama ada LHDN menerima dokumen apabila jawapan rangkaian hilang.

Selepas tamat masa:

• jangan hantar dokumen yang sama sekali lagi secara membuta tuli;
• kekalkan status tempatan dan bukti muatan;
• jika uuid telah diterima, baca status melalui titik akhir butiran dokumen; dan
• jika uuid belum diterima, selaraskan rekod operasi tanpa menganggap hantaran berjaya atau gagal.

Perubahan status untuk pembatalan dan penolakan menggunakan prinsip konservatif yang sama: ada had masa, tetapi tiada ulangan automatik.

Senarai semak penyiasatan

• Pastikan persekitaran dan kelayakan diambil daripada rekod syarikat penyewa yang betul.
• Kenal pasti operasi, status HTTP dan petikan jawapan sebenar.
• Pastikan hash SHA-256 dan Base64 berasal daripada rentetan JSON yang sama.
• Semak jenis dokumen, versi, peranan TIN, skim pendaftaran, MSIC, alamat, telefon dan ketepatan sen.
• Pastikan jumlah cukai semua baris sama dengan cukai dokumen.
• Jangan tafsir kehilangan jawapan rangkaian sebagai bukti bahawa permintaan perubahan gagal.