lhdn-einvoice

n8n node untuk integrasi dengan LHDN e-Invoice API Malaysia

Package Information

Downloads: 4 weeklyĀ /Ā 44 monthly
Latest Version: 1.2.1
Author: nmhafiz

Available Nodes

LHDN e-Invoice
Berinteraksi dengan API LHDN e-Invoice Malaysia

Documentation

LHDN e-Invoice Node for n8n

npm version
npm downloads
License: MIT
Build Status
Test Coverage
Version

šŸ‡²šŸ‡¾ 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

  1. Buka n8n instance anda
  2. Pergi ke Settings > Community Nodes
  3. Klik Install a community node
  4. Masukkan n8n-nodes-lhdn-einvoice
  5. Klik Install

Melalui npm

npm install n8n-nodes-lhdn-einvoice

šŸš€ Quick Start

Using Form Mode (Recommended for Beginners)

  1. Add the LHDN e-Invoice node to your workflow
  2. Select "Submit Document" operation
  3. Choose "Form Fields (Easy)" as Input Mode
  4. 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
  5. Set Code Number: INV001
  6. Execute - The node will automatically generate UBL 2.1 format!

Using Raw Mode (Advanced Users)

  1. Choose "Raw Document (Advanced)" as Input Mode
  2. Prepare your UBL 2.1 JSON/XML document
  3. Paste the document in the Document field
  4. Set Document Format (JSON/XML)
  5. 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:

  1. Pergi ke Credentials dalam n8n
  2. Klik Create New
  3. Pilih LHDN e-Invoice API
  4. 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:

  1. Daftar di MyInvois Portal
  2. Buat aplikasi baru dalam Developer Portal
  3. Dapatkan Client ID dan Client Secret
  4. Generate atau upload X.509 certificate
  5. 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

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

Workflow 2: Monitor Document Status

  1. Cron Node - Jalankan setiap jam
  2. LHDN e-Invoice Node - Get recent documents
  3. Function Node - Filter dokumen yang perlu dikemaskini
  4. LHDN e-Invoice Node - Get status untuk setiap dokumen
  5. 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

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

Discussion