@brokenrubik/n8n-nodes-ns

v1.3.0

Published

a month ago

n8n node for NetSuite SuiteTalk REST API integration

0High
0Medium
0Low

brokenrubik

n8n-community-node-package netsuite suitetalk n8n

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

Navigate to Integration Setup:
- Log into your NetSuite account
- Go to Setup → Integration → Manage Integrations → New
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
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

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
```
Alternative: Using NetSuite's Guide:
- Follow NetSuite's official certificate generation guide: Creating Certificates for OAuth 2.0

Step 3: Upload Certificate to NetSuite

Navigate to Certificate Setup:
- Go to Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup
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
Copy Certificate ID:
- After saving, copy the generated Certificate ID
- You'll need this for the n8n credentials

Step 4: Set Up n8n Credentials

Open n8n:
- Navigate to Credentials in n8n
- Click "Add Credential"
- Select "NetSuite API"
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)

PEM Content Format:

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

Step 5: Test the Connection

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": "[email protected]",
  "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