n8n-nodes-opencart

n8n-nodes-opencart

A comprehensive n8n node for OpenCart API integration, providing full CRUD operations and webhook support for e-commerce automation workflows.

Features

🚀 Comprehensive API Coverage

• Products: Full CRUD operations with categories, attributes, options, images
• Categories: Hierarchical category management
• Customers: Customer profiles, addresses, groups
• Orders: Order management, status updates, history tracking
• Manufacturers: Brand and manufacturer data
• Options & Filters: Product variations and filtering
• Reviews & Wishlists: Customer feedback and preferences
• Coupons & Vouchers: Discount code management
• Geographic Data: Countries, zones, currencies, languages
• Store Management: Multi-store configurations
• Content Pages: Information pages and downloads
• Returns & Rewards: Customer service and loyalty programs

🔐 Flexible Authentication

• API Key Authentication: Secure key-based access
• OAuth 2.0: Modern token-based authentication
• Multi-version Support: OpenCart 3.x and 4.x compatibility

⚡ Advanced Features

• Batch Operations: Process multiple records efficiently
• Pagination Support: Handle large datasets with automatic pagination
• Filtering & Sorting: Advanced query capabilities
• Retry Logic: Exponential backoff for failed requests
• Error Handling: Comprehensive error reporting and recovery
• Rate Limiting: Respect API limits and quotas
• Webhook Support: Real-time event notifications

Installation

From npm Registry

npm install n8n-nodes-opencart

From Source

git clone https://github.com/kilocode/n8n-nodes-opencart.git
cd n8n-nodes-opencart
npm install
npm run build
npm link

In n8n

• Install the package in your n8n installation directory
• Restart n8n
• The OpenCart node will be available in the node palette

Configuration

API Key Authentication

• In your OpenCart admin panel, go to System → Users → API
• Create or edit an API user
• Generate an API key
• Configure the credentials in n8n:
  • Base URL: https://your-store.com (without trailing slash)
  • API Version: Select your OpenCart version (3.x or 4.x)
  • Authentication Method: API Key
  • API Key: Your generated API key

OAuth 2.0 Authentication

• Set up OAuth 2.0 in your OpenCart installation
• Create OAuth client credentials
• Configure in n8n:
  • Base URL: https://your-store.com
  • API Version: Select your OpenCart version
  • Client ID: Your OAuth client ID
  • Client Secret: Your OAuth client secret
  • Scope: read write (or specific scopes as needed)

Usage Examples

Get All Products with Filtering

// Node configuration
Resource: Products
Operation: Get All
Additional Fields:
  - Filter Name: "laptop"
  - Filter Status: Enabled
  - Sort By: name
  - Sort Order: ASC
  - Limit: 50

Create New Product

{
  "name": "Gaming Laptop",
  "description": "High-performance gaming laptop",
  "model": "GL-2023",
  "price": "1299.99",
  "quantity": "10",
  "status": "1",
  "categories": ["laptops", "gaming"],
  "manufacturer_id": "5"
}

Batch Operations

// Create multiple products at once
[
  {
    "operation": "create",
    "data": {
      "name": "Product 1",
      "price": "99.99",
      "model": "P1-2023"
    }
  },
  {
    "operation": "update", 
    "id": "123",
    "data": {
      "price": "89.99"
    }
  },
  {
    "operation": "delete",
    "id": "456"
  }
]

Order Management Workflow

// 1. Get pending orders
Resource: Orders
Operation: Get All
Filters: 
  - filter_order_status_id: "1" // Pending status

// 2. Update order status
Resource: Orders  
Operation: Update
Resource ID: "{{$json.order_id}}"
Data: {
  "order_status_id": "2", // Processing
  "comment": "Order confirmed and processing started",
  "notify": "1"
}

// 3. Send notification email (via Email node)

API Endpoints Reference

Products API

Get All Products

• Method: GET /api/products
• Parameters:
  • page: Page number
  • limit: Results per page
  • sort: Sort field
  • order: Sort direction (ASC/DESC)
  • filter_name: Filter by name
  • filter_status: Filter by status
  • filter_category_id: Filter by category

Get Single Product

• Method: GET /api/products/{id}
• Response: Full product details with options, images, categories

Create Product

• Method: POST /api/products
• Required Fields: name, model, price
• Optional Fields: description, categories, manufacturer_id, images, options

Update Product

• Method: PUT /api/products/{id}
• Body: Product fields to update

Delete Product

• Method: DELETE /api/products/{id}

Orders API

Get All Orders

• Method: GET /api/orders
• Parameters:
  • filter_order_id: Filter by order ID
  • filter_customer: Filter by customer name
  • filter_order_status_id: Filter by status
  • filter_date_from: Filter by date range
  • filter_date_to: Filter by date range

