n8n-nodes-zid

Custom n8n nodes for integrating with the Zid API (orders, products, customers, etc.)

Overview

This package provides n8n nodes to connect your workflows to the Zid platform, enabling automation of order management, product updates, customer data retrieval, and more. Built with TypeScript and following n8n's best practices.

Features

• OAuth2 Authentication: Secure authentication with Zid using OAuth2
• Comprehensive API Coverage: Support for orders, products, and customers
• Trigger Nodes: Automatically trigger workflows on new orders or customers
• Action Nodes: Perform CRUD operations on Zid resources
• Error Handling: Graceful error handling with clear feedback
• Pagination Support: Handle large datasets efficiently
• Rate Limiting: Respect Zid API rate limits with retry logic

Installation

npm install n8n-nodes-zid

Setup

1. OAuth2 Credentials

Before using the Zid nodes, you need to set up OAuth2 credentials:

1. Go to your Zid developer dashboard
2. Create a new application
3. Note down your Client ID and Client Secret
4. Set the redirect URI to your n8n instance

2. Configure Credentials in n8n

1. In n8n, go to Settings > Credentials
2. Click Create New Credential
3. Select Zid OAuth2 API
4. Fill in the required fields:
   • Client ID: Your Zid application client ID
   • Client Secret: Your Zid application client secret
   • Authorization URL: https://accounts.zid.sa/oauth2/authorize
   • Access Token URL: https://accounts.zid.sa/oauth2/token
   • Scope: (optional) Specific OAuth2 scopes if required

Supported Operations

Trigger Nodes

Zid Order Trigger

• New Order: Triggers when a new order is created
• Order Status Updated: Triggers when an order status changes
• Configurable polling interval: Set how often to check for new orders
• Status filtering: Filter orders by specific status
• Limit control: Control the number of orders fetched per poll

Zid Customer Trigger

• New Customer: Triggers when a new customer is registered
• Configurable polling interval: Set how often to check for new customers
• Limit control: Control the number of customers fetched per poll

Action Nodes

Zid Node (Main Action Node)

Order Operations:

• Get All Orders: Retrieve a list of orders with optional filtering
• Get Order: Fetch details of a specific order by ID
• Update Order: Update order information

Product Operations:

• Get All Products: Retrieve a list of products
• Get Product: Fetch details of a specific product by ID
• Create Product: Create a new product
• Update Product: Update existing product information

Customer Operations:

• Get All Customers: Retrieve a list of customers
• Get Customer: Fetch details of a specific customer by ID
• Create Customer: Create a new customer
• Update Customer: Update existing customer information

Usage Examples

Example 1: New Order Notification

{
  "nodes": [
    {
      "name": "Zid Order Trigger",
      "type": "n8n-nodes-zid.zidOrderTrigger",
      "parameters": {
        "triggerOn": "newOrder",
        "pollInterval": 5,
        "limit": 10
      }
    },
    {
      "name": "Send Email",
      "type": "n8n-nodes-base.emailSend",
      "parameters": {
        "subject": "New Order Received: {{$json.id}}",
        "text": "Order details: {{$json}}"
      }
    }
  ]
}

Example 2: Sync Products

{
  "nodes": [
    {
      "name": "Get Zid Products",
      "type": "n8n-nodes-zid.zid",
      "parameters": {
        "resource": "product",
        "operation": "getAll",
        "limit": 50
      }
    },
    {
      "name": "Process Products",
      "type": "n8n-nodes-base.function",
      "parameters": {
        "functionCode": "// Process and transform product data\nreturn items.map(item => ({\n  json: {\n    id: item.json.id,\n    name: item.json.name,\n    price: item.json.price\n  }\n}));"
      }
    }
  ]
}

Example 3: Create Customer

{
  "nodes": [
    {
      "name": "Create Zid Customer",
      "type": "n8n-nodes-zid.zid",
      "parameters": {
        "resource": "customer",
        "operation": "create",
        "additionalFields": {
          "name": "John Doe",
          "email": "[email protected]",
          "phone": "+1234567890"
        }
      }
    }
  ]
}

Configuration Options

Trigger Nodes

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | triggerOn | Options | newOrder | What event to trigger on | | pollInterval | Number | 5 | Polling interval in minutes (1-60) | | statusFilter | String | "" | Filter by order status (optional) | | limit | Number | 50 | Max items per poll (1-100) |

Action Nodes

| Parameter | Type | Description | |-----------|------|-------------| | resource | Options | Resource type (order, product, customer) | | operation | Options | Operation to perform (getAll, get, create, update) | | id | String | Resource ID (for get/update operations) | | limit | Number | Max results for getAll operations | | additionalFields | Collection | Additional fields for create/update |

Error Handling

The nodes include comprehensive error handling:

• Authentication Errors: Clear messages for OAuth2 issues
• API Errors: Detailed error responses from Zid API
• Network Errors: Timeout and connection error handling
• Validation Errors: Parameter validation with helpful messages

Rate Limiting

The package respects Zid API rate limits:

• Automatic retry logic for rate-limited requests
• Exponential backoff strategy
• Configurable request delays

Development

Building from Source

git clone <repository-url>
cd n8n-nodes-zid
npm install
npm run build

Running Tests

npm test

Linting

npm run lint

API Reference

The nodes interact with the following Zid API endpoints:

• GET /orders - List orders
• GET /orders/{id} - Get order details
• PUT /orders/{id} - Update order
• GET /products - List products
• GET /products/{id} - Get product details
• POST /products - Create product
• PUT /products/{id} - Update product
• GET /customers - List customers
• GET /customers/{id} - Get customer details
• POST /customers - Create customer
• PUT /customers/{id} - Update customer

Troubleshooting

Common Issues

Authentication Failed

• Verify your OAuth2 credentials are correct
• Check that your Zid application is properly configured
• Ensure the redirect URI matches your n8n instance

API Rate Limiting

• Reduce polling frequency for trigger nodes
• Implement delays between API calls in workflows
• Monitor your API usage in the Zid dashboard

Connection Timeouts

• Check your network connectivity
• Verify Zid API status
• Increase timeout values if needed

Debug Mode

Enable debug logging by setting the environment variable:

export DEBUG=n8n-nodes-zid:*

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Zid API Documentation
• n8n Community Forum
• GitHub Issues

Changelog

v0.1.0

• Initial release
• OAuth2 authentication support
• Order, Product, and Customer operations
• Trigger nodes for new orders and customers
• Comprehensive error handling and testing