n8n-nodes-everest-tms/README.md

Everest TMS n8n integration

# n8n-nodes-everest-tms

This is an n8n community node that integrates [Everest TMS](https://geteverest.io) with your n8n workflows, enabling seamless transport and logistics management automation with AI-powered assistance.

[Everest TMS](https://geteverest.io) is a comprehensive transport management system platform, while [n8n](https://n8n.io/) is a [fair-code licensed](https://docs.n8n.io/reference/license/) workflow automation tool that allows you to connect various services.

## Table of Contents

- [Installation](#installation)
- [Operations](#operations)
- [Credentials](#credentials)
- [Compatibility](#compatibility)
- [Usage](#usage)
- [Resources](#resources)
- [Version History](#version-history)

## Installation

To install this community node, please follow the official [n8n community node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/).

You can install it via npm:

```bash
npm install n8n-nodes-everest-tms
```

Or through the n8n interface by searching for `n8n-nodes-everest-tms` in the Community Nodes section.

## Operations

This node supports comprehensive Everest TMS operations, also usable as tools, across multiple resources:

### 🚚 Missions
- **Create, Get, Update, Delete** transport missions
- **Estimate** mission costs and pricing
- **Accept** missions (for agents)
- **Set Status** and track mission progress
- **Cancel** missions with automatic refunds
- **Get Multiple** missions by references
- **Mark as Seen** by agents
- **Advanced filtering** by date ranges, statuses, clients, agents
- **Timezone support** for Europe/Paris with automatic DST handling

### 👥 Clients & Agents
- **Complete CRUD operations** for clients and agents
- **Manage** client billing information and custom requirements
- **Update** agent locations and availability in real-time
- **Filter** by availability, status, and search criteria
- **Custom information fields** for specialized requirements

### 🧾 Invoices & Billing
- **Create and manage** invoices and estimates
- **Track** payment status and dates
- **Associate** missions with invoices
- **Generate** billing documents
- **Support** for VAT and tax calculations

### 🔔 Alerts & Notifications
- **Create platform alerts** with different categories (success, warning, danger, info)
- **Filter alerts** by status (read/unread) and search terms
- **Send SMS** notifications to multiple phone numbers
- **Send Email** notifications to multiple addresses
- **Send Push Notifications** to specific agents
- **Use mission references** with {MISSION_REF} placeholder

### 🤖 Walter AI Assistant
- **Send prompts** to Walter AI for intelligent assistance
- **Get AI-powered responses** with actionable commands
- **Send messages** from Walter to users
- **Retrieve available commands** that Walter can execute
- **Conversation history** management
- **Command execution** with parameters
- **Multi-user support** with user_id parameter

### 👤 CRM Contacts
- **Manage** CRM contacts and customer relationships
- **Create events** and track interactions
- **Organize** contacts by company and category
- **Points-based** customer scoring system

### 🗺️ Route Optimization
- **Optimize** delivery routes for multiple vehicles
- **Manage** capacity constraints and time windows
- **Calculate** optimal paths and costs
- **Support** for different vehicle profiles (car, truck, bike, walk)
- **Advanced constraints** (max distance, travel time, tasks)

### 🔗 Webhooks
- **Subscribe/Unsubscribe** to real-time events
- **Support** for all Everest webhook events:
  - Mission events (created, updated, status changes, etc.)
  - Client and agent events
  - Invoice and billing events
  - Platform configuration changes
  - And many more...

### ℹ️ Platform Information
- **Get** platform details and configuration
- **Retrieve** available services, statuses, and vehicle types
- **Check** address coverage and availability
- **Get** time slots for mission scheduling
- **Platform availabilities** and working hours

## Credentials

To authenticate, you need to configure Everest API credentials in n8n:

1. **API Domain**: Your Everest platform domain (e.g., `your-platform.everst.io`)
2. **Bearer Token**: Your API Bearer token obtained from your Everest platform

These credentials are configured in the n8n credentials section under `everestApi`.

### How to get your Bearer Token

1. Log in to your Everest platform
2. Navigate to your API settings or developer section
3. Generate or copy your Bearer token
4. Use this token in the n8n credentials configuration

## Compatibility

This node has been tested with:
- n8n version 1.0.0+
- Everest API version 1.156.1+

## Usage

### Basic Setup

1. **Get Bearer Token**: Obtain your Bearer token from your Everest platform
2. **Install the Node**: Add this community node to your n8n instance
3. **Configure Credentials**: Set up your Everest API credentials in n8n with your domain and Bearer token
4. **Create Workflow**: Add the Everest node to your workflow
5. **Select Operations**: Choose the desired resource and operation

### Example Workflows

#### Create a Mission with Timezone Support
```json
{
  "resource": "mission",
  "operation": "create",
  "service_id": 1,
  "address_start": "42 rue de la Paix, 75001 Paris",
  "address_end": "15 avenue des Champs-Élysées, 75008 Paris",
  "additionalFields": {
    "client_id": 123,
    "comment": "Urgent delivery",
    "weight": 5.5,
    "start_date": "2025-06-26 14:30"
  }
}
```

#### Create Platform Alert
```json
{
  "resource": "alert",
  "operation": "create",
  "icon": "invoice",
  "category": "danger",
  "text": "Invoice awaiting payment",
  "created_for": "client:123",
  "additionalFields": {
    "url": "/client/invoices",
    "status": 0
  }
}
```

#### Interact with Walter AI Assistant
```json
{
  "resource": "walter",
  "operation": "prompt",
  "question": "Show me today's missions with status 'pending'",
  "save_to_history": true
}
```

#### Send Walter Message with User ID
```json
{
  "resource": "walter",
  "operation": "say",
  "message": "I found 5 urgent missions that need attention",
  "user_id": 123,
  "save_to_history": true,
  "commands": {
    "command": [{
      "command": "get_missions",
      "parameters": "status,urgent,date_start,2025-01-20"
    }]
  }
}
```

#### Send Multi-Channel Notifications
```json
{
  "resource": "notification",
  "operation": "sendSms",
  "tels": "0600000000,0611111111",
  "text": "Your mission {MISSION_REF} has been updated",
  "mission_ref": "ABC123XXX"
}
```

#### Subscribe to Real-time Webhooks
```json
{
  "resource": "webhook",
  "operation": "subscribe",
  "url": "https://my-site.com/webhook/everest",
  "event": "mission_created"
}
```

#### Advanced Mission Filtering
```json
{
  "resource": "mission",
  "operation": "getMany",
  "options": {
    "limit": 100,
    "statuses": "pending,in-progress",
    "date_between_start": "2025-01-20 09:00",
    "date_between_end": "2025-01-20 18:00",
    "client": 123,
    "order_by": "start_date",
    "order_by_order": "ASC"
  }
}
```

#### Optimize Delivery Routes
```json
{
  "resource": "route",
  "operation": "optimize",
  "shipments": [
    {
      "pickup": {
        "id": 1,
        "location": [2.3317, 48.8291],
        "service": 300
      },
      "delivery": {
        "id": 2,
        "location": [2.3928, 48.8522],
        "service": 300
      },
      "weight": 100,
      "volume": 0.25
    }
  ],
  "vehicles": [
    {
      "id": 1,
      "profile": "car",
      "start": [2.3969, 48.8666],
      "capacity": 10,
      "weight": 250,
      "volume": 1.3
    }
  ],
  "options": {
    "distribute_fairly": true,
    "split_per_day": true
  }
}
```

## Key Features

### 🤖 AI Integration
- **Walter AI Assistant** for intelligent automation
- **Natural language processing** for mission queries
- **Command execution** with parameter validation
- **Conversation history** management
- **Multi-user support** with user_id parameter for targeted interactions

### 🔔 Real-time Notifications
- **Multi-channel notifications** (SMS, Email, Push)
- **Template support** with mission reference placeholders
- **Bulk messaging** capabilities
- **Platform alerts** with categorization

### 📊 Advanced Filtering
- **Complex date range queries** with timezone support
- **Multi-status filtering** with comma-separated values
- **Search capabilities** across multiple fields
- **Pagination support** for large datasets

### 🛡️ Robust Error Handling
- **Comprehensive validation** for all required fields
- **Graceful error recovery** with continue-on-fail support
- **Detailed error messages** for troubleshooting
- **Simplified authentication** with direct Bearer token

### 🔐 Simplified Authentication
- **Direct Bearer token** authentication
- **No repeated authentication calls**
- **Secure token storage** per credential
- **Improved performance** with reduced API calls

## Resources

- [Everest TMS](https://geteverest.io)
- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)

## License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.