LHDN MyInvois API பிழைகளை ஊகமின்றி ஆய்வு செய்வது எப்படி?

பிழைப் பெயரை அல்ல, தோல்வியடைந்த செயலை முதலில் பாருங்கள்

MyInvois மின்னணு விலைப்பட்டியல் சிக்கலை ஆய்வு செய்யும் சரியான வரிசை:

1. அணுகல் சான்று பெறுதல், ஆவணச் சமர்ப்பிப்பு, நிலை வாசிப்பு, ரத்து அல்லது நிராகரிப்பு — இவற்றில் எது தோல்வியடைந்தது என்பதை உறுதிசெய்யுங்கள்.
2. உண்மையான HTTP நிலையையும் LHDN திருப்பிய பதில் உரையையும் சேமியுங்கள்.
3. SHA-256 கணக்கிடப்பட்ட UBL ஆவணத்தையும் Base64-ஆக மாற்றப்பட்ட தரவையும் ஒப்பிடுங்கள்.
4. தோல்வியடைந்த செயல் தெளிவான பிறகே வணிகத் தகவல் அல்லது UBL வரைபாட்டை மாற்றுங்கள்.

GetPay ஒவ்வொரு தோல்விக்கும் கற்பனையான குறியீட்டுப் பெயரை ஒதுக்காது. LHDN வழங்கிய ஆதாரத்தைச் சேமிக்கிறது; அதேவேளை செயல்பாட்டுப் பதிவுகள் அளவின்றி பெருகாதபடி பதில் உரையின் நீளத்தை வரையறுக்கிறது.

GetPay செயல்	முறை மற்றும் பாதை	மறுமுயற்சி விதி	தோல்வியில் பாதுகாக்கப்படும் ஆதாரம்
அணுகல் சான்று	POST /connect/token	இடைவெளியுடன் மறுமுயற்சி	நிலை மற்றும் முதல் 200 எழுத்துகள்
ஆவணச் சமர்ப்பிப்பு	POST /api/v1.0/documentsubmissions	நேர வரம்பு மட்டும்; மறுமுயற்சி இல்லை	நிலை மற்றும் முதல் 500 எழுத்துகள்
ஆவண விவரம்	GET /api/v1.0/documents/{uuid}/details	இடைவெளியுடன் மறுமுயற்சி	நிலை மற்றும் முதல் 300 எழுத்துகள்
ரத்து அல்லது நிராகரிப்பு	PUT /api/v1.0/documents/state/{uuid}/state	நேர வரம்பு மட்டும்; மறுமுயற்சி இல்லை	நிலை மற்றும் முதல் 300 எழுத்துகள்

அணுகல் சான்றின் காலம்: expires_in தான் அதிகாரம்

GetPay InvoicingAPI அனுமதியுடன் client-credentials முறையில் அணுகல் சான்றைப் பெறுகிறது. எல்லா சான்றுகளும் ஒரே நிலையான காலத்திற்கு செல்லுபடியாகும் என்று கருதுவதில்லை. LHDN பதிலில் வரும் expires_in மதிப்பைப் பயன்படுத்தி, சான்றைச் சேவையகச் செயல்முறையின் நினைவகத்தில் தற்காலிகமாக வைத்திருக்கும்.

60 வினாடிகளுக்கு மேல் செல்லுபடியாகும் சான்று மட்டுமே மீண்டும் பயன்படுத்தப்படும்:

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,
})

அணுகல் சான்று பெறுவது கணக்கியல் ஆவணத்தைப் பதிவு செய்யாது; எனவே அந்தச் செயலை இடைவெளியுடன் மீண்டும் முயற்சிப்பது பாதுகாப்பானது. அது தோல்வியடைந்தால் சான்றுகளை உடனே மாற்றுவதற்கு முன் நிலை மற்றும் பதில் உரையை ஆய்வு செய்ய வேண்டும்.

ஒரே JSON உரையிலிருந்து SHA-256 மற்றும் Base64

buildSubmissionDocument() ஒரே JSON உரையை உருவாக்கி, அதிலிருந்தே இரு பரிமாற்ற மதிப்புகளையும் பெறுகிறது:

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")

ஒரு JSON பதிப்புக்கு SHA-256 கணக்கிட்டு, பின்னர் மாற்றிய JSON-ஐ Base64-ஆக அனுப்பக்கூடாது. ஒரு தரவு அலகு மாறினாலும் documentHash அனுப்பப்பட்ட ஆவணத்துடன் பொருந்தாது.

GetPay சமர்ப்பிப்பு உறையில்:

• format: "JSON";
• Base64 document;
• SHA-256 பதினாறடிமான documentHash; மற்றும்
• நிறுவனத்தின் விலைப்பட்டியல் எண் codeNumber

ஆகியவை உள்ளன. வெற்றிகரமான பதிலில் submissionUid, uuid உடைய ஏற்றுக்கொள்ளப்பட்ட ஆவணங்கள், மேலும் LHDN வழங்கிய பிழைத் தகவலுடன் நிராகரிக்கப்பட்ட ஆவணங்கள் இருக்கலாம். LHDN குறியீடு வழங்காத இடத்தில் GetPay புதிதாக ஒன்றை உருவாக்காது.

இணைய இணைப்பிற்கு முன்பே UBL வணிகத் தகவலைச் சரிபார்க்குங்கள்

