n8n-nodes-lhdn-einvoice

v1.2.1

Published

6 months ago

n8n node untuk integrasi dengan LHDN e-Invoice API Malaysia

0High
0Medium
0Low

nmhafiz

n8n-community-node-package lhdn einvoice malaysia invoice tax

LHDN e-Invoice Node for n8n

🇲🇾 Node n8n rasmi untuk integrasi LHDN e-Invoice Malaysia

Automasi lengkap untuk proses e-invoice perniagaan Malaysia dengan pematuhan penuh kepada spesifikasi LHDN.

✨ What's New in v1.2.1

🐛 Bug Fixes: Fixed all TypeScript errors and test failures
✅ 100% Test Coverage: All 58 tests passing across 9 test suites
🔧 UBL 2.1 Compliance: Enhanced format compliance for invoice structures
🧮 Tax Calculation: Fixed zero tax rate handling
🛠️ Credential Tools: Added interactive setup wizard and helper scripts
📚 Documentation: Comprehensive setup guides in Bahasa Malaysia

Ciri-ciri

✅ Easy Form Input Mode - Mod input mudah dengan form fields (BARU!)
✅ Advanced Raw Mode - Input dokumen JSON/XML terus untuk pengguna mahir
✅ Authentication - Dapatkan access token untuk API
✅ Submit Documents - Hantar dokumen e-invoice (JSON/XML)
✅ Get Documents - Dapatkan dokumen berdasarkan UUID
✅ Get Recent Documents - Dapatkan senarai dokumen terkini
✅ Cancel Documents - Batalkan dokumen yang sah
✅ Reject Documents - Tolak dokumen
✅ Get Document Status - Semak status dokumen
✅ Validate TIN - Sahkan Tax Identification Number
✅ Digital Signature - Sokongan untuk tandatangan digital
✅ Sandbox & Production - Sokongan untuk kedua-dua environment

Pemasangan

Melalui n8n Community Nodes

Buka n8n instance anda
Pergi ke Settings > Community Nodes
Klik Install a community node
Masukkan n8n-nodes-lhdn-einvoice
Klik Install

Melalui npm

npm install n8n-nodes-lhdn-einvoice

🚀 Quick Start

Using Form Mode (Recommended for Beginners)

Add the LHDN e-Invoice node to your workflow
Select "Submit Document" operation
Choose "Form Fields (Easy)" as Input Mode
Fill in the form fields:
- Invoice Number: INV-2024-001
- Supplier TIN: C12345678
- Supplier Name: Your Company Sdn Bhd
- Customer TIN: D98765432
- Add invoice items with description, quantity, and price
Set Code Number: INV001
Execute - The node will automatically generate UBL 2.1 format!

Using Raw Mode (Advanced Users)

Choose "Raw Document (Advanced)" as Input Mode
Prepare your UBL 2.1 JSON/XML document
Paste the document in the Document field
Set Document Format (JSON/XML)
Execute

Example Form Input

{
  "invoiceNumber": "INV-2024-001",
  "supplier": {
    "tin": "C12345678",
    "name": "Syarikat ABC Sdn Bhd",
    "address": "No. 123, Jalan Utama",
    "city": "Kuala Lumpur",
    "postalCode": "50000",
    "state": "14"
  },
  "customer": {
    "tin": "D98765432",
    "name": "Syarikat XYZ Sdn Bhd"
  },
  "items": [
    {
      "description": "Perkhidmatan Konsultasi IT",
      "quantity": 10,
      "unitPrice": 500.00,
      "taxRate": 6
    }
  ]
}

❓ Kenapa Banyak Credential?

LHDN e-Invoice API memerlukan 8 field credential untuk keselamatan maksimum. Ini adalah requirement kerajaan Malaysia, bukan pilihan kita:

🛡️ Digital Signature: Untuk tandatangan digital dokumen
🔐 Encryption: Untuk encrypt data sensitive
🆔 Authentication: Untuk verify identity syarikat
📋 Compliance: Untuk comply dengan undang-undang Malaysia

INI STANDARD KERAJAAN - semua vendor e-Invoice kena ikut requirement yang sama.

🚀 Cara Mudah Setup (3 Langkah Sahaja!)

Option 1: Guna Credential Wizard (RECOMMENDED)

# Jalankan wizard interaktif
node credential-wizard.js

Wizard akan guide anda step-by-step dan auto-extract semua maklumat!

Option 2: Guna Helper Script

# Extract certificate info automatically
./credential-helper.sh /path/to/your/certificate.pem

Option 3: Manual Setup (lihat bahagian Konfigurasi di bawah)

💡 Setup Sekali Sahaja

Good news: Credential ini setup SEKALI SAHAJA per syarikat. Lepas tu boleh guna untuk semua workflow!

📖 Baca panduan lengkap: CREDENTIAL_SETUP_GUIDE.md

Konfigurasi

1. Buat Credentials

Sebelum menggunakan node ini, anda perlu menyediakan credentials untuk API LHDN:

Pergi ke Credentials dalam n8n
Klik Create New
Pilih LHDN e-Invoice API
Isi maklumat berikut:

| Field | Keterangan | |-------|------------| | Environment | Pilih Sandbox atau Production | | Client ID | Client ID dari LHDN | | Client Secret | Client Secret dari LHDN | | X.509 Certificate | Certificate dalam format PEM | | Private Key | Private key dalam format PEM | | X.509 Subject Name | Subject name dari certificate | | X.509 Issuer Name | Issuer name dari certificate | | X.509 Serial Number | Serial number dari certificate |

