n8n-nodes-avanta

An n8n community node for integrating with the Avanta B2B E-Commerce platform. This node enables seamless integration with Avanta's comprehensive B2B commerce solution, allowing you to automate customer management, order processing, inventory tracking, and business reporting directly from your n8n workflows.

Table of Contents

• About Avanta
• About this n8n node
• Installation
• Configuration
• Operations
• Usage Examples
• API Reference
• Changelog
• Contributing
• License
• Support

About avanta: ERP-First B2B Commerce Platform

avanta is an ERP-first B2B commerce platform for manufacturers, industrial companies, and wholesalers.

The platform is specifically designed for complex B2B processes and connects digital sales, service, and after-sales channels directly with the ERP system.

Unlike traditional e-commerce systems, avanta offers a comprehensive B2B feature set out of the box. Companies can digitalize key sales and customer service processes without extensive custom development.

The platform is open source and can be deployed as SaaS, in the cloud, or on-premise.

avanta is primarily used by mid-market and enterprise companies, particularly in industries such as mechanical engineering, plant engineering, tooling, chemicals, industrial components, and packaging.

The platform includes features such as B2B online shops, customer and service portals, PunchOut integrations (OCI / cXML), spare parts solutions, mobile apps, IoT automation, and integrated AI capabilities and bots.

About this n8n node:

This n8n node provides direct access to avanta's powerful API, enabling you to automate your workflows and integrate avanta with your existing business processes.

Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install a community node
3. Enter n8n-nodes-avanta in the npm package name field
4. Click Install

Manual Installation

If you're running n8n locally, you can install this node manually:

# Navigate to your n8n installation directory
cd ~/.n8n

# Install the node
npm install n8n-nodes-avanta

# Restart n8n

Docker Installation

For Docker installations, you can install community nodes by:

1. Using the n8n interface (recommended)
2. Building a custom Docker image with the node pre-installed

Configuration

Credentials Setup