வழக்கமான விற்பனை விலைப்பட்டியலை GetPay 01 ஆவண வகை, 1.1 பதிப்பு மற்றும் MYR நாணயத்தில் உருவாக்குகிறது. வழங்குநரின் TIN மற்றும் வணிகப் பதிவு எண் சேர்க்கப்படுகின்றன. TIN இல்லாத உள்நாட்டு B2C வாங்குபவருக்கு EI00000000010 மாற்றாகப் பயன்படுத்தப்படலாம்.

EI00000000030 எல்லா வெளிநாட்டு பரிவர்த்தனைகளுக்குமான பொதுவான வாங்குபவர் TIN அல்ல. GetPay-இல், மலேசியாவிற்கு வெளியே உள்ளதும் மலேசிய TIN வழங்காததுமான தனிநபர் வழங்குநரின் சுய-விலைப்பட்டியல் நடைமுறையில் மட்டுமே அது பயன்படுத்தப்படுகிறது.

சுய-விலைப்பட்டியல் உருவாக்கி கீழ்கண்டவற்றையும் சரிபார்க்கிறது:

• வழங்குநரின் அடையாள ஆவண வகையும் எண்ணும்;
• நாடு, மாநிலம், அஞ்சல் குறியீடு மற்றும் ஐந்து இலக்க MSIC;
• E.164 வடிவத் தொலைபேசி எண்;
• சென் அளவிற்கு துல்லியமான நேர்மறைத் தொகைகள்; மற்றும்
• செலுத்தல் சான்றின் மொத்தத்துடன் சரியாகப் பொருந்தும் வரித் தொகைகள்.

ஒவ்வொரு சென்னும் கணக்கில் சேர வேண்டும்

வரித் தொகையை வரிகளுக்குப் பகிர GetPay Hamilton largest-remainder முறையைப் பயன்படுத்துகிறது. இதனால் எந்த வரித் தொகையும் எதிர்மறையாகாது; அனைத்து வரிகளின் கூட்டுத்தொகையும் ஆவண வரியுடன் சரியாகப் பொருந்தும்:

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)

ஒவ்வொரு வரியையும் தனித்தனியாக முழுமைப்படுத்தினால் சிறிய வரித் தொகை அதிகமாகப் பகிரப்பட்டு கடைசி வரியில் எதிர்மறை மதிப்பு தோன்றலாம். சமர்ப்பிப்புக்கு முன் கணக்கைச் சரிசெய்வதே பாதுகாப்பான நடைமுறை.

நேரம் முடிவது என்பது முடிவு தெரியவில்லை என்பதாகும்

ஆவணச் சமர்ப்பிப்பு fetchWithTimeout மூலம் அனுப்பப்படுகிறது; மறுமுயற்சி செயலி பயன்படுத்தப்படுவதில்லை. வெளியே அனுப்புவதற்கு முன் GetPay தரவுத்தளத்தில் விலைப்பட்டியலின் LHDN நிலையை SUBMITTING என ஒரே அணுச் செயலாக மாற்றுகிறது. இதனால் ஒரே ஆவணத்தை இரு கோரிக்கைகள் ஒரே நேரத்தில் அனுப்ப முடியாது. ஆனால் வலைப்பின்னல் பதில் தொலைந்தால், LHDN ஆவணத்தை ஏற்றதா என்பதை அந்த உள்ளூர் நிலை மட்டும் நிரூபிக்காது.

நேர வரம்பு முடிந்தால்:

• அதே ஆவணத்தை உடனடியாக மீண்டும் அனுப்ப வேண்டாம்;
• உள்ளூர் நிலையையும் சமர்ப்பிப்பு ஆதாரத்தையும் பாதுகாக்கவும்;
• uuid கிடைத்திருந்தால் ஆவண விவரப் பாதையில் நிலையை வாசிக்கவும்;
• uuid கிடைக்கவில்லை என்றால் வெற்றி அல்லது தோல்வி என்று ஊகிக்காமல் செயல்பாட்டுப் பதிவுடன் ஒப்பிட்டுச் சரிபார்க்கவும்.

ரத்தும் நிராகரிப்பும் வரி ஆவணத்தின் நிலையை மாற்றும் செயல்கள். ஆகவே அவற்றுக்கும் நேர வரம்பு உண்டு; தானியங்கி மறுஅனுப்பல் இல்லை.

தமிழ் வணிகங்களுக்கான ஆய்வுப் பட்டியல்

• சரியான வணிக நிறுவனப் பதிவிலிருந்து சூழலும் அங்கீகாரத் தகவலும் எடுக்கப்பட்டதா என்பதை உறுதிசெய்யுங்கள்.
• தோல்வியடைந்த செயல், HTTP நிலை மற்றும் உண்மையான பதில் உரையைப் பதிவு செய்யுங்கள்.
• SHA-256 மற்றும் Base64 ஒரே JSON உரையிலிருந்து வந்ததா என்பதைச் சரிபார்க்குங்கள்.
• ஆவண வகை, பதிப்பு, TIN-இன் பங்கு, பதிவு முறை, MSIC, முகவரி, தொலைபேசி மற்றும் சென் துல்லியத்தைச் சரிபார்க்குங்கள்.
• அனைத்து வரிகளின் வரித் தொகையும் ஆவண வரியுடன் முழுமையாகப் பொருந்த வேண்டும்.
• வலைப்பின்னல் பதில் வராததை, LHDN செயலை மேற்கொள்ளவில்லை என்பதற்கான ஆதாரமாகக் கருத வேண்டாம்.