Get Order Details

• Method: GET /api/orders/{id}
• Response: Complete order with products, totals, history

Update Order Status

• Method: PUT /api/orders/{id}
• Body:

{
  "order_status_id": "2",
  "comment": "Status updated",
  "notify": "1"
}

Customers API

Get All Customers

• Method: GET /api/customers
• Parameters: Standard filtering and pagination

Get Customer Details

• Method: GET /api/customers/{id}
• Response: Customer profile with addresses, orders

Create Customer

• Method: POST /api/customers
• Required: firstname, lastname, email, password

Categories API

Get Category Tree

• Method: GET /api/categories
• Response: Hierarchical category structure

Create Category

• Method: POST /api/categories
• Required: name, parent_id

Webhook Integration

Webhook Events

The node supports real-time webhooks for:

• order.created: New order placed
• order.updated: Order status changed
• product.created: New product added
• product.updated: Product modified
• customer.created: New customer registered

Webhook Configuration

• Set up webhook endpoint in your OpenCart module
• Configure webhook URL in n8n workflow
• Handle incoming webhook data:

// Webhook payload example
{
  "event": "order.created",
  "data": {
    "order_id": "123",
    "customer_email": "[e-mail]", 
    "total": "99.99",
    "status": "pending"
  },
  "timestamp": "2023-12-01T10:00:00Z"
}

Error Handling

Common Error Codes

• 401 Unauthorized: Invalid API credentials
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource doesn't exist
• 422 Validation Error: Invalid data provided
• 429 Rate Limited: Too many requests
• 500 Server Error: OpenCart server error

Error Response Format

{
  "error": true,
  "message": "Product not found",
  "code": "PRODUCT_NOT_FOUND",
  "details": {
    "product_id": "999"
  }
}

Retry Configuration

The node automatically retries failed requests with exponential backoff:

• Default Retries: 3 attempts
• Base Delay: 1000ms
• Backoff Multiplier: 2x
• Max Delay: 30 seconds

Performance Optimization

Batch Processing

Use batch operations for:

• Bulk product imports
• Mass price updates
• Multiple order processing
• Category restructuring

Pagination Best Practices

• Use reasonable page sizes (50-100 records)
• Process pages sequentially for data consistency
• Implement progress tracking for large datasets

Rate Limiting

• Respect OpenCart server limits (typically 60 requests/minute)
• Implement delays between requests if needed
• Use batch operations to reduce total API calls

Troubleshooting

Connection Issues

• Verify base URL is correct and accessible
• Check API credentials are valid
• Ensure OpenCart API is enabled
• Verify SSL certificate if using HTTPS

Authentication Problems

• Confirm API user has proper permissions
• Check API key hasn't expired
• Verify OAuth scopes are sufficient
• Test credentials with simple GET request

Data Issues

• Validate JSON data format
• Check required fields are provided
• Verify field value constraints
• Review OpenCart logs for detailed errors

Performance Issues

• Reduce batch sizes if timeout errors occur
• Increase timeout values for large operations
• Implement pagination for large datasets
• Consider off-peak processing for bulk operations

Development

Local Development

git clone https://github.com/kilocode/n8n-nodes-opencart.git
cd n8n-nodes-opencart
npm install
npm run dev

Building

npm run build

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests (requires OpenCart instance)
npm run test:integration

Contributing

• Fork the repository
• Create feature branch (git checkout -b feature/amazing-feature)
• Commit changes (git commit -m 'Add amazing feature')
• Push to branch (git push origin feature/amazing-feature)
• Open Pull Request

Compatibility

OpenCart Versions

• ✅ OpenCart 3.0.x
• ✅ OpenCart 3.1.x
• ✅ OpenCart 4.0.x
• ⏳ OpenCart 4.1.x (coming soon)

n8n Versions

• ✅ n8n 0.200.0+
• ✅ n8n 1.0.0+

Node.js Versions

• ✅ Node.js 16.x
• ✅ Node.js 18.x
• ✅ Node.js 20.x

Support

Documentation

• OpenCart API Docs
• n8n Node Development

Community

• GitHub Issues
• n8n Community Forum
• OpenCart Community

Commercial Support

For enterprise support, custom development, or consulting services:

• Email: [e-mail]
• Website: https://kilocode.com

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0 (2023-12-01)

• 🎉 Initial release
• ✅ Complete CRUD operations for all OpenCart resources
• ✅ API Key and OAuth 2.0 authentication
• ✅ Batch operations support
• ✅ Comprehensive error handling and retry logic
• ✅ Pagination and filtering capabilities
• ✅ Webhook integration
• ✅ OpenCart 3.x and 4.x support
• ✅ Full TypeScript implementation
• ✅ 90%+ test coverage

Made with ❤️ by Kilo Code