n8n

Table of contents¶

• Introduction
• Installation
• Credentials
• Fideltour Node
• Contact
• Movement
• Loyalty
• Web Form
• Fideltour Trigger Node
• Use cases
• Create a contact and log a stay
• Automatic loyalty enrollment
• Newsletter subscription from a form
• Add points on check-out
• Look up a room's active booking
• Test workflow
• Resources

Introduction¶

n8n is a workflow automation platform (similar to Zapier or Make) that can run in the cloud or self-hosted. The n8n-nodes-fideltour package is Fideltour HotelDataHub's (HDH) official community node for n8n, and includes two nodes:

• Fideltour (action): manages contacts, movements (bookings/stays), loyalty and web forms against the HDH API v1. It can also be used as an n8n AI Agent tool (usableAsTool).
• Fideltour Trigger: starts workflows when events occur in HotelDataHub (contact created, movement updated, contact added to a segment, etc.) via REST hooks. The node subscribes and unsubscribes automatically when the workflow is activated/deactivated.

Unlike the Zapier app, which is an integration hosted by Zapier, the n8n node is an npm package the customer installs on their own n8n instance.

For a visual guide to installation, credentials and first workflows (including the webhook trigger), see n8n - Step by step guide.

Installation¶

The package is installed as a community node following the official n8n guide:

1. In n8n, go to Settings → Community Nodes → Install.
2. Enter the package name: n8n-nodes-fideltour.
3. Accept the community nodes warning and install.

Requirements:

• Node.js 20.15 or higher (on self-hosted installations).
• n8n with nodes API version 1 (n8n-workflow 2.x). Tested with the latest n8n release.
• To use the Fideltour Trigger node, the n8n instance must be reachable from the internet (HDH needs to be able to call the webhook URL).

Credentials¶

Create a credential of type Fideltour API with:

The node logs in automatically against POST /api/v1/login/ and stores the JWT token (sliding token, 24h lifetime) as the session token. When it expires, n8n transparently renews it by repeating the login; you don't need to manage tokens manually. Requests are authenticated with the Authorization: Token <jwt> header.

The credentials, along with the chain code (hotel_chain) and the hotel identifiers, are requested from hoteldatahub@fideltour.com.

Permissions: depending on the operations used, the ApiUser needs the contacts, movements or segments permissions. The credential test performs a GET /api/v1/entries/, so it requires the movements permission to validate.

Fideltour Node¶

Action node with four resources. Each operation maps to an HDH API v1 endpoint; the node's fields use the same names and values as the API (see the Contacts, Movements, Loyalty and Web Forms pages).

Contact¶

