n8n-nodes-orderful/README.md

N8N nodes for Orderful EDI platform integration

# N8N Orderful Nodes

Custom N8N community nodes for integrating with the **Orderful EDI platform**. These nodes allow you to manage Electronic Data Interchange (EDI) transactions, trading partner relationships, and data conversions directly within your N8N workflows.

## 🚀 Features

- **Full Orderful API Integration** - Connect to Orderful's modern EDI platform
- **Multiple Node Types** - Specialized nodes for different Orderful operations
- **EDI Transaction Management** - Create, list, retrieve, and manage EDI transactions
- **Trading Partner Operations** - Manage relationships and organization details
- **Data Format Conversion** - Convert between X12, JSON, and EDIFACT formats
- **Transaction Polling** - Monitor and retrieve new transactions automatically
- **Comprehensive Error Handling** - Robust error handling with detailed feedback

## 📦 What's Included

### 1. **Orderful** Node
- **List Relationships** - Get all trading partner relationships
- **Get Organization** - Retrieve your organization details
- **Convert Data** - Convert between EDI formats (X12 ↔ JSON ↔ EDIFACT)

### 2. **Orderful Transaction** Node
- **Create Transaction** - Submit new EDI transactions (850, 855, 856, 810, 204, 990, 214)
- **List Transactions** - Query transactions with filters (status, type, date range)
- **Get Transaction** - Retrieve specific transaction details
- **Get Message** - Get transaction message content
- **Confirm Delivery** - Mark transactions as delivered
- **Create Acknowledgment** - Generate transaction acknowledgments

### 3. **Orderful Poller** Node
- **Get Transactions** - Poll for new transactions from buckets
- **Remove Transactions** - Clean up processed transactions from buckets

## 🔧 Installation

### Prerequisites
- N8N instance (self-hosted or cloud)
- Orderful account with API access
- Node.js 20.15+ for development

### Install in N8N

1. **Build the nodes:**
   ```bash
   npm install
   npm run build
   ```

2. **Link to N8N:**
   ```bash
   # Link the package globally
   npm link
   
   # In your n8n installation directory
   npm link n8n-nodes-orderful
   ```

3. **Restart N8N** to load the new nodes

## 🔑 Authentication Setup

1. **Get your Orderful API Key:**
   - Log into your Orderful organization
   - Navigate to API settings
   - Generate or copy your API key

2. **Create Credentials in N8N:**
   - Go to Credentials in N8N
   - Add new credential: "Orderful API"
   - Enter your API key
   - Choose environment (Sandbox/Production)
   - Set base URL (default: `https://api.orderful.com`)

## 📋 Common Use Cases

### 1. **Automated Purchase Order Processing**
```
Trigger → Orderful Transaction (Create 850) → Orderful Transaction (Confirm Delivery)
```

### 2. **EDI Data Monitoring**
```
Schedule → Orderful Poller (Get Transactions) → Process Data → Notify
```

### 3. **Format Conversion Workflow**
```
Webhook → Orderful (Convert X12 to JSON) → Database → Response
```

### 4. **Trading Partner Onboarding**
```
Manual Trigger → Orderful (List Relationships) → Filter New Partners → Notify Team
```

## 🛠 Development

### Project Structure
```
├── credentials/
│   └── OrderfulApi.credentials.ts     # API authentication
├── nodes/
│   ├── Orderful/                      # Main operations node
│   ├── OrderfulTransaction/           # Transaction management
│   └── OrderfulPoller/               # Transaction polling
└── dist/                             # Compiled output
```

### Available Scripts
- `npm run build` - Build the nodes
- `npm run dev` - Watch mode for development
- `npm run lint` - Check code quality
- `npm run format` - Format code with Prettier

### Supported EDI Transaction Types

**Order Management:**
- 850 - Purchase Order
- 855 - Purchase Order Acknowledgment
- 856 - Ship Notice/Manifest
- 810 - Invoice

**Transportation:**
- 204 - Motor Carrier Load Tender
- 990 - Response to Load Tender
- 214 - Transportation Carrier Shipment Status

## 📚 API Reference

### Node Properties

#### Orderful Transaction Node
- **Transaction Type**: Select EDI transaction type (850, 855, 856, etc.)
- **Transaction Data**: JSON payload for the transaction
- **Partner ID**: Trading partner identifier
- **Filters**: Status, type, date range for listing operations

#### Orderful Poller Node
- **Bucket Name**: Name of the poller bucket
- **Filters**: Limit, transaction type, partner ID
- **Transaction IDs**: For removal operations

#### Orderful Node
- **Resource**: Choose between Relationship, Organization, or Conversion
- **Operation**: Specific action for the selected resource
- **Format Options**: From/To formats for conversions

## 🔍 Troubleshooting

### Common Issues

1. **Authentication Errors**
   - Verify API key is correct
   - Check environment setting (sandbox vs production)
   - Ensure base URL is correct

2. **Transaction Creation Fails**
   - Validate JSON format in transaction data
   - Check partner ID exists in your organization
   - Verify transaction type is supported

3. **Build Errors**
   - Ensure Node.js version 20.15+
   - Run `npm install` to update dependencies
   - Check TypeScript configuration

### Error Messages
- `Invalid JSON in transaction data` - Check transaction data format
- `Authentication failed` - Verify API credentials
- `Partner not found` - Check partner ID in your Orderful organization

## 🤝 Support

For issues and questions:
- **Orderful API Documentation**: https://docs.orderful.com
- **N8N Community**: https://community.n8n.io
- **EDI Resources**: https://docs.orderful.com/docs/edi-101

## 📄 License

MIT License - see LICENSE.md for details

## 🔄 Version History

- **v0.1.0** - Initial release with core Orderful functionality
  - Basic transaction management
  - Relationship and organization operations
  - Data format conversion
  - Transaction polling

---

**Built for the N8N Community** 🚀  
Transform your EDI workflows with modern automation!