n8n-nodes-flowcore

n8n community node for FlowCore, the travel ERP platform. It reads FlowCore records and runs FlowCore record actions from n8n workflows.

Business logic and authorization stay in FlowCore: every request runs as the FlowCore user who owns the API key, inside that user's client (tenant), with that user's permissions. The node only orchestrates.

• Installation
• Credentials
• Resources and operations
• Record actions
• Webhooks
• Example workflow
• Development
• Known limitations
• Publishing and n8n verification

Installation

Self-hosted n8n only (until the package is verified by n8n).

From npm (once published): In n8n, go to Settings → Community Nodes → Install and enter n8n-nodes-flowcore. See the n8n docs on installing community nodes.

Before publication, from a build of this repository:

npm ci
npm run build
npm pack                      # creates n8n-nodes-flowcore-<version>.tgz

Install the tarball into the n8n custom extensions folder (default ~/.n8n/custom, or the directory in N8N_CUSTOM_EXTENSIONS) and restart n8n:

cd ~/.n8n/custom
npm install /path/to/n8n-nodes-flowcore-0.1.0.tgz

With Docker, mount that folder into the container (/home/node/.n8n/custom).

Credentials

Create a credential of type FlowCore API:

| Field | Description | | ----------- | ------------------------------------------------------------------------- | | Environment | Production (default) or Staging. | | API Key | Personal API key of a FlowCore user. Stored encrypted by n8n as a secret. |

The environment selects a fixed API base URL. There is no free-text URL field and no fallback from one environment to the other:

| Environment | API base URL | | ----------- | ------------------------------------ | | Production | https://app.flowcore.cloud | | Staging | https://app-staging.flowcore.cloud |

Getting an API key: in FlowCore's API key management, a user creates their own key, or an administrator creates one for a user (permissions API_KEYS_MANAGE_OWN / ADMIN_USERS_API_KEYS). The key is shown only once. Production keys start with fc_live_, Staging keys with fc_test_. Use a dedicated technical user per customer integration and give it only the role permissions the workflow needs (for example FOLLOWUPS_ADD, OPERATIONSBOOKINGS_EDIT).

Testing: n8n's Test button calls GET /me/api-key in the selected environment. It reads only the key's metadata.

One credential per customer and environment. A key belongs to exactly one FlowCore client, so create separate credential entries, for example FlowCore – Customer A (Staging) and FlowCore – Customer A (Production). Build and test the workflow against the Staging credential, then switch the node to the Production credential. There is intentionally no tenant selector: the key alone determines the customer.

The key is sent in the x-api-key header. The node never logs it, and n8n never exports it with workflows.

Resources and operations

| Resource | FlowCore model | Operations | | --------- | -------------------- | --------------------------------------------------------------------------------- | | Booking | operationsbookings | Get, Get Many, Count, Get Actions, Preview Action, Execute Action | | Contact | contacts | Get, Get Many, Count, Create, Update | | Follow-Up | followups | Get, Get Many, Count, Create, Update, Get Actions, Preview Action, Execute Action | | Invoice | invoices | Get, Get Many, Count, Get Actions, Preview Action, Execute Action | | Travel | travels | Get, Get Many, Count |

