n8n-nodes-zid

Custom n8n nodes for integrating with the Zid API. This package provides trigger and action nodes to automate workflows with Zid's e-commerce platform.

Features

• OAuth2 Authentication: Secure authentication using Zid's OAuth2 flow with dual-token support
• Trigger Nodes: Automatically trigger workflows on new orders, order updates, and new customers
• Action Nodes: Perform operations on orders, products, and customers
• Error Handling: Comprehensive error handling with specific Zid API error responses
• Pagination Support: Automatic handling of paginated API responses
• Rate Limiting: Built-in respect for Zid API rate limits

Installation

Method 1: Global npm Installation (Recommended)

npm install -g [email protected]

Method 2: Docker Installation

# Pull the n8n image
docker pull n8nio/n8n

# Install the package in a running container
docker exec -it <container_name> npm install -g [email protected]

# Or build a custom image
FROM n8nio/n8n
RUN npm install -g [email protected]

Method 3: Development Installation

# Clone and build
git clone <repository>
cd n8n-nodes-zid
npm install
npm run build
npm pack

# Install the package
npm install -g n8n-nodes-zid-beta-0.1.1.tgz

OAuth2 Setup

This package implements Zid's OAuth2 authorization flow with dual-token authentication. See OAUTH2_IMPLEMENTATION.md for detailed implementation information.

Quick Setup

1. Create Zid App: Register your application in the Zid Partner Dashboard
2. Get Credentials: Note your Client ID and Client Secret
3. Configure URLs: Set up the required URLs in your Zid app
4. Configure n8n:
   • Go to Settings → Credentials
   • Add new "Zid OAuth2 API" credential
   • Enter your Client ID and Client Secret
   • Complete the OAuth2 flow

Partner Dashboard URL Configuration

When creating your Zid app, configure these URLs:

1. Application URL: Your n8n instance base URL

   • Example: https://your-n8n.com

2. Redirect URL: n8n OAuth2 redirect endpoint

   • Example: https://your-n8n.com/rest/oauth2-credential/callback

3. Callback URL: Same as redirect URL

   • Example: https://your-n8n.com/rest/oauth2-credential/callback

Note: The exact callback URL format may vary depending on your n8n installation. Check your n8n instance's OAuth2 callback URL pattern.

Required Tokens

Zid requires two tokens for API access:

• Authorization Token: Bearer token for API access
• X-Manager-Token: Store-specific access token

Both tokens are automatically handled by the OAuth2 credential.

Scope Configuration

Configure required scopes in your Zid Partner Dashboard:

• read:orders - Read order data
• write:orders - Update order information
• read:products - Read product data
• write:products - Create/update products
• read:customers - Read customer data
• write:customers - Create/update customers

Available Nodes

Trigger Nodes

Zid Order Trigger

• Triggers on new orders or order status updates
• Configurable polling interval (1-60 minutes)
• Status filtering support
• Flood prevention on first run

Zid Customer Trigger

• Triggers on new customer registrations
• Configurable polling interval (1-60 minutes)
• Automatic duplicate prevention

Action Nodes

Zid (Main Action Node)

Supports three resources with multiple operations:

Orders

• Get All Orders
• Get Order by ID
• Update Order

Products

• Get All Products
• Get Product by ID
• Create Product
• Update Product

Customers

• Get All Customers
• Get Customer by ID
• Create Customer
• Update Customer

API Reference

Authentication Headers

All API requests include:

Authorization: Bearer <authorization_token>
X-Manager-Token: <access_token>
Content-Type: application/json
Accept: application/json

Base URL

https://api.zid.sa/v1

Error Handling

The package handles specific Zid API errors:

• 401: Authentication errors
• 403: Authorization/permission errors
• 429: Rate limit exceeded
• Network errors: Connection issues

Usage Examples

Example 1: New Order Email Notification

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

Example 2: Product Sync

{
  "nodes": [
    {
      "name": "Get Products",
      "type": "n8n-nodes-zid.zid",
      "parameters": {
        "resource": "product",
        "operation": "getAll",
        "limit": 50
      }
    }
  ]
}

Development

Building

npm install
npm run build

Testing

npm test

Linting

npm run lint
npm run lint:fix

Troubleshooting

Installation Issues

1. "Package does not contain any nodes"

   • Ensure you're using version 0.1.1 or later
   • Restart n8n after installation

2. OAuth2 Authentication Fails

   • Verify Client ID and Client Secret
   • Check redirect URLs in Partner Dashboard
   • Ensure both tokens are present

3. API Errors

   • Check token expiration (tokens last 1 year)
   • Verify required scopes are granted
   • Check API rate limits

Debug Steps

1. Check n8n logs for detailed error messages
2. Verify credentials in n8n Settings → Credentials
3. Test API access with curl using the same tokens
4. Check Zid Partner Dashboard for app status

Version History

• 0.1.1: Updated OAuth2 implementation with dual-token support
• 0.1.0: Initial release with basic OAuth2 support

Contributing

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

License

MIT License - see LICENSE file for details.

Support

• Zid API Documentation
• Zid Partner Dashboard
• n8n Community

Related Documentation

• OAuth2 Implementation Details
• Installation Guide
• Example Workflows