n8n-nodes-ayudala

Community node for n8n that integrates with Ayudala — a helpdesk and service management platform.

Related project: This node connects to the Ayudala External API (/api/ext/). When the backend API changes, this node must be updated accordingly.

Installation

Community Nodes (recommended)

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter n8n-nodes-ayudala and confirm.

Manual

cd ~/.n8n/nodes
npm install n8n-nodes-ayudala

Restart n8n after installation.

Credentials

| Field | Description | |-------|-------------| | Base URL | Your Ayudala instance URL (e.g. https://app.ayuda.la) | | API Key | Generated from Integrations > API Keys in Ayudala |

The credential test calls GET /api/ext/verify to validate the key.

Nodes

Ayudala

Regular node with 22 resources:

| Resource | Operations | |----------|-----------| | Activity Event | Get Many | | Search | Query (omnisearch) | | Ticket | Create, Get, Get Many, Update, Change Status, Assign | | Comment | Create, Get Many | | Work Log | Create, Get Many | | Wish | Create, Get Many, Approve, Reject | | Company | Get, Get Many | | Contract | Get, Get Many, Get Hours | | Exchange Rate | Get, Get Many, Get History, Update, Bulk Update | | Invoice | Get, Get Many, Add Line, Record Payment | | SLA | Get Policies, Get Ticket SLA | | KB Article | Create, Get, Get Categories, Get Many, Publish, Search, Unpublish, Update | | Resource | Get, Get Many, Get Expiring, Get Rentals | | Secret Vault | Create, Get, Get Many, Reveal, Revoke | | Monitoring | Send Alert, Resolve Alert | | Purchase Request | Create, Get, Get Many, Update, Submit, Approve, Reject | | Survey | Get, Get Many, Get Responses | | Calendar Event | Get Many, Create | | Conversation | Get Many, Create | | Quotation Request | Get, Get Quotations, Get Many | | User | Get Many | | Vendor | Create, Get, Get Many |

Ayudala Trigger

Webhook-based trigger that receives events from Ayudala:

• activity_event.created — Activity feed event recorded
• ticket.created — New ticket created
• ticket.updated — Ticket fields changed
• ticket.resolved — Ticket marked resolved
• ticket.closed — Ticket closed
• comment.added — Comment added to ticket
• sla.breached — SLA breach detected
• invoice.created — New invoice created
• invoice.paid — Invoice payment recorded
• meeting.created — Billable meeting created
• meeting.confirmed — Billable meeting confirmed (work logs created)
• meeting.reverted — Confirmed meeting reverted to draft
• purchase_request.created — Purchase request created
• purchase_request.submitted — Purchase request submitted for review
• purchase_request.approved — Purchase request approved
• purchase_request.rejected — Purchase request rejected
• tender.published — Quotation request published
• tender.closed — Quotation request closed
• tender.awarded — Quotation request awarded
• bid.submitted — Quotation submitted

The trigger automatically registers and deregisters webhooks in Ayudala when the workflow is activated/deactivated. Payloads are verified with HMAC-SHA256.

API Scopes

The API key needs the following scopes depending on which resources you use:

| Scope | Required for | |-------|-------------| | activity:read | Activity Event Get Many | | search:read | Search Query | | tickets:read | Ticket / Work Log Get operations | | tickets:write | Ticket / Wish Create/Update/Status | | comments:read | Comment Get Many | | comments:write | Comment Create | | worklogs:write | Work Log Create | | companies:read | Company operations | | contracts:read | Contract operations | | invoices:read | Invoice operations | | sla:read | SLA operations | | knowledge:read | KB Article Get, Get Many, Search, Get Categories | | knowledge:write | KB Article Create, Update, Publish, Unpublish | | resources:read | Resource operations (including rentals) | | monitoring:write | Monitoring operations | | purchase_requests:read | Purchase Request Get / Get Many | | purchase_requests:write | Purchase Request Create, Update, Submit, Approve, Reject | | tenders:read | Quotation Request Get / Get Many / Get Quotations | | surveys:read | Survey operations | | exchange_rates:read | Exchange Rate Get, Get Many, Get History | | exchange_rates:write | Exchange Rate Update, Bulk Update | | calendar:read | Calendar Get Many | | calendar:write | Calendar Create | | conversations:read | Conversation Get Many | | conversations:write | Conversation Create | | users:read | User Get Many | | vendors:read | Vendor Get, Get Many | | vendors:write | Vendor Create | | secrets:read | Secret Vault Get, Get Many, Reveal | | secrets:write | Secret Vault Create, Revoke | | webhooks:write | Trigger node (auto-registration) | | * | Full access (all scopes) |

Development

Prerequisites

• Node.js >= 18
• npm >= 9

Setup

git clone https://github.com/ayudala/n8n-nodes-ayudala.git
cd n8n-nodes-ayudala
npm install

Build

npm run build

Test

npm test

Lint & Format

npm run lint
npm run format

Local testing with n8n

# Build the node
npm run build

# Link the node globally
npm link

# Link into your n8n installation
cd ~/.n8n/nodes
npm link n8n-nodes-ayudala

# Restart n8n
n8n start

Watch mode (development)

npm run dev

This watches TypeScript files and recompiles on changes. Restart n8n to pick up the new build.

Project Structure

n8n-nodes-ayudala/
├── credentials/
│   └── AyudalaApi.credentials.ts    # API key + base URL credential
├── nodes/
│   └── Ayudala/
│       ├── Ayudala.node.ts           # Main node (router + handlers)
│       ├── AyudalaTrigger.node.ts    # Webhook trigger node
│       ├── GenericFunctions.ts       # Shared HTTP helpers
│       ├── ayudala.svg               # Node icon
│       ├── Ayudala.node.json         # Node metadata (codex)
│       ├── AyudalaTrigger.node.json  # Trigger metadata (codex)
│       └── descriptions/             # Resource UI descriptions
│           ├── TicketDescription.ts
│           ├── CompanyDescription.ts
│           └── ...
├── test/
│   └── nodes/
│       └── GenericFunctions.test.ts
├── package.json
├── tsconfig.json
├── jest.config.js
├── gulpfile.js                       # SVG icon copy to dist/
└── LICENSE

Publishing

# Bump version in package.json (semver)
npm version patch|minor|major

# Build + publish (prepublishOnly runs build automatically)
npm publish

Keeping in Sync with Ayudala Backend

This node mirrors the Ayudala External API. When the backend changes:

| Backend Change | Action Required | |---|---| | New /api/ext/ endpoint | Add operation in descriptions/ + handler in Ayudala.node.ts | | Modified endpoint (params/response) | Update matching description fields and handler | | Removed endpoint | Remove from descriptions, handler, and HANDLERS map | | New webhook event type | Add option to AyudalaTrigger.node.ts events list | | New API key scope | Update scopes table in this README |

License

MIT