2. Dapatkan Credentials dari LHDN

Untuk mendapatkan credentials yang diperlukan:

Daftar di MyInvois Portal
Buat aplikasi baru dalam Developer Portal
Dapatkan Client ID dan Client Secret
Generate atau upload X.509 certificate
Catat semua maklumat yang diperlukan

Penggunaan

1. Get Access Token

{
  "resource": "authentication",
  "operation": "getToken"
}

2. Submit e-Invoice

{
  "resource": "document",
  "operation": "submit",
  "documentFormat": "JSON",
  "document": {
    "Invoice": {
      "InvoiceTypeCode": {
        "@listVersionID": "1.1",
        "#text": "01"
      },
      "ID": "INV12345",
      "IssueDate": "2024-01-15",
      "IssueTime": "15:30:00Z",
      "DocumentCurrencyCode": "MYR",
      "AccountingSupplierParty": {
        // Maklumat pembekal
      },
      "AccountingCustomerParty": {
        // Maklumat pembeli
      },
      "InvoiceLine": [
        // Item-item invoice
      ]
    }
  },
  "codeNumber": "INV001"
}

3. Get Recent Documents

{
  "resource": "document",
  "operation": "getRecent",
  "pageNo": 1,
  "pageSize": 20,
  "submissionDateFrom": "2024-01-01T00:00:00Z",
  "submissionDateTo": "2024-01-31T23:59:59Z"
}

4. Validate TIN

{
  "resource": "validation",
  "operation": "validateTin",
  "tin": "C12345678",
  "idType": "BRN",
  "idValue": "123456789"
}

Contoh Workflow

Workflow 1: Submit e-Invoice

HTTP Request Node - Terima data invoice dari webhook
Function Node - Format data mengikut struktur UBL 2.1
LHDN e-Invoice Node - Submit dokumen
IF Node - Semak status submission
Email Node - Hantar notifikasi

Workflow 2: Monitor Document Status

Cron Node - Jalankan setiap jam
LHDN e-Invoice Node - Get recent documents
Function Node - Filter dokumen yang perlu dikemaskini
LHDN e-Invoice Node - Get status untuk setiap dokumen
Database Node - Kemaskini status dalam database

Format Dokumen

JSON Format (UBL 2.1)

{
  "Invoice": {
    "InvoiceTypeCode": {
      "@listVersionID": "1.1",
      "#text": "01"
    },
    "ID": "INV12345",
    "IssueDate": "2024-01-15",
    "IssueTime": "15:30:00Z",
    "DocumentCurrencyCode": "MYR",
    "AccountingSupplierParty": {
      "Party": {
        "PartyIdentification": [
          {
            "ID": {
              "@schemeID": "TIN",
              "#text": "C12345678"
            }
          }
        ],
        "PartyName": [
          {
            "Name": "Syarikat ABC Sdn Bhd"
          }
        ],
        "PostalAddress": {
          "CityName": "Kuala Lumpur",
          "PostalZone": "50000",
          "CountrySubentityCode": "14",
          "AddressLine": [
            {
              "Line": "Jalan ABC 123"
            }
          ],
          "Country": {
            "IdentificationCode": "MYS"
          }
        }
      }
    },
    "AccountingCustomerParty": {
      "Party": {
        "PartyIdentification": [
          {
            "ID": {
              "@schemeID": "TIN",
              "#text": "D98765432"
            }
          }
        ],
        "PartyName": [
          {
            "Name": "Syarikat XYZ Sdn Bhd"
          }
        ]
      }
    },
    "InvoiceLine": [
      {
        "ID": "1",
        "InvoicedQuantity": {
          "@unitCode": "C62",
          "#text": "1"
        },
        "LineExtensionAmount": {
          "@currencyID": "MYR",
          "#text": "100.00"
        },
        "Item": {
          "Name": "Perkhidmatan Konsultansi"
        },
        "Price": {
          "PriceAmount": {
            "@currencyID": "MYR",
            "#text": "100.00"
          }
        }
      }
    ],
    "LegalMonetaryTotal": {
      "LineExtensionAmount": {
        "@currencyID": "MYR",
        "#text": "100.00"
      },
      "TaxExclusiveAmount": {
        "@currencyID": "MYR",
        "#text": "100.00"
      },
      "TaxInclusiveAmount": {
        "@currencyID": "MYR",
        "#text": "106.00"
      },
      "PayableAmount": {
        "@currencyID": "MYR",
        "#text": "106.00"
      }
    }
  }
}

Error Handling

Node ini menyediakan error handling yang komprehensif:

Authentication Errors - Token tidak sah atau expired
Validation Errors - Format dokumen tidak betul
API Rate Limits - Automatic retry dengan backoff
Network Errors - Timeout dan connection issues

Sokongan

Dokumentasi Rasmi: LHDN e-Invoice SDK
MyInvois Portal: https://myinvois.hasil.gov.my/
GitHub Issues: Laporkan masalah

Lesen

MIT License - lihat LICENSE untuk butiran penuh.

Sumbangan

Sumbangan adalah dialu-alukan! Sila baca CONTRIBUTING.md untuk panduan.

Changelog

v1.0.0

✅ Keluaran awal
✅ Sokongan untuk semua operasi asas LHDN e-Invoice API
✅ Sokongan untuk format JSON dan XML
✅ Digital signature support
✅ Comprehensive error handling