Package Information
Available Nodes
Documentation
n8n-miva-connector
n8n community node for integrating with Miva eCommerce platforms. Provides programmatic access to Miva's JSON API for managing products, orders, customers, inventory, and fulfillment operations within n8n workflows.
n8n is a fair-code licensed workflow automation platform.
Installation
Build the package files
cd n8n-connector
npm install
npm run build
This installs dependencies and produces the distributable files that n8n loads. The build script clears dist/, compiles TypeScript to JavaScript, and runs the icon build task so the node metadata is ready for packaging. The output is written to dist/, which is the only folder published by this package.
Use the package with n8n (local development)
npm link
npm link makes the package available globally for local development. In your n8n installation, run npm link n8n-nodes-miva so n8n resolves this node from your local build. Re-run npm run build after code changes to refresh the dist/ artifacts, then restart n8n to pick up the latest build.
Follow the installation guide in the n8n community nodes documentation for other ways to use the package file.
Operations
Data Retrieval
- Get Products: Retrieve product information with field selection and pagination
- Get Orders: Access order data with item flattening and field filtering
- Get Customers: Retrieve customer information and account data
Inventory Management
- Adjust Inventory: Update product inventory levels in bulk
- Report Low Inventory: Generate low stock alerts
Order Processing
- Create Returns: Create RMA returns for order items
- Create Shipment: Generate shipments from order line items
- Update Shipments: Modify shipment details and tracking
- Mark Returns Received: Process returned items and adjust inventory
- Acknowledge Orders: Mark orders as acknowledged
Product Management
- Insert Product: Create new products
- Update Product: Modify existing product data
Media Management
- Upload Images: Upload images to products from URLs
- Delete Product Image: Remove images from products
Project Structure
miva-n8n-connector/
├── credentials/
│ └── MivaApi.credentials.ts # API authentication
├── nodes/Miva/ # Main node implementation
│ ├── Miva.node.ts # Entry point & operation routing
│ ├── Miva.node.json # Node metadata
│ ├── index.ts # Module export
│ ├── miva.svg # Node icon
│ ├── operations/ # Business logic implementation
│ │ ├── getProducts.ts # Product retrieval
│ │ ├── getOrders.ts # Order retrieval with flattening
│ │ ├── getCustomers.ts # Customer retrieval
│ │ ├── adjustInventory.ts # Bulk inventory adjustments
│ │ ├── reportLowInventory.ts # Alert generation
│ │ ├── createReturns.ts # RMA return creation
│ │ ├── createShipment.ts # Shipment creation
│ │ ├── updateShipments.ts # Shipment updates
│ │ ├── markReturnsReceived.ts # Return processing
│ │ ├── acknowledgeOrders.ts # Order acknowledgment
│ │ ├── insertProduct.ts # Product creation
│ │ ├── updateProduct.ts # Product updates
│ │ ├── uploadImages.ts # Bulk image uploads
│ │ ├── deleteProductImage.ts # Image deletion
│ │ └── index.ts # Operation exports
│ ├── parameters/ # UI parameter definitions
│ │ ├── common.ts # Shared parameters
│ │ ├── productFields.ts # Product field options
│ │ ├── orderFields.ts # Order field options
│ │ ├── customerFields.ts # Customer field options
│ │ └── index.ts # Parameter exports
│ ├── transport/ # API communication layer
│ │ └── index.ts # HTTP client & transformers
│ ├── utils/ # Shared utilities
│ │ ├── index.ts # Field matching & validation
│ │ └── paginationUtils.ts # Pagination helpers
│ └── types/ # TypeScript definitions
│ └── index.ts # Interfaces & types
├── ARCHITECTURE.md # Technical architecture details
└── package.json # Dependencies & n8n registration
Architecture
The node follows a layered architecture:
- Presentation Layer: UI parameters and field selection
- Orchestration Layer: Operation routing and execution coordination
- Business Logic Layer: Core operation implementations
- Transport Layer: API communication and response transformation
- Utility Layer: Shared helper functions and validation
Processing Patterns
Batch Operations: Process multiple input items in single API calls
getOrders,adjustInventory,createReturns,createShipment,updateShipments,markReturnsReceived,acknowledgeOrders,reportLowInventory
Individual Operations: Process each input item separately
getProducts,getCustomers,uploadImages,deleteProductImage,updateProduct,insertProduct
API Integration
- Authentication: HMAC-SHA256 with base64-encoded signing key
- Request Format: POST requests with JSON body and timestamp
- Response Handling: Automatic transformation from Miva's nested structure to flat objects
- Field Optimization: Dynamic ondemand column filtering for performance
Credentials
Required Configuration
- API Token: Your store's API authorization token
- Base URL: Your Miva store's API endpoint (e.g.,
https://yourstore.com/mm5/json.mvc) - Signing Key: Base64-encoded HMAC signing key for secure communication
Security Features
- All API requests use HMAC-SHA256 authentication
- Credentials stored in n8n's encrypted credential system
- No credential information logged or exposed in error messages
Usage Examples
Basic Product Retrieval
Miva: Get Products
├── Store Code: your_store
├── Count: 100
├── Return Fields: product_code, product_name, product_inventory
└── Include Custom Fields: false
Order Processing with Item Flattening
Miva: Get Orders
├── Store Code: your_store
├── Count: 50
├── Return Fields: id, total, customer, items
├── Order Item Fields: product_code, quantity, price
└── Flatten Items: true
Bulk Inventory Adjustment
Miva: Adjust Inventory
├── Store Code: your_store
├── Product Identifier Type: product_sku
├── Product Identifier Field: sku
└── Adjustment Field: adjustment_amount
Image Upload
Miva: Upload Images
├── Store Code: your_store
├── Product Identifier Type: product_code
├── Product Identifier Field: product_code
├── Image URL Field: image_url
└── File Path Template: graphics/products/{product_code}/{filename}
Field Selection
The node supports dynamic field selection to optimize API performance:
Product Fields: Basic fields like product_code, product_name, product_inventory
Order Fields: Order data including id, total, customer, items
Customer Fields: Customer information and account data
Ondemand Fields: Automatically detected and optimized for performance
- Products:
descrip,catcount,url,product_inventory,attributes - Orders:
ship_method,cust_login,parts,items,charges
Error Handling
- Continue on Fail: Support for n8n's continue-on-fail mode
- Validation: Input parameter validation with helpful error messages
- API Errors: Proper handling of Miva API error responses
- Context Preservation: Error messages include operation context and item index
Performance Considerations
- Pagination: Built-in support for large datasets (up to 10,000 records per request)
- Field Filtering: Response transformation filters unused fields
- Batch Processing: Multiple operations batch data for efficiency
- Memory Management: No retention of large response objects between operations
Development
Building
npm run build
Testing
npm run lint
npm run format
TypeScript
The project uses TypeScript with strict type checking and comprehensive interfaces for all API operations.
Resources
Version History
v1.0.0
- Initial stable release
v0.1.0
- Complete Miva API integration with 14 core operations
- HMAC-SHA256 authentication for all API requests
- Support for products, orders, customers, inventory, and media management
- Advanced features: order flattening, field selection, batch processing
- Comprehensive error handling and validation
- Performance optimizations with ondemand column support
Note: This is a community-maintained node. For issues, feature requests, or contributions, please visit the GitHub repository.