Get Many filters: email (exact, case-insensitive match) and external_object_id (contact's ID in the external system).

Additional Create/Update fields: first name, last name, phone numbers, date of birth, gender, document type and number, language (ISO 639-1), country (ISO 3166-1 alpha-2), address, postal code, province/town/zone (created if they don't exist), company data, tags (custom_tags, comma-separated), custom fields (custom_fields, JSON object), external_object_id, notes and subscription status.

The Source field offers HDH's standard sources (PMS, Booking Engine / Web, Newsletter Form, API, Zapier / Make / N8n, CRM, etc.). For contacts created from n8n, the usual values are API (21) or Zapier / Make / N8n (22).

Important: email is a unique field in Fideltour. If you try to create a contact with an existing email you'll get an error; for upsert-style flows, search first with Get Many filtering by email, or use the Web Form resource, which already does an upsert by email.

Movement¶

Required Create fields:

Additional Create/Update fields: occupancy (adults, children, juniors, babies), amounts (amount, amount_paid, currency, paid), room (room_number, room_type, contracted/upgraded types), meal plan (contracted/upgraded), agency, category, offer, package, rate, event type, booking_type, input_channel and original_input_channel (HDH's standard channels; for BE, PMS and WiFi type companies the server overrides it), status (status, sub_status), check-in/check-out completed flags, custom_fields, external_object_id, notes and url (usable in campaigns via [BOOKING_URL]).

Get by Room requires room_number, hotel and entrance, and is useful for kiosks, in-room apps or digital key systems that only know the room.

Get Many filters: contact, external_object_id, input_channel and localizer.

Important: a movement always belongs to a contact. Before creating a movement you need to obtain the contact's HDH ID (with Contact → Get Many filtering by email, or by chaining the output of Contact → Create).

Loyalty¶

Note: Add Points requires the point_type field (e.g. 0 for regular points); the endpoint rejects the request without it.

Web Form¶

A single operation, Submit (POST /contacts/web-form/), which creates or updates a contact (upsert by email) from a web form or a newsletter subscription. Unlike the other operations, this endpoint authenticates via the body: besides hotel_chain and email, it requires api_user (the ApiUser's username) or company_id.

The Source field distinguishes between Newsletter Form (6) and Contact Form (7). Additional fields include first name, last name, phone, language, country, visitor IP, tags and the GDPR consents (accept_terms, accept_commercial_communications, accept_personalized_commercial_communications).

Fideltour Trigger Node¶

Starts the workflow when HDH notifies an event. When the workflow is activated, the node registers the subscription at POST /api/v1/webhooks/zapier-webhooks-subscriptions/ (the same REST hooks used by the Zapier app) with the n8n webhook URL; when the workflow is deactivated, it removes it. Each ApiUser only sees and manages its own subscriptions.

The node outputs the webhook payload exactly as HDH sends it. The payloads for each event are documented on the Zapier page (they're the same): full contact or movement record plus hotel_chain on creation/update events, and reduced payloads on level, unsubscribe and segment events.

For contact and movement triggers to work, Fideltour must be configured to send its webhooks to the customer's generic HDH endpoints (same configuration as for Zapier).

Use cases¶

Create a contact and log a stay¶

Basic write flow: create (or locate) the contact and chain the movement creation, reusing the ID returned by the first node.

1. Fideltour node with resource Contact and operation Create. Fill in Email and, in Additional Fields, the guest's available data (name, surname, language, country).
2. Second Fideltour node with resource Movement and operation Create. In Contact ID, use the expression {{ $('Create Contact').first().json.id }} to link the stay to the contact from step 1, and fill in Hotel Chain, Hotel, Date, Entrance, Departure and Localizer.

This JSON can be pasted directly onto the n8n canvas:

{
  "name": "Fideltour - Create contact and stay",
  "nodes": [
    {
      "parameters": {},
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "name": "When clicking 'Execute workflow'"
    },
    {
      "parameters": {
        "resource": "contact",
        "operation": "create",
        "email": "guest@example.com",
        "source": 21,
        "additionalFields": {
          "name": "Ada",
          "surname": "Lovelace",
          "language": "en",
          "country": "GB"
        }
      },
      "type": "n8n-nodes-fideltour.fideltour",
      "typeVersion": 1,
      "position": [220, 0],
      "name": "Create Contact",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    },
    {
      "parameters": {
        "resource": "movement",
        "operation": "create",
        "hotelChain": "my-hotel-chain",
        "contact": "={{ $('Create Contact').first().json.id }}",
        "hotel": 1,
        "date": "={{ $now.toFormat(\"yyyy-MM-dd'T'HH:mm:ss\") }}",
        "entrance": "={{ $now.plus({ days: 7 }).toFormat('yyyy-MM-dd') }}",
        "departure": "={{ $now.plus({ days: 9 }).toFormat('yyyy-MM-dd') }}",
        "localizer": "BOOKING-12345",
        "additionalFields": {
          "roomNumber": "101",
          "adults": 2,
          "currency": "EUR",
          "amount": 250
        }
      },
      "type": "n8n-nodes-fideltour.fideltour",
      "typeVersion": 1,
      "position": [440, 0],
      "name": "Create Movement",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    }
  ],
  "connections": {
    "When clicking 'Execute workflow'": {
      "main": [[{ "node": "Create Contact", "type": "main", "index": 0 }]]
    },
    "Create Contact": {
      "main": [[{ "node": "Create Movement", "type": "main", "index": 0 }]]
    }
  }
}

Automatic loyalty enrollment¶

Use the Fideltour Trigger node with the Contact Created event (type 5) to start a workflow every time a contact is created in HotelDataHub, and chain the Loyalty → Sign In operation to enroll it in the loyalty program:

{
  "name": "Fideltour - Loyalty enrollment",
  "nodes": [
    {
      "parameters": { "event": 5 },
      "type": "n8n-nodes-fideltour.fideltourTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "name": "Fideltour Trigger",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    },
    {
      "parameters": {
        "resource": "loyalty",
        "operation": "signIn",
        "contactId": "={{ $json.id }}",
        "password": "ChangeMe-123",
        "sendWelcomeEmail": true
      },
      "type": "n8n-nodes-fideltour.fideltour",
      "typeVersion": 1,
      "position": [220, 0],
      "name": "Loyalty Sign In",
      "credentials": { "fideltourApi": { "name": "Fideltour API" } }
    }
  ],
  "connections": {
    "Fideltour Trigger": {
      "main": [[{ "node": "Loyalty Sign In", "type": "main", "index": 0 }]]
    }
  }
}

You can insert an IF node between the trigger and the sign-in to only enroll contacts that meet a condition (e.g. source or accepted consents).

Newsletter subscription from a form¶

Connect any lead source (n8n Form node, a Webhook from the hotel's website, Typeform, etc.) with the Web Form → Submit resource:

1. An input node with the form fields (email, name, consents…).
2. Fideltour node with resource Web Form, operation Submit, hotel_chain, the form's mapped Email, API User (or Company ID) and Source = Newsletter Form.
3. In Additional Fields, map the GDPR consents (accept_terms, accept_commercial_communications) and, if available, the visitor's IP.

Since it's an upsert by email, the same flow works for both new signups and updating existing contacts without checking first whether they exist.

Add points on check-out¶

Reward the stay when it ends, using the Movement Updated event (type 12):

1. Fideltour Trigger node with event Movement Updated.
2. IF node checking that the movement's check-out has been completed (e.g. {{ $json.is_checkout_realized }} is true).
3. Fideltour node with resource Loyalty, operation Add Points: Contact ID = {{ $json.contact }}, Points calculated from the stay's amount (e.g. {{ Math.floor($json.amount) }}), a descriptive Concept ("Points for stay {{ $json.localizer }}") and Point Type = 0.

Note: the Movement Updated event fires on every movement update, not just at check-out; the IF node is essential to avoid duplicating points. For more control, you can add a condition on sub_status (9 = Checked Out).

Look up a room's active booking¶

The Movement → Get by Room operation handles the typical case of a system that only knows the room number (room service chatbot, in-room tablet, digital key): given room_number, hotel and entrance, it returns that room's active booking along with its contact's data, which can be used elsewhere in the workflow to personalize the response or log consumption as new movements (booking_type 11 = Room service, for example).

Test workflow¶

The repository includes a workflow that exercises every node operation: test-workflows/fideltour-all-operations.json. To use it, import it into n8n and fill in the Config node with your own HDH account values (chain code, hotel ID, credentials) before running it.

Resources¶

• npm package: n8n-nodes-fideltour
• Repository: github.com/Fideltour/n8n
• HotelDataHub API documentation
• n8n community nodes documentation
• Zapier page: webhook payloads and generic endpoint configuration, shared with n8n