n8n-nodes-tiny-erp-api-v2/README.md

Custom nodes for Tiny ERP integration with n8n, including AI tools for AI Agent workflows

# n8n-nodes-tiny-erp-api-v2

A comprehensive package of custom nodes for n8n that enables integration with Tiny ERP API, including specialized AI tools for AI Agent workflows.

## 🚀 Features

- **Modular Node Structure**: Clean, maintainable code following n8n best practices
- **AI Agent Ready**: Specialized AI tools with `$fromAI()` support
- **Complete ERP Integration**: Products, Orders, and Users operations
- **TypeScript Support**: Full type safety and IntelliSense
- **Error Handling**: Comprehensive error handling with helpful messages

## 📦 Installation

### Via n8n Community Packages
1. Go to **Settings > Community Packages**
2. Enter `n8n-nodes-tiny-erp-api-v2`
3. Click **Install**

### Via npm
```bash
npm install n8n-nodes-tiny-erp-api-v2
```

## 🔧 Configuration

### Credentials Setup
1. Go to **Credentials** in n8n
2. Click **+ Add Credential**
3. Search for "Tiny ERP API"
4. Enter your Tiny ERP API token

### Getting Your API Token
1. Access your [Tiny ERP](https://tiny.com.br) account
2. Go to **Settings > API**
3. Generate a new API token
4. Copy the token to n8n credentials

## 🎯 Available Nodes

### 1. Tiny ERP (Main Node)
**Modular node with all Tiny ERP operations**
- Products: Get products with pagination and filtering
- Orders: Retrieve detailed order information
- Users: Get user data with multiple filter options
- AI Tool Ready: `usableAsTool: true` for AI Agent integration

### 2. AI Tools Collection
**Specialized nodes optimized for AI Agent workflows**

#### TinyErpAiTool (Recommended)
- **Purpose**: Comprehensive AI tool combining all operations
- **Best For**: General AI agents that need operation flexibility
- **Features**: Automatic operation detection, smart parameter inference

#### TinyErpProductsTool
- **Purpose**: Dedicated product operations
- **Best For**: Inventory-focused AI agents
- **Operations**: Product search and retrieval

#### TinyErpOrdersTool
- **Purpose**: Dedicated order operations  
- **Best For**: Order management AI agents
- **Operations**: Order data retrieval

#### TinyErpUsersTool
- **Purpose**: Dedicated user operations
- **Best For**: Customer management AI agents
- **Operations**: User search and filtering

## 🤖 AI Agent Integration

### Environment Setup
```bash
# Required for AI tool functionality
N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
```

### Docker Compose Example
```yaml
environment:
  - N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
```

### AI Parameter Examples
```typescript
// AI can automatically fill these parameters
'={{ $fromAI("operationType", "Type of operation: products, orders, or users", "string") }}'
'={{ $fromAI("numeroPedido", "The order number to retrieve data for", "string") }}'
'={{ $fromAI("productName", "Name of the product to search for", "string") }}'
```

### Recommended AI Models
- **Claude 3.5 Sonnet**: Excellent parameter inference
- **Claude 3.7 Sonnet**: Advanced reasoning capabilities
- **GPT-4**: Good general performance

## 📖 Usage Examples

### Basic Product Search
```json
{
  "resource": "products",
  "operation": "getProducts",
  "numeroPaginas": 1,
  "productName": "laptop"
}
```

### Order Lookup
```json
{
  "resource": "orders", 
  "operation": "getOrderData",
  "numeroPedido": "ORD-12345"
}
```

### User Search
```json
{
  "resource": "users",
  "operation": "getUserData",
  "nomeUsuario": "João Silva",
  "mesNascimento": 3,
  "cpf": "123.456.789-00"
}
```

## 🏗️ Architecture

### Modular Structure
```
nodes/
├── TinyErp/                    # Main modular node
│   ├── TinyErp.node.ts        # Main node definition
│   ├── actions/               # Operations directory
│   │   ├── products/          # Product operations
│   │   ├── orders/            # Order operations
│   │   └── users/             # User operations
│   └── transport/             # API communication layer
```

### Benefits
- **Separation of Concerns**: Each operation in its own file
- **Maintainability**: Easy to update individual operations
- **Scalability**: Simple to add new operations
- **Team Collaboration**: Multiple developers can work simultaneously
- **Testing**: Individual operations can be unit tested

## 🔍 API Operations

### Products
- **Get Products**: Retrieve product catalog with pagination
- **Search Products**: Filter products by name or criteria
- **Inventory Check**: Check product availability

### Orders
- **Get Order Data**: Detailed order information
- **Order Status**: Current order status and tracking
- **Order Items**: List of items in an order

### Users
- **Get User Data**: User information and details
- **Search Users**: Filter by name, CPF, birth month
- **User History**: Customer interaction history

## 🛠️ Development

### Setup
```bash
git clone <repository-url>
cd n8n-nodes-tiny-erp-api-v2
npm install
```

### Build
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Linting
```bash
npm run lint
npm run lintfix
```

## 📚 Documentation

- [Main Node Documentation](./nodes/TinyErp/README.md)
- [AI Tools Documentation](./nodes/TinyErpAiTools/README.md)
- [API Reference](https://tiny.com.br/api)

## 🤝 Contributing

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

## 📄 License

MIT License - see [LICENSE](./LICENSE) file for details

## 🆕 Changelog

### v0.2.0
- ✨ Added AI tool nodes for AI Agent integration
- 🏗️ Modularized node structure
- 🤖 Added `$fromAI()` support
- 📚 Comprehensive documentation
- 🔧 Improved error handling

### v0.1.3
- 🐛 Bug fixes and improvements
- 📝 Updated documentation

## 🔗 Links

- [Tiny ERP](https://tiny.com.br)
- [n8n Documentation](https://docs.n8n.io)
- [n8n Community](https://community.n8n.io)