n8n-nodes-salla/INSTALLATION.md

n8n node for Salla.sa e-commerce platform integration with OAuth2.0

# Installation Guide - n8n-nodes-salla

This guide will walk you through the complete setup process for the Salla n8n integration node.

## Prerequisites

Before you begin, ensure you have:

1. **n8n instance** running (version 1.0.0 or higher)
2. **Salla Partner Account** - Sign up at [Salla Partners](https://salla.partners/)
3. **Node.js** (version 18 or higher) for development
4. **npm** package manager

## Step 1: Get Salla API Credentials

### 1.1 Create a Salla Application

1. Go to [Salla Partner Dashboard](https://salla.partners/)
2. Log in to your partner account
3. Navigate to **"My Applications"**
4. Click **"Create New Application"**
5. Fill in the application details:
   - **App Name**: Your application name (e.g., "My n8n Integration")
   - **App Description**: Brief description of your integration
   - **App Category**: Choose appropriate category
   - **Redirect URI**: `https://your-n8n-instance.com/rest/oauth2-credential/callback`

### 1.2 Configure OAuth Settings

1. In your application settings, configure:
   - **Scopes**: Select the permissions your integration needs:
     - `orders:read`, `orders:write` - For order operations
     - `products:read`, `products:write` - For product operations
     - `customers:read`, `customers:write` - For customer operations
     - `coupons:read`, `coupons:write` - For coupon operations
     - And other scopes as needed
   
2. **Webhook Configuration** (optional but recommended):
   - **Webhook URL**: `https://your-n8n-instance.com/webhook/salla`
   - **Events**: Select events you want to receive
   - **Secret**: Generate a strong secret for webhook validation

### 1.3 Note Your Credentials

From your Salla application, note down:
- **Client ID**
- **Client Secret**
- **Webhook Secret** (if configured)

## Step 2: Install the n8n Node

### Option A: Install from npm (Recommended)

1. In your n8n instance, go to **Settings > Community Nodes**
2. Click **"Install"**
3. Enter package name: `n8n-nodes-salla`
4. Click **"Install"**

### Option B: Manual Installation (Development)

1. Clone this repository:
   ```bash
   git clone https://github.com/aolamer/n8n-nodes-salla.git
   cd n8n-nodes-salla
   ```

2. Run the setup script:
   ```bash
   npm run setup
   ```

3. Copy the built files to your n8n installation:
   ```bash
   cp -r dist/* /path/to/your/n8n/custom-nodes/
   ```

## Step 3: Configure Credentials in n8n

### 3.1 Create OAuth2 Credentials

1. In n8n, go to **Credentials**
2. Click **"Create New Credential"**
3. Search for **"Salla OAuth2 API"**
4. Fill in the credential fields:

#### Required Configuration
- **Environment**: `production` or `sandbox`
- **Client ID**: Your Salla application Client ID
- **Client Secret**: Your Salla application Client Secret

#### OAuth Settings
- **OAuth Scopes**: `offline_access` (default) or custom scopes like `offline_access read write orders products customers`

#### API Configuration  
- **API Version**: `v2` (recommended) or `v1`
- **Rate Limit Handling**: `retry` (recommended) or `fail`
- **Max Retries**: `3` (default) or your preferred number (1-10)

#### Token Management (Advanced)
- **Auto Refresh Tokens**: `true` (recommended) - Automatically refresh tokens before expiry
- **Token Refresh Buffer**: `30` minutes (default) - Refresh tokens X minutes before expiry

#### Optional Settings
- **Webhook Secret**: Your webhook secret for signature validation (optional)
- **Store Domain**: Your store domain - will be auto-detected (optional)

### 3.2 Complete OAuth Flow

1. Click **"Connect my account"** in the credential configuration
2. You'll be redirected to Salla's authorization page
3. Log in with your Salla merchant account (not your partner account)
4. Grant the requested permissions to your application
5. You'll be redirected back to n8n
6. **OAuth tokens are automatically saved** - no manual configuration needed!
7. The credential will show as "Connected" with a green checkmark

### 3.3 Verify Token Management

The enhanced credentials now include automatic token management:

- ✅ **Access tokens** are saved automatically after OAuth completion
- ✅ **Refresh tokens** are stored securely for automatic renewal
- ✅ **Token expiry** is tracked (considering Salla's 14-day limit)
- ✅ **Auto-refresh** occurs before expiry (configurable buffer time)
- ✅ **Error recovery** handles expired tokens automatically

## Step 4: Test the Integration

### 4.1 Create a Test Workflow

1. Create a new workflow in n8n
2. Add a **"Salla"** node
3. Select your configured credentials
4. Choose a simple operation like:
   - **Resource**: `Order`
   - **Operation**: `Get All`
5. Execute the node to test the connection

### 4.2 Verify Connection

If successful, you should see:
- ✅ Green checkmark on the node
- Data returned from Salla API
- No authentication errors

## Step 5: Set Up Webhooks (Optional)

### 5.1 Configure Webhook Trigger

1. Add a **"Salla Trigger"** node to your workflow
2. Configure the events you want to listen to
3. Set **"Validate Webhook"** to `true`
4. Enter your webhook secret
5. Save the workflow and activate it

### 5.2 Register Webhook with Salla

1. Copy the webhook URL from your trigger node
2. In your Salla application settings, add this URL as a webhook endpoint
3. Select the events you want to receive
4. Test the webhook by triggering an event in your Salla store

## Common Resources and Operations

### Orders
- **Get**: Retrieve specific order by ID
- **Get All**: List all orders with filtering
- **Update**: Modify order details
- **Cancel**: Cancel an order

### Products
- **Create**: Add new products
- **Get**: Retrieve product details
- **Get All**: List all products
- **Update**: Modify product information
- **Delete**: Remove products

### Customers
- **Get**: Retrieve customer information
- **Get All**: List all customers
- **Update**: Modify customer details
- **Delete**: Remove customers

### Digital Products, Coupons, Shipments, etc.
- Similar CRUD operations available for all resources

## Troubleshooting

### Common Issues

1. **Authentication Errors**
   - Verify Client ID and Client Secret
   - Check if OAuth flow was completed
   - Ensure scopes are correctly configured

2. **Rate Limiting**
   - The node automatically handles rate limits
   - Increase retry settings if needed
   - Consider implementing delays between requests

3. **Webhook Issues**
   - Verify webhook URL is accessible
   - Check webhook secret configuration
   - Ensure events are properly selected in Salla

4. **Token Expiry**
   - Tokens are automatically refreshed
   - Check if refresh token is valid
   - Re-authenticate if needed

### Support

- **Salla API Documentation**: [https://docs.salla.dev/](https://docs.salla.dev/)
- **n8n Documentation**: [https://docs.n8n.io/](https://docs.n8n.io/)
- **Issues**: Create an issue on the GitHub repository

## Security Best Practices

1. **Credentials Storage**
   - All sensitive data is securely stored in n8n's encrypted credential system
   - Never commit credentials to version control
   - Use n8n's credential management for all API keys and secrets
   - Regularly rotate API keys in both Salla and n8n

2. **Webhook Security**
   - Always validate webhook signatures
   - Use HTTPS for webhook endpoints
   - Implement proper error handling

3. **API Usage**
   - Respect rate limits
   - Implement proper error handling
   - Log important events for debugging

## Next Steps

1. Explore the example workflows in the `examples/` folder
2. Build your integration workflows
3. Test thoroughly in sandbox environment
4. Deploy to production

Congratulations! Your Salla n8n integration is now ready to use. 🎉