n8n-node-netsuite

A comprehensive n8n node for NetSuite integration, providing full access to NetSuite's SuiteTalk REST API with OAuth 2.0 M2M authentication.

Features

🔐 Secure Authentication

• OAuth 2.0 Machine-to-Machine (M2M) authentication
• JWT token-based authentication with PS256 algorithm
• Automatic token caching and refresh
• Certificate-based security

📊 Complete CRUD Operations

• List Records: Retrieve multiple records with pagination support
• Get Record: Fetch individual records by ID
• Insert Record: Create new records
• Update Record: Modify existing records
• Remove Record: Delete records

🔍 Advanced Query Capabilities

• SuiteQL Support: Execute SQL-like queries against NetSuite data
• Raw API Requests: Direct access to any NetSuite REST endpoint
• Pagination Handling: Automatic handling of large result sets
• Query Parameters: Support for filters, limits, and offsets

🛠️ Developer-Friendly Features

• Modular Architecture: Clean, maintainable code structure
• Comprehensive Error Handling: NetSuite-specific error parsing and reporting
• TypeScript Support: Full type safety and IntelliSense
• Extensive Documentation: Detailed comments and examples

Prerequisites

System Requirements

• Node.js 20+ and npm
• n8n installed globally: npm install n8n -g

NetSuite Requirements

• NetSuite account with REST API access
• OAuth 2.0 Application configured in NetSuite
• Certificate and private key for M2M authentication
• Appropriate permissions for the operations you want to perform

Installation

For Development

# Clone the repository
git clone https://github.com/BrokenRubik/n8n-netsuite-node
cd n8n-netsuite-node

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Restart n8n to load the new node: https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/

Setup Instructions

Step 1: Create NetSuite Integration Record

1. Navigate to Integration Setup:

   • Log into your NetSuite account
   • Go to Setup → Integration → Manage Integrations → New

2. Configure Integration:

   • Enter a Name for your integration (e.g., "n8n NetSuite Integration")
   • Set State to "Enabled"
   • Under Client Credentials (M2M), check "Client Credentials (Machine To Machine) Grant"
   • Leave all other checkboxes unchecked
   • Click Save

3. Copy Integration Client ID:

   • ⚠️ Important: After saving, immediately copy the Integration Client ID
   • This ID will disappear if you close the tab or navigate away
   • Store it securely as you'll need it for the n8n credentials

Step 2: Generate Certificate and Private Key

1. Create Certificate Pair:

   • Open a terminal/command prompt
   • Generate a private key and certificate using OpenSSL:

   openssl req -x509 -newkey rsa:3072 -keyout n8n_key.pem -out n8n_cert.pem -days 365 -nodes\n
   

2. Alternative: Using NetSuite's Guide:

   • Follow NetSuite's official certificate generation guide: Creating Certificates for OAuth 2.0

Step 3: Upload Certificate to NetSuite

1. Navigate to Certificate Setup:

   • Go to Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup

2. Upload Certificate:

   • Click "New" to create a new certificate entry
   • Enter a Name for the certificate (e.g., "n8n Integration Certificate")
   • Upload the certificate file (n8n_cert.pem) - not the private key
   • Click Save

3. Copy Certificate ID:

   • After saving, copy the generated Certificate ID
   • You'll need this for the n8n credentials

Step 4: Set Up n8n Credentials

1. Open n8n:

   • Navigate to Credentials in n8n
   • Click "Add Credential"
   • Select "NetSuite API"

2. Enter Credential Information:

   • Account ID: Your NetSuite account ID (e.g., "1234567" or "1234567_SB1" for sandbox)
   • Integration Client ID: The ID copied from Step 1
   • Certificate ID (M2M): The ID copied from Step 3
   • PEM Content: Copy and paste the entire content of your private key file (n8n_key.pem)

3. PEM Content Format:

   -----BEGIN PRIVATE KEY-----
   MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...
   ... (your private key content) ...
   -----END PRIVATE KEY-----
   

Step 5: Test the Connection

1. Create a Test Workflow:
   • Create a new workflow in n8n
   • Add a NetSuite node
   • Configure it to list a simple record type (e.g., Customer)
   • Execute the workflow to verify the connection

Usage Examples

List Sales Orders

// Operation: List Records
// Record Type: Sales Order
// Query: status:pendingFulfillment
// Limit: 100

Create Customer Record

// Operation: Insert Record
// Record Type: Customer
// Input data:
{
  "companyName": "Acme Corp",
  "email": "contact@acme.com",
  "phone": "+1-555-0123"
}

Execute SuiteQL Query

// Operation: Execute SuiteQL
// Query: SELECT id, companyName FROM customer WHERE dateCreated >= '2024-01-01'
// Limit: 1000

Raw API Request

// Operation: Raw Request
// Method: GET
// Path: /services/rest/record/v1/customer/123
// Full Response: true

Architecture

Modular Design

• Main Node: Orchestrates operations and handles authentication
• Service Layer: Manages API communication and token handling
• Operation Modules: Individual handlers for each operation type
• Type System: Comprehensive TypeScript definitions
• Utilities: Shared helper functions and response handlers

Error Handling

• Follows NetSuite's official error format documentation
• Provides detailed error messages with context
• Supports graceful degradation with "Continue on Fail"
• Includes error codes, paths, and actionable guidance

Development

Project Structure

├── nodes/NetSuite/
│   ├── types/           # TypeScript type definitions
│   ├── utils/           # Utility functions
│   ├── operations/      # Operation implementations
│   ├── NetSuite.node.ts # Main node class
│   └── NetSuite.service.ts # API service layer
├── credentials/         # Authentication configuration
└── dist/               # Built output

Adding New Operations

1. Create operation file in operations/ directory
2. Export function from operations/index.ts
3. Add case to switch statement in NetSuite.node.ts
4. Add UI configuration to NetSuite.node.options.ts

Troubleshooting

Debug Information

• Enable debug logging with DEBUG=n8n-nodes-netsuite
• Check n8n logs for detailed error messages
• Verify NetSuite audit trail for failed requests