n8n-nodes-inflow-crm/README.md

Official Inflow CRM integration for n8n. Create, update, search records and handle webhooks with dynamic field support.

# n8n-nodes-inflow-crm

[![npm version](https://badge.fury.io/js/n8n-nodes-inflow-crm.svg)](https://www.npmjs.com/package/n8n-nodes-inflow-crm)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official **Inflow CRM** integration for n8n. This community node package provides comprehensive CRM automation capabilities, allowing you to create, update, search, and manage records while handling real-time webhooks with dynamic field support.

## 🎯 What is this?

The **n8n-nodes-inflow-crm** package is a community node that seamlessly integrates [Inflow CRM](https://inflowcrm.pl) with your n8n workflows. It provides:

- **CRUD Operations**: Create, read, update, and delete CRM records
- **Real-time Webhooks**: Trigger workflows when CRM events occur
- **Dynamic Field Mapping**: Automatically fetch and map CRM fields
- **Pipeline & Stage Management**: Easily assign records to sales pipelines and stages
- **Bulk Operations**: Retrieve multiple records at once for efficient processing
- **File Upload Support**: Handle document and attachment uploads
- **Advanced Filtering**: Search and filter records with complex criteria
- **Multi-Module Support**: Work with all Inflow CRM modules (contacts, companies, deals, etc.)

## 📦 Installation

### Option 1: Install via n8n Admin Panel (Recommended)

1. Open your n8n instance
2. Go to **Settings** → **Community Nodes**
3. Click **Install a community node**
4. Enter the package name: `n8n-nodes-inflow-crm`
5. Click **Install**

### Option 2: Manual Installation

For detailed installation instructions, visit the [official n8n community nodes documentation](https://docs.n8n.io/integrations/community-nodes/installation/).

```bash
# Install via npm in your n8n installation directory
npm install n8n-nodes-inflow-crm
```

### Option 3: Docker Environment

Add the package to your Docker environment variables:

```bash
# Docker environment variable
N8N_NODES_INCLUDE=n8n-nodes-inflow-crm

# Or install during container startup
docker exec -it n8n npm install n8n-nodes-inflow-crm
```

## 🔧 Available Actions & Triggers

### 📋 Node Actions

The **Inflow CRM** node provides nine main operations:

#### 📝 Create Record
- **Purpose**: Create new records in any CRM module
- **Fields**: Dynamic field mapping based on selected module
- **File Support**: Upload attachments and documents
- **Validation**: Automatic required field validation

#### ✏️ Update Record  
- **Purpose**: Update existing records by ID
- **Fields**: Only specify fields you want to change
- **File Support**: Add or replace attachments
- **Flexibility**: Partial updates supported

#### 🔍 Search Records
- **Purpose**: Find multiple records with filtering
- **Filtering**: Advanced filter capabilities with dynamic fields
- **Pagination**: Configurable limit and page parameters
- **Sorting**: Sort by any field in ascending/descending order

#### 🔎 Find One Record
- **Purpose**: Retrieve a single record matching criteria
- **Filtering**: Flexible filtering without requiring ID
- **Use Case**: Get specific records based on any field values

#### 🆔 Get By ID
- **Purpose**: Quickly retrieve any single record when you know its ID
- **When to Use**: Perfect for lookups, follow-up workflows, or fetching details after creating a record
- **User Benefit**: Fast, direct access to specific records without complex filtering

#### 🆔📋 Get By IDs
- **Purpose**: Retrieve multiple records at once by providing a list of IDs (comma-separated)
- **When to Use**: Batch operations, syncing specific records, processing lists of items
- **User Benefit**: Process multiple records efficiently in one operation with pagination and sorting support

#### 🗑️ Delete Record
- **Purpose**: Delete records by ID
- **Safety**: Permanent deletion - use with caution
- **Response**: Confirmation of deletion status

#### 🔢 Count Records
- **Purpose**: Count records matching filter criteria
- **Filtering**: Optional filters to count specific subsets
- **Performance**: Efficient for large datasets

#### ⚙️ Get Processes
- **Purpose**: Lists all available sales pipelines/processes and their stages
- **When to Use**: Building workflows that need to know available pipelines, automating pipeline assignments
- **Supported Modules**: Works with Potentials (leads) and Orders
- **User Benefit**: Dynamic access to your pipeline structure for smart automation

### 🎣 Webhook Triggers

The **Inflow CRM Trigger** node responds to real-time CRM events:

#### 🆕 Record Created
- **Trigger**: When new records are created in selected module
- **Data**: Complete record data in webhook payload
- **Real-time**: Instant notification of new records

#### 📝 Record Updated  
- **Trigger**: When records are modified in selected module
- **Data**: Updated record data with changes
- **Use Case**: Sync changes to other systems

#### 🗑️ Record Deleted
- **Trigger**: When records are deleted from selected module  
- **Data**: Information about deleted record
- **Cleanup**: Trigger cleanup workflows

## 🎛️ Dynamic Field Support

### How Dynamic Fields Work

The integration automatically fetches available fields from your Inflow CRM instance and presents them in n8n's **Resource Mapper** interface. This means:

- ✅ **Automatic Field Discovery**: Fields are loaded dynamically based on your CRM configuration
- ✅ **Type-Safe Mapping**: Field types are respected (text, number, date, boolean, etc.)
- ✅ **Module-Specific Fields**: Different field sets for different modules (contacts, companies, deals)
- ✅ **Custom Field Support**: Works with your custom fields automatically

### Current n8n Limitations

⚠️ **Important**: n8n currently has limitations with certain dynamic field types that affect the user experience:

#### Multiselect Fields
- **Issue**: Dynamic multiselect fields fetched from the API are not fully supported
- **Workaround**: Use text input with comma-separated values
- **Status**: This is an n8n platform limitation, not specific to Inflow CRM

#### Dynamic Relation Fields with Search
- **Issue**: Relation fields with search/autocomplete functionality (like those in Inflow CRM UI) cannot be replicated in n8n
- **Workaround**: Use the related record ID directly
- **Example**: Instead of searching for "John Doe", use the contact ID: `12345`

#### Complex Field Types
- **Issue**: Some advanced field types may display as simple text inputs
- **Impact**: Functionality works, but UX may be less intuitive than in the Inflow CRM interface

## 🚧 Current Issues & Roadmap

### Recently Resolved ✅

#### Potentials with Pipelines and Stages
- **Status**: ✅ **RESOLVED** - Now fully working!
- **What Changed**: You can now easily assign Potentials (leads) and Orders to specific pipelines and stages
- **How It Works**:
  - When creating or updating records, select from a user-friendly dropdown
  - Format: "Proces: [Pipeline Name] z etapu: [Stage Name]"
  - Example: "Proces: Sprzedaż produktów z etapu: Pierwszy kontakt"
  - No manual ID entry needed - just pick from the list!
- **Supported Modules**: Potentials and Orders

### Upcoming Improvements

- Better support for complex field relationships
- Improved multiselect field handling (pending n8n platform updates)
- Advanced bulk operations
- Additional automation capabilities

## 📚 Advanced Usage & API Reference

For operations that are not possible through the n8n node interface, you can use the raw Inflow CRM API directly in your workflows.

### 📖 Detailed API Documentation

Complete API documentation is available at: **[https://inflowcrm.github.io/public-api-docs/](https://inflowcrm.github.io/public-api-docs/)**

This documentation includes:
- Complete endpoint reference
- Request/response examples  
- Authentication details
- Advanced filtering options
- Webhook event specifications
- Rate limiting information

### 🔗 Using Raw API Calls

When the n8n node doesn't support your specific use case, you can make direct API calls using n8n's **HTTP Request** node:

```javascript
// Example: Custom API call in n8n HTTP Request node
{
  "method": "POST",
  "url": "https://srv.inflowcrm.pl/api/your-endpoint",
  "headers": {
    "x-api-key": "{{$credentials.inflowCrmApi.apiKey}}",
    "Content-Type": "application/json"
  },
  "body": {
    "your": "custom data"
  }
}
```

## 🔐 Authentication

The package uses **API Key authentication** with Inflow CRM. To configure:

1. Generate an API key in your Inflow CRM instance
2. In n8n, create new **Inflow CRM API** credentials
3. Enter your API key and server URL
4. Test the connection

## 🐛 Debugging

This project uses the [`debug`](https://www.npmjs.com/package/debug) library for comprehensive logging. Enable debugging with:

```bash
# Enable all Inflow CRM debugging
DEBUG=inflow:* n8n start

# Enable specific components
DEBUG=inflow:api,inflow:auth n8n start
```

Available namespaces:
- `inflow:api` - API communication
- `inflow:auth` - Authentication  
- `inflow:cache` - Metadata caching
- `inflow:actions` - Node actions

## 🤝 Support & Contributing

### Getting Help

- 📖 [API Documentation](https://inflowcrm.github.io/public-api-docs/)
- 🐛 [Report Issues](https://github.com/InflowCRM/n8n-nodes-inflow-crm/issues)
- 💬 [n8n Community](https://community.n8n.io)

### Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our [GitHub repository](https://github.com/InflowCRM/n8n-nodes-inflow-crm).

## 📄 License

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

---

**Made with ❤️ by the Inflow CRM Team**

[Inflow CRM](https://inflowcrm.pl) | [Documentation](https://inflowcrm.github.io/public-api-docs/) | [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)