Integrasi API MyInvois LHDN untuk WooCommerce

Panduan teknikal integrasi API MyInvois LHDN v1.0 dengan WooCommerce dan aplikasi kustom. Merangkumi OAuth 2.0, UBL 2.1 JSON, dan kod QR pengesahan.

Pelaksanaan mandat e-Invois oleh Lembaga Hasil Dalam Negeri (LHDN) kini menjadi kewajipan undang-undang bagi semua perniagaan di Malaysia. Bagi pemilik kedai WooCommerce, platform SaaS, atau aplikasi web kustom dengan jumlah transaksi tinggi, memasukkan data invois secara manual ke Portal MyInvois adalah mustahil.

Untuk memastikan pematuhan undang-undang percukaian tanpa mengganggu operasi jualan, laman web anda perlu dihubungkan secara terus melalui API Integrasi Sistem MyInvois LHDN (v1.0).

Berikut adalah panduan seni bina kejuruteraan lengkap untuk mengintegrasikan API MyInvois dengan WooCommerce dan aplikasi web berasaskan PHP/Node.js.

1. Seni Bina API MyInvois LHDN & Pengesahan OAuth 2.0

Semua komunikasi data dengan pelayan LHDN menggunakan protokol OAuth 2.0 Client Credentials Grant menggunakan kunci kelayakan yang dijana melalui Portal Pembayar Cukai MyInvois (Sandbox & Pengeluaran).

+----------------------------------------------------------------------+
|                     ALIRAN INTEGRASI MYINVOIS LHDN                   |
|                                                                      |
| 1. Pesanan WooCommerce ---> 2. Token OAuth 2.0 ---> 3. UBL 2.1 JSON  |
|    (Status: Selesai)        (Identity Server)       (Base64 SHA256)  |
|                                                           |          |
| 5. Simpan QR & UUID   <---  4. Pengesahan LHDN   <---------+         |
|    (PDF & E-mel Klien)      (UUID Sah & Status Sah)                  |
+----------------------------------------------------------------------+

Langkah 1: Mendapatkan Token Capaian (Access Token)

Hantar permintaan disahkan ke Pelayan Identiti LHDN:

# Permintaan Token OAuth 2.0 (Persekitaran Pra-Pengeluaran / Sandbox)
curl -X POST "https://preprod-api.myinvois.hasil.gov.my/connect/token"   -H "Content-Type: application/x-www-form-urlencoded"   -d "client_id=LHDN_CLIENT_ID_ANDA"   -d "client_secret=LHDN_CLIENT_SECRET_ANDA"   -d "grant_type=client_credentials"   -d "scope=InvoicingAPI"

Pelayan akan mengembalikan token bearer yang sah selama 3,600 saat:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "InvoicingAPI"
}

2. Struktur Dokumen UBL 2.1 & Medan Data Wajib Malaysia

LHDN menetapkan bahawa setiap dokumen e-Invois mesti mematuhi format standard Universal Business Language (UBL 2.1) dalam struktur JSON atau XML.

Medan Data Pengenalan Perniagaan Wajib:

TIN Pembeli (Nombor Pengenalan Cukai): Contohnya C12345678090 atau EI00000000010 untuk e-invois disatukan (consolidated).
Nombor Pendaftaran Pembeli: Nombor Pendaftaran SSM (Format 12-digit baharu), No. Kad Pengenalan (MyKad), atau Pasport.
Nombor Pendaftaran Cukai Jualan & Perkhidmatan (SST): Sekiranya berkenaan.
Kod MSIC: Kod Klasifikasi Industri Standard Malaysia 5-digit (contoh: 47912 untuk Jualan runcit melalui internet).
Kod Klasifikasi Produk/Perkhidmatan: Kod klasifikasi item LHDN (contoh: 001 untuk Barangan, 002 untuk Perkhidmatan).

Contoh Muatan JSON UBL 2.1:

{
  "_D": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
  "_A": "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
  "_B": "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
  "Invoice": [
    {
      "ID": [{ "_": "INV-2026-08001" }],
      "IssueDate": [{ "_": "2026-08-29" }],
      "IssueTime": [{ "_": "14:30:00Z" }],
      "InvoiceTypeCode": [{ "_": "01", "listVersionID": "1.0" }],
      "DocumentCurrencyCode": [{ "_": "MYR" }],
      "AccountingSupplierParty": [
        {
          "Party": [
            {
              "PartyIdentification": [
                { "ID": [{ "_": "C25892341020", "schemeID": "TIN" }] },
                { "ID": [{ "_": "202401009876", "schemeID": "BRN" }] }
              ],
              "PartyLegalEntity": [
                { "RegistrationName": [{ "_": "TECHFIX MALAYSIA SDN BHD" }] }
              ]
            }
          ]
        }
      ]
    }
  ]
}

3. Integrasi WooCommerce: Skrip Penghantaran Automatik

Untuk menghantar invois secara automatik sejurus selepas transaksi pembayaran disahkan (contohnya melalui Billplz, Curlec, atau FPX), sambungkan skrip ke cangkuk (hook) penyelesaian pesanan WooCommerce:

<?php
/**
 * Sambung ke Cangkuk Status Pesanan WooCommerce Selesai
 */
add_action('woocommerce_order_status_completed', 'jagaweb_hantar_lhdn_einvois', 10, 1);

function jagaweb_hantar_lhdn_einvois($order_id) {
    $order = wc_get_order($order_id);
    
    // Semak sama ada e-Invois telah dihantar sebelum ini
    if ($order->get_meta('_lhdn_invoice_uuid')) {
        return;
    }

    $buyer_tin   = $order->get_meta('_billing_tin') ?: 'EI00000000010'; // TIN lalai e-invois disatukan
    $buyer_brn   = $order->get_meta('_billing_brn') ?: $order->get_meta('_billing_mykad');
    $order_total = $order->get_total();

    // 1. Bina Struktur Dokumen
    $document_data_raw = [
        'Invoice' => [
            'ID' => [['_' => 'ORD-' . $order->get_order_number()]],
            'IssueDate' => [['_' => gmdate('Y-m-d')]],
            'IssueTime' => [['_' => gmdate('H:i:sZ')]],
            'InvoiceTypeCode' => [['_' => '01']],
            'LegalMonetaryTotal' => [
                ['PayableAmount' => [['_' => (float)$order_total, 'currencyID' => 'MYR']]]
            ]
        ]
    ];

    $document_json = json_encode($document_data_raw);
    $document_data = [
        'format' => 'JSON',
        'document' => base64_encode($document_json),
        'documentHash' => hash('sha256', $document_json),
        'codeNumber' => 'ORD-' . $order->get_order_number()
    ];

    // 2. Hantar ke API LHDN
    $api_token = jagaweb_dapatkan_token_lhdn();
    $response = wp_remote_post('https://preprod-api.myinvois.hasil.gov.my/api/v1.0/documentsubmissions/', [
        'headers' => [
            'Authorization' => 'Bearer ' . $api_token,
            'Content-Type'  => 'application/json'
        ],
        'body' => json_encode(['documents' => [$document_data]]),
        'timeout' => 30
    ]);

    if (!is_wp_error($response)) {
        $body = json_decode(wp_remote_retrieve_body($response), true);
        if (!empty($body['acceptedDocuments'][0]['uuid'])) {
            $uuid = $body['acceptedDocuments'][0]['uuid'];
            $order->update_meta_data('_lhdn_invoice_uuid', $uuid);
            $order->update_meta_data('_lhdn_validation_url', "https://myinvois.hasil.gov.my/{$uuid}/share");
            $order->save();
        }
    }
}

4. Pengendalian e-Invois Disatukan (Consolidated B2C)

Berdasarkan garis panduan rasmi LHDN, perniagaan e-dagang yang melayani pengguna individu dibenarkan menyatukan transaksi runcit harian dan menghantar e-Invois Disatukan dalam tempoh 7 hari kalendar selepas akhir bulan:

Nama Pembeli: Pembeli Am / General Public
TIN Pembeli: EI00000000010
ID Pembeli: NA
Sistem pengantara kustom perlu menjadualkan tugas cron automatik untuk mengumpulkan semua transaksi B2C yang tidak memohon invois individu.

Penyelesaian Ralat Lazim API LHDN

+----------------------------+-----------------------------------+-----------------------------------+
| Kod Ralat / Status         | Punca Masalah                     | Tindakan Pembetulan               |
+----------------------------+-----------------------------------+-----------------------------------+
| 400 Bad Request            | Skema dokumen UBL tidak sah       | Semak padanan medan JSON wajib    |
| DS302                      | Nombor Cukai (TIN) tidak wujud    | Sahkan format TIN pembeli         |
| DS308                      | Ketidakpadanan jumlah barisan item| Bundarkan jumlah item ke 2 desimal|
| 401 Unauthorized           | Token Bearer telah tamat tempoh   | Laksanakan pembaharuan token auto |
+----------------------------+-----------------------------------+-----------------------------------+

Automasi Pematuhan e-Invois Laman Web Anda Bersama JagaWeb

Menyambungkan sistem MyInvois LHDN ke WooCommerce atau platform web kustom memerlukan pengesahan skema yang ketat, enkripsi dokumen kriptografi, dan sistem pengendalian ralat yang lancar.

JagaWeb membangunkan perisian pengantara (middleware) dan integrasi API khusus untuk perniagaan di Malaysia.

Semakan Seni Bina & Akses RM5,000: Audit proses pembayaran, pangkalan data, dan titik integrasi invois untuk kesiapsiagaan penuh LHDN.
Pembangunan Middleware Kustom: Integrasi webhook penuh dengan pengesahan automatik, penjanaan kod QR pada invois PDF, dan penghantaran e-invois disatukan bulanan.
Pelan Penjagaan RM450/bulan: Pemantauan API berterusan, kemas kini versi skema LHDN, dan sokongan teknikal 24/7.

Hubungi Pasukan JagaWeb untuk Integrasi API MyInvois LHDN.

Integrasi API MyInvois LHDN untuk Laman Web WooCommerce & Kustom di Malaysia