1. In n8n, go to Credentials and create new avanta API credentials
2. Fill in the required fields:
   • Host: Your avanta API base URL including store scope (e.g., https://your-avanta-instance.com/rest/STORE_CODE or https://your-avanta-instance.com/rest/all for all stores)
   • Access Token: Your avanta API access token

Getting API Credentials

To obtain your avanta API credentials, you'll need to generate an access token through the avanta admin interface:

Step 1: Access the Admin Panel

1. Log into your avanta system with administrator privileges
2. Navigate to System > Integrations > API Tokens in the admin menu

Step 2: Create a New Integration Token

1. Click Add New Token or Create Integration
2. Provide a descriptive name for your integration (e.g., "n8n Workflow Integration")
3. Select the appropriate API Resources and Access Levels based on your workflow needs:
   • Companies: For managing B2B customer companies and relationships
   • Orders: For order processing and management
   • Products: For catalog and inventory operations
   • Reports: For generating business analytics and reports
   • Users: For customer user management

Step 3: Configure Token Permissions

Set the appropriate access levels for each resource:

• Read: View existing data
• Write: Create and update data
• Delete: Remove data (use with caution)

Step 4: Generate and Secure Your Token

1. Click Generate Token
2. Important: Copy the generated access token immediately - it will only be displayed once
3. Store the token securely (consider using a password manager)
4. Note your API base URL including store scope (typically https://your-domain.com/rest/STORE_CODE or https://your-domain.com/rest/all for all stores)

Authentication Method

The avanta API uses Bearer Token Authentication. All API requests must include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Security Best Practices

• Never share your access token in public repositories or unsecured locations
• Rotate tokens regularly for enhanced security
• Use separate tokens for different environments (development, staging, production)
• Monitor token usage through the admin panel's API logs
• Revoke unused tokens to minimize security risks

Troubleshooting Authentication

If you encounter authentication issues:

1. Verify the token hasn't expired or been revoked
2. Check that the token has the necessary permissions for your operations
3. Ensure your API base URL is correct and accessible
4. Confirm your avanta instance supports the API version being used

Operations

The avanta node supports comprehensive B2B E-Commerce operations across the following resources:

Customer Companies

• Create/Update: Register new B2B customer companies or modify existing profiles
• Deactivate: Deactivate customer companies
• Delete: Remove customer companies from the platform
• Get Many: Retrieve multiple customer companies

Company Addresses

• Create/Update: Add or modify billing and shipping addresses for B2B customers
• Deactivate: Deactivate company addresses
• Get Many: Retrieve multiple company addresses

Company Contacts

• Create: Add contact persons for B2B customer companies
• Get Many: Retrieve multiple company contacts
• Link to Companies: Associate contacts with their respective companies
• Link to Sales Organization: Associate contacts with sales organizations
• Remove: Remove company contacts

Company Groups

• Create/Update: Create or modify company groups for organizing B2B customers
• Delete: Remove company groups
• Get Many: Retrieve multiple company groups

Company Restrictions

• Create/Update: Set up product or category restrictions for companies
• Delete: Remove company restrictions

Company Roles (available from avanta v3.6)

• Create/Update: Define roles and permissions for company users
• Delete: Remove company roles
• Get Many: Retrieve multiple company roles

Company Rules (available from avanta v3.6)

• Create/Update: Configure business rules for companies
• Get Many: Retrieve multiple company rules

Company SKUs

• Create/Update: Assign custom SKU mappings for companies
• Delete: Remove company SKU assignments

Company Users

• Create: Create user accounts for B2B customer access

Bill of Materials (BOM)

• Import: Create or update Bill of Materials for products

Categories

• Create/Update: Create or modify product categories

Downloads

• Create Category: Create or update download categories
• Remove Category: Remove download categories
• Create Item: Create or update downloadable items
• Remove Item: Remove downloadable items

Order Management

• Order Create: Create new orders programmatically
• Order Simulation: Execute order simulations for testing and validation

Business Reports

• Backorders: Generate reports for items on backorder
• Credit Memos: Create credit memo documentation for returns
• Invoices: Generate invoice reports for B2B transactions
• Orders: Create comprehensive order reports and tracking
• Reshipments: Document reshipment activities and logistics
• Shipments: Track shipment status and delivery information
• Trackings: Monitor package tracking and delivery updates

Product Catalog

• Create/Update: Add new products or modify existing product information and pricing
• Get Many: Retrieve multiple products
• Remove: Delete products from the catalog

Sales Organizations

• Create: Set up sales territories and organizational structures
• Get Many: Retrieve multiple sales organizations
• Remove: Delete sales organizations

Usage Examples

Creating a Company

{
  "name": "Example Corp",
  "email": "[email protected]",
  "group_id": "1",
  "additionalFields": {
    "telephone": "+1-555-0123",
    "vat_id": "US123456789",
    "internet": "https://example.com"
  }
}

Creating an Order Report

{
  "customer_id": "CUST001",
  "company_id": 123,
  "customer_orderid": "ORD-2024-001",
  "order_positions": [
    {
      "item_pos": 1,
      "name": "Product A",
      "sku": "PROD-A-001",
      "qty": 5,
      "price": 29.99,
      "subtotal": 149.95
    }
  ]
}

Creating a Company Address

{
  "company_customer_id": "COMP001",
  "company_group_id": "1",
  "external_address_id": "ADDR001",
  "additionalFields": {
    "street": "123 Business Ave",
    "city": "Business City",
    "postcode": "12345",
    "country_id": "US",
    "address_type": 1
  }
}

API Reference

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Base URL

All API endpoints are relative to your avanta instance base URL including store scope:

https://your-avanta-instance.com/rest/STORE_CODE/V1/proline-admin/

Or for all stores:

https://your-avanta-instance.com/rest/all/V1/proline-admin/

Common Parameters

Most operations support these common parameters:

• bulk: Boolean - Whether to process multiple items in a single request
• return: Boolean - Whether to return response to a webhook
• extension_attributes: Array - Custom attributes for extending data

Error Handling

The node includes comprehensive error handling:

• Continue on Fail: Option to continue workflow execution even if the node fails
• Detailed Error Messages: Clear error descriptions for troubleshooting
• Retry Logic: Built-in retry mechanisms for transient failures

Data Types and Validation

Required Fields

Each B2B E-Commerce operation has specific required fields. Common required fields include:

• Customer Company Operations: name, group_id for company registration
• Business Report Operations: customer_id, company_id for transaction tracking
• Address Operations: company_customer_id, company_group_id for shipping/billing setup

Optional Fields

Most B2B operations support additional optional fields through the "Additional Fields" collection, enabling:

• Custom business dates and delivery schedules
• Extension attributes for custom B2B requirements
• Document file attachments for compliance and documentation
• Custom pricing structures and quantity breaks
• Tax information and VAT handling
• Multi-currency support for international B2B transactions

Date Formatting

Date fields are automatically formatted to ISO 8601 format when sent to the API.

Workflow Integration

B2B E-Commerce Use Cases

The avanta node is designed for comprehensive B2B E-Commerce automation:

• Customer Onboarding: Automate new B2B customer registration and setup
• Order Processing: Streamline order intake, validation, and fulfillment workflows
• Inventory Management: Sync product catalogs and inventory levels
• Business Reporting: Generate automated reports for sales, shipments, and analytics
• Multi-Company Management: Handle complex B2B relationships and hierarchies

Triggers

This node works well with:

• Webhook triggers for real-time order processing and customer updates
• Schedule triggers for batch reporting and inventory synchronization
• Manual triggers for on-demand B2B operations and testing

Data Flow

The node can be chained with:

• HTTP Request nodes for additional API calls and third-party integrations
• Set nodes for data transformation and B2B-specific formatting
• IF nodes for conditional logic based on customer types or order values
• Function nodes for custom B2B business logic and calculations
• Email nodes for automated B2B communication and notifications

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your API credentials are correct
   • Check that your access token hasn't expired
   • Ensure your host URL is correct

2. Validation Errors

   • Check that all required fields are provided
   • Verify data types match expected formats
   • Review field length limitations

3. Connection Issues

   • Verify network connectivity to your avanta instance
   • Check firewall settings
   • Confirm SSL/TLS configuration

Debug Mode

Enable debug mode in n8n to see detailed request/response information:

1. Set environment variable: N8N_LOG_LEVEL=debug
2. Restart n8n
3. Check logs for detailed API communication

Contributing

We welcome contributions to improve this node! Here's how you can help:

Development Setup

1. Clone the repository:

git clone https://github.com/ecoplan-avanta/n8n-nodes-avanta.git
cd n8n-nodes-avanta

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run linting:

npm run lint

Submitting Changes

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes
4. Run tests and linting: npm run lint
5. Commit your changes: git commit -m "Add your feature"
6. Push to your fork: git push origin feature/your-feature-name
7. Submit a pull request

Code Standards

• Follow TypeScript best practices
• Use ESLint configuration provided
• Add appropriate type definitions
• Include JSDoc comments for public methods
• Follow n8n node development guidelines

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Documentation

• n8n Documentation
• avanta API Documentation
• Node Development Guide

Community

• n8n Community Forum
• GitHub Issues

Commercial Support

For commercial support and custom development:

• Email: [email protected]
• Website: https://www.ecoplan.com

Changelog

For a detailed list of changes and version history, see the CHANGELOG.md file.

You can also view the releases on GitHub Releases.

Note: The changelog is automatically generated from git commits when pushing to a release branch (GitLab CI). Commits are categorized based on their message prefixes:

• feat, add, AVANTAN8N-*, AVANTA-* → Added
• fix, bugfix, hotfix → Fixed
• Other commits → Changed

GitHub Releases are automatically created after npm publish via GitHub Actions.

Latest Version: 0.1.59

Highlights of recent releases:

• Added CHANGELOG.md and README.md to npm package
• Version publishing workflow improvements
• Migrated publishing from GitLab to GitHub
• AVANTAN8N-26: Permission management for n8n-node
• Fixed product node download import as URL type
• Debug mode for API requests
• AVANTAN8N-48: Fixed Dynamic Custom Attributes UI Collection error
• AVANTAN8N-47: Fixed company deactivation functionality
• Category synchronization support
• Bill of Materials (BOM) synchronization

Note: This is a community-maintained node. For issues specific to the avanta API itself, please contact avanta support directly.