n8n-nodes-expertsa-4-krayin

Full-featured & Intelligent Krayin CRM Integration for n8n

Built to address real-world operational challenges in digital sales workflows. Fully optimized for Krayin CRM.

🚀 Why is this node different?

Most CRM integrations are basic wrappers, but this node was engineered specifically to solve real-world pains and production requirements:

• 🛡️ Intelligent Lead Product Preservation: In standard Krayin CRM API updates, modifying a lead wipes out all attached products unless you resend the entire catalog array. Our node handles this seamlessly: when moving a lead between stages (e.g. from abandoned checkout to approved purchase), it queries existing products and preserves them 100% intact — without requiring custom code or complex flatMap, reduce, or JSON.stringify expressions.
• ➕ Frictionless Offer Merging & Upsells: Need to add an upsell or new product offer to an existing lead? Simply provide the Product ID and Quantity. The node appends the new offer while keeping previous products and automatically recalculates the total opportunity value.
• 🎯 Simplified Product Attachment: No need to manually construct nested payloads with floating-point decimals (224.0000). Specify just the Product ID and Quantity — the node looks up and populates the official name and unit price directly from your CRM catalog.
• 🔍 Smart Lookup by SKU or Offer Code: If your sales platforms (Hotmart, Stripe, Shopify, Eduzz, Kiwify, etc.) send alphanumeric offer codes, the node locates the product by numeric ID, exact SKU, or catalog search without crashing your workflow on 404 errors.
• 🧩 Custom & Extra Attributes: Easily pass any custom fields defined in your CRM (e.g., hotmart_status, transaction_id, utm_source, coupon) structured via the UI or as raw JSON without rigid schema restrictions.
• 🔄 Direct Pipeline & Stage Filtering: Query and filter stages by name or code to dynamically route leads across sales pipelines.
• 🔑 Two Authentication Modes: Personal Access Token (recommended for production and high concurrency) or Login (Email & Password) with in-memory token caching and automatic re-login on 401. See Choosing the Right Authentication Mode before going to production.

📚 Features & Operations Guide

This node supports all core Krayin CRM resources:

1. 💼 Leads & Opportunities

• Create Lead (create):
  • Title, opportunity value, linked contact (person_id), pipeline, and initial stage.
  • Lead Products: Add one or multiple products specifying just Product ID and Quantity. If the lead value is left as 0, it is automatically calculated from the products sum.
  • Custom Attributes: Add custom attributes via Code and Value pairs or advanced JSON.
• Get Lead (get): Fetch comprehensive lead details by ID, including attached products and contacts.
• Get Many Leads (getAll): Filter leads by pipeline (pipeline_id), stage (stage_id), or assigned user (user_id), with automatic pagination.
• Update Lead (update):
  • Stage Transitions: Change the Stage ID — all existing products are preserved automatically.
  • Product Update Mode: Choose between Preserve Existing and Add New (Default), Replace All (Overwrite), or Clear All Products.
  • Deal Status: Switch between Open, Won, or Lost.
• Delete Lead (delete): Remove the lead opportunity from CRM.

2. 📦 Products & Services

• Get Product (get):
  • Accepts numeric ID (e.g. 12) or alphanumeric code / SKU (e.g. 9t67pevq).
  • Standardized top-level response for clean n8n mapping ($json.id, $json.price, $json.name).
• Get Many Products (getAll): Filter products by SKU or name with automatic pagination.
• Create Product (create): Register new products with name, SKU, price, and description.
• Update & Delete Products: Keep your product catalog synchronized.

3. 👤 Contacts (Persons)

• Create Contact (create): Add contacts with email, phone numbers, job title, and organization link.
• Get Contact (get): Retrieve contact details by ID.
• Get Many Contacts (getAll): Search by name or email, or list all contacts.
• Update & Delete Contacts.

4. 🏢 Organizations (Companies)

• Create Organization (create): Add company profiles with full address information.
• Get & Get Many Organizations: View companies associated with your contacts and opportunities.
• Update & Delete Organizations.

5. 📅 Activities (Tasks & Calendar)

• Create Activity (create): Schedule calls, meetings, lunches, or notes with start/end timestamps linked to a lead.
• Get Many Activities (getAll): Track pending and completed activities.
• Update Activity (update): Mark as completed (is_done) or update notes.
• Delete Activity (delete).

6. 📊 Sales Pipelines & Stages

• Pipeline (pipeline): List all sales pipelines configured in your CRM.
• Stage (stage): Retrieve pipeline stages with filters by Pipeline ID, Stage Name, or Stage Code (e.g. won, lost).

🔐 Credential Setup

In n8n, navigate to Credentials > Add Credential and search for Krayin CRM API.

🌟 Option 1: API Token (Personal Access Token) — Recommended for High Concurrency

This is the fastest, zero-latency, and most robust method for production workflows handling simultaneous webhooks.

To enable Personal Access Tokens visually in your Krayin CRM, install the official expertsa/krayin-api-keys plugin:

# In your Krayin CRM root directory:
composer require expertsa/krayin-api-keys
php artisan optimize:clear

How to get your API Token:

