n8n-nodes-hamkar

This is an n8n community node for integrating with the Hamkar.co API. It allows you to manage contacts and records (create, update, delete, and list) through n8n workflows, plus automatic workflow triggers.

n8n is a fair-code licensed workflow automation platform.

📚 Documentation

• Complete Documentation - Full guide with examples and best practices
• Quick Reference - Cheat sheet for common operations
• Troubleshooting Guide - Solutions to common issues

📑 Quick Links

• Installation
• Operations
• Credentials
• Trigger Node
• Example Workflows
• Compatibility
• Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Manual Installation

To install manually:

1. Go to Settings > Community Nodes
2. Select Install
3. Enter n8n-nodes-hamkar in Enter npm package name
4. Agree to the risks of using community nodes
5. Select Install

After installing the node, you can use it like any other node. n8n displays the node in search results in the Nodes panel.

Operations

The Hamkar package includes two nodes:

1. Hamkar Node (Regular Operations)

Contact Operations

• Create: Create a new contact with name, phone numbers, address, and type (legal/natural)
• Update: Update an existing contact by ID
• Delete: Delete a contact by ID (or archive using update)
• Get Many: Retrieve multiple contacts with optional search filtering

Record Operations

• Create: Create a new record with contact information, products, and custom field answers
• Update: Update an existing record by ID
• Delete: Delete a record by ID
• Get Many: Retrieve multiple records with optional search filtering

2. Hamkar Trigger Node (Automatic Workflow Starts)

Automatically triggers workflows when events occur in Hamkar:

Contact Triggers

• Contact Created: Triggers when a new contact is created
• Contact Updated: Triggers when a contact is modified
• Contact Deleted: Triggers when a contact is deleted

Record Triggers

• Record Created: Triggers when a new record is created
• Record Updated: Triggers when a record is modified
• Record Deleted: Triggers when a record is deleted

Note: Trigger functionality requires webhook support from Hamkar.co. If webhooks are not available, use scheduled polling with "Get Many" operations instead.

Credentials

To use this node, you need a Hamkar API key:

1. Log in to your Hamkar.co account
2. Navigate to your project settings
3. Go to the "Connection" (اتصال) section
4. Copy your API key (X-API-Key)

In n8n:

1. Go to Credentials > New
2. Search for Hamkar API
3. Paste your API key
4. Save the credential

Compatibility

• Minimum n8n version: 0.200.0
• Tested with n8n version: 1.0.0+

Usage

Creating a Contact

To create a contact, you need to provide:

• Name: Contact name
• Phone Number: Mobile phone number
• Telephone Number (optional): Landline number
• Address (optional): Contact address
• Is Legal: Whether it's a legal entity (true) or natural person (false)
• Is Archived: Whether the contact is archived

Creating a Record

To create a record, you need to provide:

• Tag: Status title/tag
• Topic: Topic title
• Due Date: Date in YYYY-MM-DD format
• Contact: Contact information including name, phone number, and type
• Products: List of products with ID, quantity, and price
• Answers: Custom field answers with field ID and answer text

Updating a Record

Same as creating, but you also need to provide the Record ID of the record you want to update.

Deleting a Record

Provide the Record ID of the record you want to delete.

Listing Records

You can:

• Return all records or limit the number
• Use a search query to filter results

Trigger Node

Setup Webhook Triggers

1. In n8n:

   • Add "Hamkar Trigger" node to your workflow
   • Select the event you want to listen for
   • Copy the webhook URL provided

2. In Hamkar.co:

   • Navigate to Settings → Webhooks (if available)
   • Add the webhook URL from n8n
   • Select which events to send
   • Save configuration

3. Activate Workflow:

   • Toggle your workflow to "Active"
   • Test by creating/updating a contact or record in Hamkar

Alternative: Polling Method

If Hamkar.co doesn't support webhooks yet, use scheduled polling:

[Schedule Trigger] (every 5 minutes)
   ↓
[Hamkar - Get Many Contacts]
   ↓
[Function Node] (compare with previous results)
   ↓
[Process new/changed items]

Example Workflows

1. Create Contact from Form Submission

[Webhook Trigger] (Form submission)
   ↓
[Hamkar - Create Contact]
   Name: {{$json.name}}
   Phone: {{$json.phone}}
   ↓
[Send Email] (Confirmation)

2. Auto-Email New Contacts

[Hamkar Trigger] (Contact Created)
   ↓
[Send Email]
   To: sales@company.com
   Subject: New Contact: {{$json.name}}
   Body: Phone: {{$json.phone_number}}

3. Daily Contact Report

[Schedule Trigger] (Daily at 9 AM)
   ↓
[Hamkar - Get Many Contacts]
   Return All: true
   ↓
[Function Node] (Calculate statistics)
   ↓
[Send Email] (Report to manager)

4. Import Contacts from CSV

[Read CSV File]
   ↓
[Split In Batches] (10 contacts per batch)
   ↓
[Hamkar - Create Contact]
   Name: {{$json.name}}
   Phone: {{$json.phone}}
   ↓
[Wait] (1 second between batches)

5. Sync to Google Sheets

[Hamkar Trigger] (Contact Created/Updated)
   ↓
[Google Sheets - Append/Update Row]
   Values: {{$json.name}}, {{$json.phone_number}}

For more examples and detailed guides, see DOCUMENTATION.md.

Resources

• n8n community nodes documentation
• Hamkar.co API Documentation

Development

If you want to contribute or modify this node:

# Clone the repository
git clone https://github.com/yourusername/n8n-nodes-hamkar.git
cd n8n-nodes-hamkar

# Install dependencies
npm install

# Build the node
npm run build

# Watch for changes during development
npm run dev

License

MIT

Support

Documentation

Before asking for help, check these resources:

1. Complete Documentation - Comprehensive guide with all features
2. Quick Reference - Quick lookup for common tasks
3. Troubleshooting Guide - Solutions to common problems

Getting Help

• Issues & Bugs: GitHub Issues
• Questions: n8n Community Forum
• Feature Requests: GitHub Issues with "enhancement" label

Reporting Bugs

When reporting an issue, please include:

• n8n version
• Node package version
• Error message (full text)
• Steps to reproduce
• Expected vs actual behavior

Version History

See CHANGELOG.md for version history and updates.

Current Version: 3.0.12

Recent Updates

• ✅ Added Hamkar Trigger node for automatic workflows
• ✅ Support for Contact and Record events
• ✅ Improved icon and UI elements
• ✅ Comprehensive documentation and guides