n8n-nodes-mi2u

n8n community node package for MyInvoice2U (Mi2u) ICS API integration. Provides LHDN-compliant e-invoice management for Malaysian businesses.

Table of Contents

• Overview
• Installation
• Available Nodes
• Quick Start
• Usage Guide
• Configuration
• Troubleshooting
• Resources

Overview

This package provides three specialized nodes for Malaysian e-invoice automation:

MyInvoice2u Node (Action): Comprehensive invoice management with authentication, invoice operations (create, search, refund, cancel), and customer management.

Mi2u Trigger Node (Trigger): Real-time webhook-based PDF generation and LHDN validation status monitoring with configurable polling.

WhatsApp Decryption Node (Utility): Decrypt WhatsApp Business API encrypted media files using AES-256-CBC with HKDF key derivation.

Key Capabilities

• LHDN-Compliant: Built-in Malaysian tax codes, state codes, MSIC codes, and classification codes
• Multi-Mode Processing: Manual, Smart (bulk), and Shopify integration modes
• Automatic Grouping: Smart mode groups line items by invoiceCodeNumber for batch processing
• Shopify Integration: Automatic TIN/NRIC extraction from order attributes
• Real-Time Monitoring: Webhook triggers for PDF generation and validation status
• Cookie Management: Automatic authentication with cookie caching and fallback
• Retry Logic: Configurable retry settings with exponential backoff
• Malaysian Timezone: Auto-generates invoice dates/times in Asia/Kuala_Lumpur timezone
• Phone Formatting: Automatic Malaysian phone number formatting (removes country codes)

Installation

Prerequisites

• n8n version 0.200.0 or higher
• Node.js 20.15 or higher
• MyInvoice2U account with ICS API credentials

Install via n8n Community Marketplace

1. Go to Settings → Community Nodes
2. Click Install a Community Node
3. Enter n8n-nodes-mi2u
4. Click Install

Install via npm

npm install n8n-nodes-mi2u

Docker Installation

FROM n8nio/n8n:latest
RUN npm install n8n-nodes-mi2u

Available Nodes

MyInvoice2u Node

Consolidated action node using resource-based organization with delegation pattern.

Resources:

• Authentication: Login (get token), Detect Credentials (validate user)
• Invoice: Create, Search, Refund, Cancel/Void
• Customer: Get Expiring Customers

Processing Modes (Create/Refund):

• Manual Mode: Individual invoice entry with full field control
• Smart Mode: Bulk processing from JSON/Excel/CSV with automatic line item grouping by invoiceCodeNumber
• Shopify Mode: Direct Shopify order integration with automatic TIN/NRIC extraction from note_attributes

Architecture:

• Uses delegation pattern to route operations to specialized nodes
• Dynamic property inheritance based on resource/operation selection
• Maintains backward compatibility with individual nodes

Mi2u Trigger Node

Webhook trigger node for real-time monitoring and PDF generation.

Operations:

• PDF Generation: Two modes available
  • Self-Validate Mode: Automatically polls LHDN status then generates PDF
  • Wait-for-Validation Mode: Generates PDF from validated invoice data
• LHDN Status Check: Real-time validation status monitoring via webhook

Configuration:

• Polling interval: 5 seconds (default, configurable)
• Max polling attempts: 20 (default, configurable)
• Authentication: HTTP cookie with automatic credential fallback
• Webhook path: /mi2u-trigger
• Response mode: onReceived

WhatsApp Decryption Node

Utility node for WhatsApp Business API media decryption.

Features:

• Encryption: AES-256-CBC decryption with HKDF key derivation
• Media Types: Supports image, video, audio, document, and text files
• Integrity Verification: Optional SHA256 hash verification
• Output Format: Standard n8n binary data compatible with other nodes
• Input: Encrypted file URL, media key (base64), MIME type, file name
• Output: Decrypted binary data in specified property name (default: 'data')

Quick Start

Setup Credentials

1. Go to Credentials → Create New
2. Select Mi2u API
3. Enter your MyInvoice2U username and password
4. Save

Create Your First Invoice

1. Add MyInvoice2u node
2. Select Resource: Invoice
3. Select Operation: Create Invoice
4. Choose Processing Mode: Manual Mode
5. Fill in supplier, buyer, and line item details
6. Execute workflow