• Get: GET /api/<model>/<id>. Returns the record.
• Get Many: GET /api/<model>/overview. Returns one item per record. Options:
  • Return All, or a Limit. Pages are read with skip/limit, at most 300 records per request.
  • Filters: Search Text (FlowCore's free-text search) and Where (JSON) (FlowCore criteria, e.g. {"status": "BOOKED", "createdAt": {">=": "2026-01-01T00:00:00Z"}}).
  • Sort By / Sort Direction, Fields, Populate Relations.
  • Unknown fields or invalid filters are rejected by FlowCore with HTTP 400 and are not ignored silently. ISO timestamps in filters need a timezone.
• Count: GET /api/<model>/count with the same filters. Returns { "count": n }.
• Create / Update (contacts and follow-ups only): POST /api/<model> and PUT /api/<model>/<id>. Only the fields you set are sent.
  • Follow-ups: text, description, due date, reminder, task type, assignee. On create, also teams and a related record. The related record is read first, so a follow-up can only be attached to a record the user may read. To complete or reopen a follow-up, use the complete / reopen actions.
  • Contacts: first name, last name, email, phone, mobile, prefix, plus Other Attributes (JSON) for further FlowCore fields. FlowCore validates them.

Bookings and invoices are deliberately read-only apart from record actions: FlowCore itself treats raw writes to them as unsafe because they bypass its business workflows.

Each output item is linked to the input item it came from. With Continue On Fail, a failed item returns { error, description, httpCode } and the remaining items still run.

Record actions

Record actions are FlowCore's business operations on a record, for example cancelling a booking, creating an invoice, issuing or sending an invoice, or completing a follow-up. FlowCore decides which actions a record offers, whether the user may run them, and what they do. The node does not re-implement any of this.

• Get Actions (GET /api/<model>/<id>/actions) lists the actions the record offers now to this user. Actions ruled out by the record's state or the user's permissions are absent.
• Preview Action (POST …/actions/<action>/preview) shows what the action would do, without side effects. It returns summary, notices, the accepted inputs and a fingerprint.
• Execute Action (POST …/actions/<action>) runs the action and returns the changed fields (data) and the actions available afterwards. It proceeds as follows:
  1. It checks the action list. If FlowCore no longer offers the action, the node fails without changing anything.
  2. For actions with a preview, it fetches a fresh preview and sends its fingerprint, as FlowCore requires.
  3. Actions that need an interactive FlowCore dialog (confirmation.mode = view) are refused.
  4. If you set Confirmed Preview Fingerprint (from an earlier Preview Action, e.g. after a human approval step via Send and Wait), the node sends that fingerprint instead. FlowCore then refuses with HTTP 409 if the preview has changed since the approval.

Action Name or ID is loaded from FlowCore for the resource and the Record ID entered in the node. When the record ID is an expression, set the action ID with an expression too (e.g. cancel). Action Inputs (JSON) is a flat object such as {"cancellationDate": "2026-10-01"}. Run Preview Action to see which inputs an action accepts.

Execute Action is never retried by the node. Do not enable Retry On Fail for it. If an AI agent uses the node as a tool, require human approval for that tool.

Webhooks

FlowCore can call a URL when records change. This MVP has no custom FlowCore trigger node: FlowCore has no API to register and remove webhooks, so n8n could not manage their lifecycle. Use the standard Webhook node instead.

1. Add a Webhook node, method POST. Use a long, random path, because FlowCore does not sign its requests.

2. Activate the workflow and copy the Production URL.

3. In FlowCore's settings, open the webhook configuration (stored as webhooks in the client settings; requires access to Settings). Add the URL and select the modules or system events:

   • Modules are model identities such as contacts, followups or travels, and fire on create, update and destroy.
   • The booking status events are BOOKING_CHANGED_STATUS_TO_BOOKED, …_REQUESTED and …_CANCELED.

4. FlowCore sends a JSON body like this:

   {
   	"model": "operationsbookings",
   	"action": "update",
   	"payload": [{ "id": "68c1a2b3c4d5e6f708192a3b" }],
   	"key": "…",
   	"secret": "…"
   }

   For a system event, action is the event name (e.g. BOOKING_CHANGED_STATUS_TO_CANCELED) and model is operationsbookings. payload contains only record IDs. Fetch the current record with a FlowCore Get node ({{ $json.body.payload[0].id }}) instead of trusting the webhook body.

Delivery details from FlowCore's implementation:

• Events are debounced for about 3 seconds per record.
• There are no retries; a failed delivery is only logged by FlowCore.
• There is no signature header.

Security note: for compatibility with older integrations, FlowCore currently puts the client's legacy shared API key into key and the client ID into secret. n8n stores webhook bodies in its execution data. Restrict access to these executions, or turn off saving successful executions for the workflow, until FlowCore removes these fields.

A FlowCore Trigger node is a possible future extension once FlowCore offers webhook registration, deregistration and signed deliveries.

Example workflow

examples/booking-cancelled-follow-up.json can be imported via Workflows → Import from File. It runs these steps:

1. Webhook receives BOOKING_CHANGED_STATUS_TO_CANCELED from FlowCore.
2. FlowCore → Booking → Get reads the current booking.
3. FlowCore → Follow-Up → Create creates a follow-up "Check cancellation fees" attached to the booking, due in two days.

After importing, select your own FlowCore credential in both FlowCore nodes. The example contains no credentials or customer data.

Development

Requirements: Node.js ≥ 22.12, npm.

npm ci
npm run dev          # starts n8n with this node hot-reloaded (http://localhost:5678)
npm run build        # n8n-node build → dist/
npm run lint         # n8n community-node lint rules
npm run format       # prettier
npm run typecheck    # TypeScript incl. tests
npm test             # fixture-based tests (no network)

Tests

• Fixture-based tests (test/*.test.ts, run by npm test and CI) do not need network or credentials. Their fixtures in test/fixtures.ts follow FlowCore's documented response shapes. They cover the environment mapping, credential and request construction, pagination, response mapping, record actions and error handling.
• Live tests (test/live/*.live.test.ts, npm run test:live) call a real FlowCore environment.
  • They are skipped unless they are configured explicitly.
  • They are read-only: they refuse any non-GET request, so they never change data, not even on Staging.
  • Use a test user's key:

FLOWCORE_LIVE_ENVIRONMENT=staging \
FLOWCORE_LIVE_API_KEY=fc_test_... \
FLOWCORE_LIVE_RESOURCE=booking \
FLOWCORE_LIVE_RECORD_ID=<booking id on staging> \
npm run test:live

There are no automated mutating tests against any environment. Test create, update and execute manually on Staging with test data.

Known limitations

• Five resources only (bookings, contacts, follow-ups, invoices, travels). Other FlowCore models can be read with n8n's HTTP Request node, using the FlowCore API credential.
• No create/update for bookings, invoices or travels. Booking creation through FlowCore's booking API (/api/v3/travel/legacy/book) is not part of the MVP.
• No delete operation.
• Field inputs are offered only for verified fields. Other fields use JSON with FlowCore's field names, and the node does not validate them.
• Updates cannot clear a field (empty inputs are not sent).
• Get Many uses offset pagination. Records written during a long "Return All" run can shift between pages. Each request returns at most 300 records.
• Action options can only be loaded for a fixed record ID.
• Actions that need an interactive FlowCore dialog (view mode) cannot run from n8n.
• The node can be used as an AI agent tool. Execute Action then runs without the confirmation step of FlowCore's MCP interface. Give agents the node only with n8n's human approval for tools enabled, or limit the tool to read operations.
• No FlowCore Trigger node (see Webhooks).
• FlowCore has no inbound rate limiting today. Keep batch sizes and concurrency moderate anyway.

Publishing and n8n verification

Not done yet. The process, when the package is ready:

1. Make the GitHub repository public. n8n verification requires a public repository whose URL matches repository.url in package.json.
2. Set up npm publishing from GitHub Actions with provenance (.github/workflows/publish.yml). Prefer npm Trusted Publishing (OIDC) over a stored token. n8n requires provenance for verification since 1 May 2026.
3. Run npm run release locally. It lints, builds, bumps the version, updates the changelog, tags and pushes. The tag triggers the publish workflow.
4. Check the published package with npx @n8n/scan-community-package n8n-nodes-flowcore.
5. Submit it in the n8n Creator Portal. Requirements include:
   • no runtime dependencies
   • MIT license
   • English UI
   • documentation
   • the technical and UX guidelines

License

MIT