n8n-nodes-nqdev-aio/README.md

Custom n8n node package for seamless integration of Vietnamese SaaS services: eSMSvn, Haravan, and Zalo

# n8n-nodes-nqdev-aio

🚀 **Custom n8n node package for seamless integration of Vietnamese SaaS services**

[![npm version](https://badge.fury.io/js/n8n-nodes-nqdev-aio.svg)](https://badge.fury.io/js/n8n-nodes-nqdev-aio)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Publish: Package to npmJs](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/publish_npm.yml/badge.svg)](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/publish_npm.yml)

[![Release: Create GitHub Release](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/create-release.yml/badge.svg)](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/create-release.yml)
[![Update Changelog](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/changelog.yml/badge.svg)](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/actions/workflows/changelog.yml)

## 🎯 What's Included

This package provides custom n8n nodes for integrating with popular Vietnamese SaaS services:

- **eSMS.vn** - SMS marketing automation platform
- **Haravan** - E-commerce platform integration
- **Zalo** - Social network messaging service

## 📦 Installation

### Option 1: NPM Installation (Recommended)

```bash
npm install n8n-nodes-nqdev-aio
```

### Option 2: Manual Installation

1. Download the latest release
2. Place in your n8n custom nodes directory
3. Restart n8n

### Option 3: Docker Installation

Add to your n8n Docker setup:

```dockerfile
RUN npm install n8n-nodes-nqdev-aio
```

## 🔧 Configuration

After installation, you'll need to set up credentials for each service:

### eSMS.vn Configuration

1. Go to n8n Settings > Credentials
2. Add new credential > eSMS.vn API
3. Enter your API Key and Secret Key from eSMS.vn dashboard
4. Test connection

### Haravan Configuration

1. Go to n8n Settings > Credentials
2. Add new credential > Haravan API
3. Enter your shop name, access token, and API version
4. Test connection

### Zalo Configuration

1. Go to n8n Settings > Credentials
2. Add new credential > Zalo API
3. Enter your access token, app ID, and app secret
4. Test connection

## 🚀 Features

### eSMS.vn Node

- ✅ Send individual SMS messages
- ✅ Send bulk SMS campaigns
- ✅ Check account balance
- ✅ Track message delivery status
- ✅ Support for Brandname & CSKH SMS types
- ✅ Multi-recipient support

### Haravan Node

- ✅ Product management (CRUD operations)
- ✅ Order management and tracking
- ✅ Customer management
- ✅ Inventory operations
- ✅ Full REST API integration

### Zalo Node

- ✅ Send text messages
- ✅ Send image messages
- ✅ Template message support
- ✅ User profile management
- ✅ Follower management
- ✅ Image upload capabilities

## 📖 Usage Examples

### SMS Marketing Campaign with eSMS.vn

```json
{
  "resource": "sms",
  "operation": "sendBulk",
  "phones": "+84912345678,+84987654321",
  "message": "🎉 Sale cuối năm - Giảm giá 50% tất cả sản phẩm! Mua ngay: shop.com",
  "smsType": "1",
  "brandname": "MYSHOP"
}
```

### E-commerce Product Sync with Haravan

```json
{
  "resource": "product",
  "operation": "create",
  "title": "Áo thun nam basic",
  "body_html": "<p>Áo thun chất liệu cotton cao cấp</p>",
  "product_type": "Thời trang",
  "vendor": "Fashion Brand"
}
```

### Social Messaging with Zalo

```json
{
  "resource": "message",
  "operation": "sendText",
  "user_id": "user123456789",
  "text": "Xin chào! Cảm ơn bạn đã quan tâm đến sản phẩm của chúng tôi."
}
```

## 🔄 Workflow Examples

### 1. SMS Marketing Campaign

```
Webhook Trigger → eSMS.vn (Send Bulk) → Google Sheets (Log Results)
```

### 2. E-commerce Integration

```
Haravan (Get Orders) → Filter New Orders → Email Notification → Zalo Message
```

### 3. Customer Service Automation

```
Zalo (Get Messages) → Process Text → eSMS.vn (Send Response) → CRM Update
```

## 🛠️ Development

### Prerequisites

- Node.js 18+
- n8n installed
- TypeScript knowledge

### Setup

```bash
# Clone repository
git clone https://github.com/nqdev-group/n8n-nodes-nqdev-aio.git
cd n8n-nodes-nqdev-aio

# Install dependencies
npm install

# Build the project
npm run build

# Development mode
npm run dev
```

### Project Structure

```
n8n-nodes-nqdev-aio/
├── credentials/              # API credential configurations
│   ├── EsmsVnApi.credentials.ts
│   ├── HaravanApi.credentials.ts
│   └── ZaloApi.credentials.ts
├── nodes/                    # Node implementations
│   ├── EsmsVn/              # SMS marketing node
│   ├── Haravan/             # E-commerce node
│   └── Zalo/                # Social messaging node
├── assets/                   # Icons and assets
├── examples/                 # Workflow examples
├── dist/                     # Built output
└── Documentation files
```

## 🧪 Testing

### Manual Testing

1. Start n8n in development mode
2. Import example workflows from `/examples` folder
3. Configure credentials with test accounts
4. Execute workflows to verify functionality

### API Testing

Each service provides test endpoints:

- **eSMS.vn**: Balance check endpoint
- **Haravan**: Shop info endpoint
- **Zalo**: Profile endpoint

## 📚 API Documentation

### eSMS.vn

- [API Documentation](https://esms.vn/docs)
- [Developer Portal](https://esms.vn/developers)

### Haravan

- [API Documentation](https://docs.haravan.com)
- [Developer Guide](https://developers.haravan.com)

### Zalo

- [API Documentation](https://developers.zalo.me/docs)
- [Official Account API](https://developers.zalo.me/docs/official-account)

## 🔒 Security & Privacy

- All credentials are encrypted by n8n
- API keys are never logged or exposed
- HTTPS required for all API communications
- Regular security updates and vulnerability patches

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines:

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

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

### Community Support

- [GitHub Issues](https://github.com/nqdev-group/n8n-nodes-nqdev-aio/issues)
- [n8n Community Forum](https://community.n8n.io)

### Professional Support

For enterprise support and custom integrations:

- Email: contact@nqdev.com
- Website: [nqdev.com](https://nqdev.com)

## 🔄 Changelog

### v1.0.0

- ✅ Initial release
- ✅ eSMS.vn node implementation
- ✅ Haravan node implementation
- ✅ Zalo node implementation
- ✅ Full TypeScript support
- ✅ Comprehensive documentation

## 🚀 Roadmap

- [ ] Advanced template management for Zalo
- [ ] Webhook support for real-time updates
- [ ] Advanced analytics and reporting
- [ ] Additional Vietnamese SaaS integrations
- [ ] Multi-language support

---

**Made with ❤️ by nqdev-group for the Vietnamese developer community**