Common Workflows

Simple Invoice Creation:

Schedule Trigger → MyInvoice2u (Invoice > Create, Manual Mode)

Bulk Invoice Processing:

Spreadsheet File → Read Binary File → Convert to JSON → MyInvoice2u (Invoice > Create, Smart Mode)

Complete E-Invoice Automation:

Webhook → MyInvoice2u (Create) → Mi2u Trigger (LHDN Status) → Mi2u Trigger (PDF) → Email/Telegram

Shopify Order Integration:

Shopify Trigger → MyInvoice2u (Invoice > Create, Shopify Mode) → Mi2u Trigger (PDF) → Email Customer

Refund Processing:

Refund Request → MyInvoice2u (Invoice > Refund, Smart Mode) → Mi2u Trigger (PDF) → Notification

WhatsApp Document Processing:

WhatsApp Webhook → WhatsApp Decryption → Spreadsheet Read → MyInvoice2u (Create, Smart Mode)

Usage Guide

Authentication Operations

Login: Get authentication token for API access

• Input: Username, password
• Output: Authentication cookie and token

Detect Credentials: Validate user credentials

• Input: Email, TIN
• Output: User validation status

Invoice Operations

Create Invoice

Three processing modes available:

1. Manual Mode: Individual invoice entry with full field control. Use for custom invoices and corrections.

2. Smart Mode: Bulk processing from structured data (JSON/Excel/CSV). Automatically groups line items by invoiceCodeNumber. Use for batch imports and ERP integration.

Example input:

[
  {
    "invoiceCodeNumber": "INV-001",
    "supplierTin": "C1234567890",
    "buyerName": "Customer ABC",
    "itemDescription": "Product A",
    "quantity": 2,
    "unitPrice": 100.00
  }
]

3. Shopify Mode: Direct Shopify order integration. Automatically extracts TIN/NRIC from order attributes. Configurable supplier settings and automatic date generation.

Required Shopify data structure:

{
  "note_attributes": [
    {"name": "TIN", "value": "IG40176873020"},
    {"name": "NRIC", "value": "960528016739"}
  ],
  "line_items": [...],
  "customer": {...}
}

Output includes invoice details, return codes, and complete invoice data.

Search Invoice: Find existing invoices by TIN and document number. Returns complete invoice data.

Refund Invoice: Create credit notes automatically. Searches for original invoice, generates refund with invoice type 04, and auto-generates refund number.

Cancel Invoice: Cancel or void invoices with LHDN-compliant reason codes (01-08). Supports both cancel (MY103) and void (MY109) operations.

Customer Operations

Get Expiring Customers: Fetch customers with expiring subscriptions. Configurable days threshold and pagination support.

Trigger Operations

PDF Generation

Two modes:

• Self-Validate: Automatically polls LHDN status then generates PDF
• Wait-for-Validation: Generates PDF from validated invoice data

Configuration: 5-second polling interval, 20 max attempts (both configurable)

LHDN Status Check: Real-time validation status monitoring via webhook. Polls validation status and returns LHDN response data.

WhatsApp Decryption

Decrypt WhatsApp Business API encrypted media files using AES-256-CBC with HKDF key derivation. Input encrypted file URL and media key, outputs decrypted binary data.

Configuration

Shopify Integration

Add custom checkout fields to collect TIN/NRIC:

<input name="attributes[TIN]" placeholder="Company TIN (Optional)">
<input name="attributes[NRIC]" placeholder="NRIC (Optional)">

Data must be in note_attributes format for the node to process correctly.

LHDN Codes

Built-in Malaysian tax authority codes:

States: 01-17 (Johor, Kedah, Kelantan, Melaka, Negeri Sembilan, Pahang, Pulau Pinang, Perak, Perlis, Selangor, Terengganu, Sabah, Sarawak, WP Kuala Lumpur, WP Labuan, WP Putrajaya, Unknown)

Countries: ISO 3166-1 alpha-3 codes (MYS, SGP, THA, IDN, etc.)

Currencies: ISO 4217 codes (MYR, USD, EUR, SGD, GBP, etc.)