1. In your Krayin CRM panel, go to Settings > API Keys (/admin/settings/api-keys).
2. Click "+ Create API Key" and give it a label (e.g. n8n Production).
3. Copy the generated Personal Access Token.
4. In n8n, select Authentication Type: API Token (Personal Access Token) - Recommended for High Concurrency.
5. Enter your Base URL and paste the token into API Token.

🔑 Option 2: Login (Email & Password)

Authenticates directly via the Krayin REST API using administrator credentials:

1. In Authentication Type, select: Login (Email & Password).
2. Fill in:
   • Base URL: Your Krayin instance URL (e.g. https://crm.yourdomain.com).
   • Email: Administrator/user email in Krayin CRM.
   • Password: User password.
3. The node logs in via API and caches the Bearer token in memory, per n8n process, for up to 12 hours. If the API answers 401 Unauthorized, the node waits a short random delay, reuses a token renewed by another execution in the same process if there is one, or logs in again, and retries the request once.

⚠️ Login mode is intended for simple setups (a single n8n process, low concurrency, testing). For production with parallel executions or multiple workers, use Option 1 (API Token). See the section below.

⚠️ Choosing the Right Authentication Mode (Read Before Going to Production)

TL;DR

If your workflows run in production with any concurrency, use the API Token mode.

Why Login mode can fail under concurrency

In Login mode, the node has to call Krayin's login endpoint to obtain a Bearer token. Depending on your Krayin version and configuration, a new login for a user can invalidate the tokens previously issued to that same user.

The node caches the token in memory to avoid logging in on every request. However, that memory is not shared between separate n8n processes:

• Single n8n process (regular mode): all executions share the same in-memory cache → one login, one token, no conflict.
• Multiple processes (queue mode with several workers, or isolated execution processes): each process has its own cache and performs its own login. This can produce a "token ping-pong":
  1. Worker A logs in and gets token T1.
  2. Worker B logs in and gets token T2 — Krayin may revoke T1.
  3. Worker A's next request fails with 401 Unauthorized.
  4. Worker A logs in again (T3), which may now revoke T2… and so on.

The node mitigates this with a randomized delay and one automatic re-login + retry after a 401. This resolves most occasional collisions, but under sustained bursts of parallel executions some requests can still fail.

Why the token isn't shared between processes

Versions 1.0.9 and 1.0.10 stored the login token in a temporary file on disk (os.tmpdir()) so that all n8n processes on the same machine could reuse it. Starting with v1.0.11, this disk cache was removed: n8n requires verified community nodes to run on n8n Cloud, where access to the file system (fs, path, os) is not allowed. There is no supported mechanism for a community node to share state between n8n workers, so the definitive solution for concurrency is the API Token mode, which requires no login at all.

Symptoms that you should switch to API Token

• Intermittent errors such as 401 Unauthorized, Unauthenticated or Não autorizado from Krayin nodes, especially when several executions run at the same time.
• Errors that disappear when you re-run the same execution manually.
• Failures that increase during traffic peaks (launches, campaigns, payment webhook bursts).

How to migrate from Login to API Token

1. Install the expertsa/krayin-api-keys plugin on your Krayin CRM (see Option 1).
2. Create an API key in Settings > API Keys and copy the token.
3. In n8n, open your existing Krayin CRM API credential, change Authentication Type to API Token (Personal Access Token), paste the token and save.
4. Workflows that use this credential are updated automatically — no need to edit the nodes.

💡 Tip: create a dedicated API key per environment (e.g. n8n Production, n8n Staging) so you can revoke one without affecting the others.

🛠️ Installation

In n8n (Community Node)

1. In your n8n instance, go to Settings > Community Nodes.
2. Click Install a community node.
3. In the npm Package Name field, enter:

n8n-nodes-expertsa-4-krayin

4. Accept the risk agreement and click Install.

Local Development & Build

# 1. Install dependencies
npm install

# 2. Build TypeScript and copy assets
npm run build

# 3. Spin up local n8n via Docker
docker-compose up -d

💡 Example Workflow

To accelerate your integration, a ready-to-import reference workflow is provided in this repository:

📁 Example file: examples/Krayin CRM pipeline.json

What this example workflow demonstrates:

• Discovery & Normalization: Retrieves pipelines, stages, and products from Krayin CRM.
• Contact Verification: Checks if the contact person exists in CRM and creates it if not.
• Smart Lead Routing: Identifies existing open deals for the contact or creates a new lead.
• Stage Transition with Product Preservation: Moves the lead through stages (e.g. checkout to approved sale) while retaining existing products and attaching new offers.

📥 How to import in your n8n:

1. Download Krayin CRM pipeline.json.
2. In your n8n workflow canvas, open the top-right menu > Import from File...
3. Select the file and link your Krayin CRM credentials!

🚀 Also check out: Expertsa Groups

Managing WhatsApp groups for launches, cohorts, and student communities?

Check out Expertsa Groups — an advanced WhatsApp group management and automation platform built for digital operators to scale with peace of mind.

📲 Learn more at expertsa.com.br.

☕ Support the Project

This node is actively maintained to solve real operational bottlenecks. If it saved you development hours or streamlined your automations, consider supporting:

Pix key: expertsa.oficial@gmail.com

📄 License

Distributed under the MIT License. Built with ❤️ by Expertsa.