n8n-nodes-myobv2/README.md

Comprehensive n8n node for MYOB Business API - Sales Orders, Customers, Items, Invoices, and more

# n8n-nodes-myobv2

[![npm version](https://badge.fury.io/js/n8n-nodes-myobv2.svg)](https://badge.fury.io/js/n8n-nodes-myobv2)

Comprehensive n8n community node for MYOB Business API integration. This node provides full CRUD operations for Sales Orders, Customers, Items, and Invoices.

## Features

### Supported Resources & Operations

#### 📦 Sales Orders
- **Create**: Create sales orders with multiple line items (supports Shopify integration)
- **Get**: Retrieve sales order by UID
- **List**: List all sales orders with filtering

#### 👥 Customers
- **Create**: Create new customers
- **Get**: Retrieve customer by UID  
- **List**: List all customers with filtering

#### 📋 Items/Inventory
- **Create**: Create new inventory items
- **Get**: Retrieve items by UID or SKU
- **List**: List all inventory items with filtering

#### 🧾 Invoices
- **Get**: Retrieve invoice by UID
- **List**: List all invoices with filtering
- **Create from Sales Order**: Convert existing sales orders to invoices

### Key Capabilities

✅ **Multi-Resource Operations** - One node handles all MYOB entities  
✅ **Shopify Integration** - Direct support for Shopify webhook data  
✅ **SKU Auto-Lookup** - Automatic conversion of SKUs to MYOB UIDs  
✅ **Flexible Line Items** - UI forms or dynamic JSON arrays  
✅ **Advanced Filtering** - OData query support for list operations  
✅ **Error Handling** - Graceful fallbacks and detailed error messages  
✅ **OAuth2 Authentication** - Secure cloud-based authentication  

## Installation

### From n8n Community Nodes

1. Go to **Settings** → **Community Nodes**
2. Enter `n8n-nodes-myobv2`
3. Click **Install**

### Manual Installation

```bash
npm install n8n-nodes-myobv2
```

## Setup

### 1. MYOB Developer Account

1. Register at [MYOB Developers](https://developer.myob.com/)
2. Create a new app to get your API Key and Secret
3. Set redirect URI to: `http://localhost:5678/rest/oauth2-credential/callback`

### 2. n8n Credentials

1. Create new **MYOB OAuth2 API** credentials in n8n
2. Enter your **Client ID** (API Key) and **Client Secret** (API Secret)
3. Add your **Company File GUID** (found in MYOB cloud URL)
4. Click **Connect my account** and authorize

## Usage Examples

### Sales Order Operations

#### Create Sales Order from Shopify
```javascript
// Configure node:
Resource: Sales Order
Operation: Create
Input Method: JSON Array
Line Items Data: {{ $json.line_items }}
Customer UID: "12345678-1234-1234-1234-123456789012"
Default SKU: "DEFAULT-ITEM"
```

#### Get Sales Order
```javascript
Resource: Sales Order
Operation: Get
Sales Order UID: "87654321-4321-4321-4321-210987654321"
```

#### List Recent Sales Orders
```javascript
Resource: Sales Order
Operation: List
Filter: Date gt datetime'2024-01-01T00:00:00'
Limit: 50
```

### Customer Operations

#### Create Customer
```javascript
Resource: Customer
Operation: Create
Customer Name: "Acme Corp"
Email: "orders@acme.com"
Phone: "+1-555-0123"
```

#### Find Customer by Name
```javascript
Resource: Customer
Operation: List
Filter: CompanyName eq 'Acme Corp'
```

### Item Operations

#### Get Item by SKU
```javascript
Resource: Item
Operation: Get
Item SKU: "WIDGET-001"
```

#### Create New Item
```javascript
Resource: Item
Operation: Create
Item Name: "Premium Widget"
Item SKU/Number: "WIDGET-PREMIUM"
Base Selling Price: 99.95
```

#### List Active Items
```javascript
Resource: Item
Operation: List
Filter: IsActive eq true and IsSold eq true
Limit: 100
```

### Invoice Operations

#### Create Invoice from Sales Order
```javascript
Resource: Invoice
Operation: Create from Sales Order
Sales Order UID: "12345678-1234-1234-1234-123456789012"
```

#### List Recent Invoices
```javascript
Resource: Invoice
Operation: List
Filter: Date gt datetime'2024-01-01T00:00:00'
```

## Advanced Features

### Dynamic Line Items (Shopify Integration)

The node automatically handles Shopify webhook data:

```json
{
  "line_items": [
    {
      "sku": "WIDGET-001",
      "quantity": 2,
      "price": "29.95",
      "title": "Premium Widget",
      "variant_title": "Blue",
      "discount_allocations": [
        {"amount": "5.99"}
      ]
    }
  ]
}
```

Features:
- Automatic SKU lookup and UID resolution
- Discount calculation from Shopify data
- Fallback to default SKU for missing items
- Product title and variant consolidation

### OData Filtering

Use OData query syntax for powerful filtering:

```javascript
// Date ranges
Date gt datetime'2024-01-01T00:00:00'

// Text matching
CompanyName eq 'Acme Corp'

// Boolean filters  
IsActive eq true and IsSold eq true

// Numeric comparisons
BaseSellingPrice gt 50.00

// Multiple conditions
IsActive eq true and Date gt datetime'2024-01-01T00:00:00'
```

### Error Handling

The node provides detailed error messages and graceful fallbacks:

- SKU not found → Falls back to default SKU
- Network errors → Detailed error context
- Validation errors → Clear field-specific messages
- API rate limits → Automatic retry suggestions

## Field Reference

### Sales Order Create Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Customer UID | String | Yes | MYOB customer GUID |
| Tax Inclusive | Boolean | No | Whether prices include tax |
| Purchase Order Number | String | No | Reference number |
| Journal Memo | String | No | Internal memo |
| Comment | String | No | Order comment |
| Shipping Address Lines 1-5 | String | No | Multi-line shipping address |
| Shipping SKU | String | No | Shipping item SKU |
| Shipping Price | Number | No | Shipping cost |
| Input Method | Options | Yes | UI Form or JSON Array |
| Line Items Data | JSON | Conditional | Raw line items (JSON method) |
| Default SKU | String | Conditional | Fallback SKU (JSON method) |

### Customer Create Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Customer Name | String | Yes | Company/person name |
| Customer Number | String | No | Custom customer code |
| Email | String | No | Contact email |
| Phone | String | No | Contact phone |

### Item Create Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Item Name | String | Yes | Product name |
| Item SKU/Number | String | Yes | Unique identifier |
| Item Description | String | No | Product description |
| Base Selling Price | Number | No | Default price |

### List Operation Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| Limit | Number | No | Max records (default: 100) |
| Filter | String | No | OData filter expression |

## Common Workflows

### E-commerce → MYOB Integration

1. **Shopify Webhook** → **MYOB Sales Order Create**
2. **Order Processing** → **MYOB Invoice Create from Sales Order**
3. **Customer Sync** → **MYOB Customer Create/Update**

### Inventory Management

1. **CSV Import** → **MYOB Item Create** 
2. **Stock Updates** → **MYOB Item Get/Update**
3. **Price Changes** → **MYOB Item List & Update**

### Reporting & Analytics

1. **MYOB Sales Order List** → **Data Processing** → **Dashboard**
2. **MYOB Customer List** → **CRM Sync**
3. **MYOB Invoice List** → **Accounting Reports**

## Troubleshooting

### Authentication Issues

**Problem**: `invalid_client` error  
**Solution**: Verify Client ID and Client Secret match your MYOB app exactly

**Problem**: OAuth callback error  
**Solution**: Ensure redirect URI is `http://localhost:5678/rest/oauth2-credential/callback`

### SKU Lookup Failures

**Problem**: "SKU not found" errors  
**Solution**: Set a valid Default SKU for fallback

**Problem**: Items created with wrong details  
**Solution**: Verify SKU format matches MYOB exactly (case-sensitive)

### API Rate Limits

**Problem**: 429 Too Many Requests  
**Solution**: Add delays between requests or batch operations

### Data Validation Errors

**Problem**: "Required field missing"  
**Solution**: Check MYOB field requirements for your specific operation

## API Coverage

### MYOB Endpoints Used

- `/Sale/Order/Item` - Sales orders
- `/Contact/Customer` - Customers  
- `/Inventory/Item` - Items/inventory
- `/Sale/Invoice/Item` - Invoices

### Supported MYOB Features

✅ Item sales orders  
✅ Customer management  
✅ Inventory items  
✅ Invoice creation  
✅ OData filtering  
✅ Pagination  
✅ Error handling  

### Roadmap

🔄 Purchase orders  
🔄 Payments  
🔄 Tax codes  
🔄 Accounts  
🔄 Reports  
🔄 Time billing  

## Version History

### 1.0.0
- Initial release with multi-resource support
- Sales Orders, Customers, Items, Invoices
- Shopify integration
- OData filtering
- Comprehensive error handling

## Support

- **GitHub**: [Issues & Feature Requests](https://github.com/dannyboi0077/n8n-nodes-myobv2/issues)
- **n8n Community**: [Community Forum](https://community.n8n.io/)
- **Documentation**: [MYOB API Docs](https://developer.myob.com/api/accountright/v2/)

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests.