n8n-nodes-perfexcrm

This is an n8n community node for interacting with Perfex CRM. It provides operations for managing Customers, Invoices, and Payments.

Installation

In n8n Desktop or Self-Hosted

1. Go to Settings > Community Nodes
2. Click Install a community node
3. Enter n8n-nodes-perfexcrm and click Install

Manual Installation

cd ~/.n8n/nodes
npm install /path/to/n8n-nodes-perfexcrm

Development

npm install
npm run build
npm link

# In ~/.n8n/nodes directory:
npm link n8n-nodes-perfexcrm

Credentials

This node uses the Perfex CRM API module. You need to:

1. Install the API module in your Perfex CRM
2. Generate an API token from the API module settings
3. Configure the credentials in n8n with:
   • Base URL: Your Perfex CRM URL (e.g., https://your-perfexcrm.com)
   • API Token: The JWT token from the API module

Resources & Operations

Customer

| Operation | Description | Output | |-----------|-------------|--------| | Create | Create a new customer with company details, address, and billing/shipping information | customerId, status, message | | Get | Get a customer by ID | Customer details | | Get Many | Get all customers with optional limit/sort | Customer list | | Search | Search customers by company name, email, phone, etc. | Matching customers | | Update | Update customer information | Update status |

Address Handling

When creating a customer, you can:

• Fill the main address and toggle Copy to Billing Address and/or Copy to Shipping Address
• Manually fill the Billing Address separately
• Manually fill the Shipping Address separately

Invoice

| Operation | Description | Output | |-----------|-------------|--------| | Create | Create a new invoice with items, taxes, discounts, and custom fields | invoiceId, invoiceNumber, clientid, status, message | | Get | Get an invoice by ID | Invoice details | | Get Many | Get all invoices with filters (limit, sort, customer ID, status) | Invoice list | | Search | Search invoices by number, customer name, etc. with limit/sort options | Matching invoices | | Get URL | Get the customer-facing invoice URL | invoiceId, invoiceNumber, hash, invoiceUrl | | Get Admin URLs | Get admin panel and PDF URLs | invoiceId, invoiceNumber, adminUrl, pdfViewUrl, pdfDownloadUrl |

Get Many Options

• Limit: Number of results to return (default: 50)
• Sort By: Sort by ID, Date, or Invoice Number (ascending/descending)
• Customer ID: Filter by customer
• Status: Filter by invoice status (Draft, Sent, Unpaid, Partially Paid, Paid, etc.)

Search Options

• Limit: Number of results to return (default: 50)
• Sort By: Sort by ID, Date, Invoice Number, or Total (ascending/descending)

Invoice Items

Each invoice item can include:

• Description and long description
• Quantity and rate
• Unit of measure
• Tax (in format TaxName|TaxRate, e.g., KDV|20.00)
• S/N (Serial Number) - custom field

Invoice Number Auto-Generation

If the Invoice Number field is left blank, the node will automatically get the last invoice number and increment by 1.

S/N Custom Field

The S/N (Serial Number) is a custom field on invoice items. The default custom field ID is 8. If your installation uses a different ID, you can specify it in the node settings.

Payment

| Operation | Description | Output | |-----------|-------------|--------| | Create | Record a new payment for an invoice | paymentId, status, message | | Get | Get a payment by ID | Payment details | | Get Many | Get all payments with limit, sort, query, and invoice ID filter | Payment list | | Search | Search payments | Matching payments |

Get Many Options

• Limit: Number of results to return (default: 50)
• Sort By: Sort by ID, Date, or Amount (ascending/descending)
• Search Query: Filter by payment ID, transaction ID, or note
• Invoice ID: Filter payments by specific invoice

URL Outputs

Get URL (Customer-Facing)

Returns the public invoice URL that customers can access:

https://your-domain.com/invoice/{id}/{hash}

Get Admin URLs

Returns admin panel URLs (requires admin authentication):

| URL | Description | |-----|-------------| | adminUrl | Direct link to invoice in admin panel: https://your-domain.com/admin/invoices/list_invoices/{id}#{id} | | pdfViewUrl | View PDF in browser: https://your-domain.com/admin/invoices/pdf/{id}?output_type=I | | pdfDownloadUrl | Download PDF: https://your-domain.com/admin/invoices/pdf/{id} |

API Endpoints Used

| Resource | Endpoint | Methods | |----------|----------|---------| | Customers | /api/customers | GET, POST, PUT | | Invoices | /api/invoices | GET, POST | | Payments | /api/payments | GET, POST | | Search | /api/{resource}/search/{query} | GET |

Authentication

The node uses JWT authentication with the authtoken header. The token is generated by the Perfex CRM API module and should be configured in the n8n credentials.

Example Workflows

Create Customer and Invoice

1. Perfex CRM (Customer: Create)

   • Company: {{ $json.company_name }}
   • Address: Copy to Billing
   • Output: customerId

2. Perfex CRM (Invoice: Create)

   • Customer ID: {{ $json.customerId }}
   • Items: Add your products
   • Output: invoiceId

3. Perfex CRM (Invoice: Get URL)

   • Invoice ID: {{ $json.invoiceId }}
   • Output: invoiceUrl (send to customer)

Record Payment

1. Perfex CRM (Invoice: Search)

   • Find the invoice

2. Perfex CRM (Payment: Create)

   • Invoice ID: {{ $json.id }}
   • Amount: {{ $json.total }}
   • Payment Mode: 12 (or your payment mode ID)
   • Output: paymentId

Get Admin Links

1. Perfex CRM (Invoice: Get Admin URLs)
   • Invoice ID: {{ $json.invoiceId }}
   • Output: adminUrl, pdfViewUrl, pdfDownloadUrl

Country Codes

Common country codes used in Perfex CRM:

• Turkey: 228
• United States: 231
• United Kingdom: 230

Currency Codes

Common currency codes:

• TRY (Turkish Lira): 3
• USD: 1
• EUR: 2

License

MIT

Author

Ömer Vehbe ([email protected])