Tax Types: 01-Standard Rate, 02-Zero Rate, 03-Exempt, 04-Sales Tax, 05-Service Tax, 06-Tourism Tax

Classification: MSIC codes for product and service classifications

API Configuration

Base URL: https://ics-uat.myinvoice2u.com/MYWs/ws/api/

Interfaces: LOGIN, MY101 (create/refund), MY103 (cancel), MY109 (void), MY111 (search), getauthcode

Authentication

Three methods supported:

1. Mi2u API Credentials (recommended): Stored in n8n credentials with automatic session management
2. HTTP Cookie: Pass from previous nodes, falls back to credentials if invalid
3. Manual Token: Direct token input for custom flows

Retry Settings

Default configuration:

• Max tries: 3
• Wait between tries: 5 seconds
• Retry on fail: Enabled

Configurable in node settings.

Troubleshooting

Common Issues

Authentication Failed

• Verify Mi2u API credentials are correct
• Check if HTTP cookie is valid (if using cookie authentication)
• Auto-login fallback activates when no cookie provided

Polling Too Slow

• Default is 5 seconds (configurable)
• Enable custom polling settings to adjust interval
• Increase max attempts if needed (default: 20)

Operations Not Found

• Use Resource → Operation selection
• Properties load dynamically based on selection
• Triggers use separate Mi2u Trigger node

Error Codes

• 00 - Success
• 01 - Authentication failed
• 02 - Invalid parameters
• 03 - Invoice not found
• 04 - Validation failed

Support

• GitHub Issues: Bug reports and feature requests
• n8n Community Forum: Workflow questions
• MyInvoice2U Support: API-specific issues

Resources

Documentation

• MyInvoice2U Website
• LHDN E-Invoice Portal
• n8n Documentation

Development

• GitHub Repository
• Issue Tracker

Changelog

v0.3.1 (Current)

Architecture:

• Consolidated 8+ individual nodes into 3 specialized nodes
• Resource-based organization with delegation pattern
• MyInvoice2u node (Action) with 3 resources: Authentication, Invoice, Customer
• Mi2u Trigger node with 2 operations: PDF Generation, LHDN Status Check
• WhatsApp Decryption utility node

Performance:

• Cookie caching with automatic expiration
• Exponential backoff retry logic and polling
• Optimized authentication with credential fallback

Features:

• Customer Operations: Get expiring customers with pagination
• WhatsApp Integration: AES-256-CBC decryption with HKDF
• Enhanced Output: Root-level fields for easy Telegram/notification integration
• Issue Mode Detection: Automatic determination based on buyer information
• Phone Formatting: Malaysian phone number normalization
• State Mapping: Shopify province code to LHDN state code conversion

Bug Fixes:

• Fixed issueMode logic for smart mode processing
• Corrected buyer TIN property path validation
• Resolved multi-item processing validation errors
• Fixed cookie authentication fallback

Previous Versions

• v0.2.4: Consolidated nodes, WhatsApp decryption, customer management
• v0.2.3: Independent refund/cancel modes
• v0.2.2: UI improvements
• v0.2.1: Shopify integration
• v0.2.0: Smart mode and bulk processing
• v0.1.x: Initial release

Migration Guide

Upgrading from v0.2.3 is backward compatible. Existing workflows continue working without modification.

Optional migration:

| Old Node | New Node | Configuration | |----------|----------|---------------| | Mi2u | MyInvoice2u | Authentication > Login | | Mi2uAuth | MyInvoice2u | Authentication > Detect | | Mi2uCreate | MyInvoice2u | Invoice > Create | | Mi2uSearch | MyInvoice2u | Invoice > Search | | Mi2uRefund | MyInvoice2u | Invoice > Refund | | Mi2uCancel | MyInvoice2u | Invoice > Cancel | | Mi2uPdf | Mi2u Trigger | PDF Generation | | Mi2uLhdnValidStatus | Mi2u Trigger | LHDN Status Check |

License

MIT License - Copyright 2024 Axiom (MyInvoice2U)

Contributors

Author: Axiom ([email protected])
Organization: MyInvoice2U
Repository: github.com/n1xuy/n8n-nodes-mi2u