n8n

Tabla de contenidos¶

• Introducción
• Instalación
• Credenciales
• Nodo Fideltour
• Contact
• Movement
• Loyalty
• Web Form
• Nodo Fideltour Trigger
• Casos de uso
• Crear un contacto y registrar una estancia
• Alta automática en el programa loyalty
• Suscripción a newsletter desde un formulario
• Sumar puntos al hacer check-out
• Consultar la reserva activa de una habitación
• Workflow de prueba
• Recursos

Introducción¶

n8n es una plataforma de automatización de workflows (similar a Zapier o Make) que puede ejecutarse en la nube o self-hosted. El paquete n8n-nodes-fideltour es el community node oficial de Fideltour HotelDataHub (HDH) para n8n, e incluye dos nodos:

• Fideltour (acción): gestiona contactos, movimientos (reservas/estancias), loyalty y formularios web contra la API v1 de HDH. Puede usarse también como herramienta de un AI Agent de n8n (usableAsTool).
• Fideltour Trigger: arranca workflows cuando ocurren eventos en HotelDataHub (contacto creado, movimiento actualizado, contacto añadido a segmento, etc.) mediante REST hooks. El nodo da de alta y de baja la suscripción automáticamente al activar/desactivar el workflow.

A diferencia de la app de Zapier, que es una integración alojada por Zapier, el nodo de n8n es un paquete npm que el cliente instala en su propia instancia de n8n.

Instalación¶

El paquete se instala como community node siguiendo la guía oficial de n8n:

1. En n8n, ir a Settings → Community Nodes → Install.
2. Introducir el nombre del paquete: n8n-nodes-fideltour.
3. Aceptar el aviso de nodos de la comunidad e instalar.

Requisitos:

• Node.js 20.15 o superior (en instalaciones self-hosted).
• n8n con nodes API versión 1 (n8n-workflow 2.x). Probado con la última release de n8n.
• Para usar el nodo Fideltour Trigger, la instancia de n8n debe ser accesible desde internet (HDH necesita poder llamar a la URL del webhook).

Credenciales¶

Crear una credencial de tipo Fideltour API con:

El nodo hace login automáticamente contra POST /api/v1/login/ y guarda el token JWT (sliding token, 24 h de vida) como token de sesión. Cuando caduca, n8n lo renueva de forma transparente repitiendo el login; no es necesario gestionar tokens manualmente. Las peticiones se autentican con la cabecera Authorization: Token <jwt>.

Las credenciales, junto con el código de cadena (hotel_chain) y los identificadores de hotel, se solicitan a hoteldatahub@fideltour.com.

Permisos: según las operaciones que se usen, el ApiUser necesita los permisos contacts, movements o segments. El test de la credencial hace un GET /api/v1/entries/, por lo que requiere el permiso movements para validar.

Nodo Fideltour¶

Nodo de acción con cuatro recursos. Cada operación se corresponde con un endpoint de la API v1 de HDH; los campos del nodo usan los mismos nombres y valores que la API (ver las páginas Contactos, Movimientos, Loyalty y Formularios web).

Contact¶

Filtros de Get Many: email (búsqueda exacta, insensible a mayúsculas) y external_object_id (ID del contacto en el sistema externo).

Campos adicionales de Create/Update: nombre, apellidos, teléfonos, fecha de nacimiento, género, tipo y número de documento, idioma (ISO 639-1), país (ISO 3166-1 alpha-2), dirección, código postal, provincia/ciudad/zona (se crean si no existen), datos de empresa, etiquetas (custom_tags, separadas por comas), campos personalizados (custom_fields, objeto JSON), external_object_id, notas y estado de suscripción.

El campo Source ofrece los orígenes estándar de HDH (PMS, Booking Engine / Web, Formulario Newsletter, API, Zapier / Make / N8n, CRM, etc.). Para contactos creados desde n8n, los valores habituales son API (21) o Zapier / Make / N8n (22).

Importante: el email es campo único en Fideltour. Si se intenta crear un contacto con un email existente se recibe un error; para flujos de tipo upsert, buscar primero con Get Many filtrando por email, o usar el recurso Web Form, que ya hace upsert por email.

Movement¶

Campos obligatorios de Create:

Campos adicionales de Create/Update: ocupación (adultos, niños, juniors, bebés), importes (amount, amount_paid, currency, paid), habitación (room_number, room_type, tipos contratado/upgrade), régimen (contratado/upgrade), agencia, categoría, oferta, paquete, tarifa, tipo de evento, booking_type, input_channel y original_input_channel (canales estándar de HDH; para companies de tipo BE, PMS y WiFi el servidor lo sobreescribe), estado (status, sub_status), flags de check-in/check-out realizados, custom_fields, external_object_id, notas y url (usable en campañas mediante [BOOKING_URL]).

Get by Room requiere room_number, hotel y entrance, y es útil para quioscos, apps de habitación o sistemas de llave digital que solo conocen la habitación.

Filtros de Get Many: contact, external_object_id, input_channel y localizer.

Importante: un movimiento siempre pertenece a un contacto. Antes de crear un movimiento hay que obtener el ID del contacto en HDH (con Contact → Get Many filtrando por email, o encadenando la salida de Contact → Create).

Loyalty¶

Nota: Add Points exige el campo point_type (p. ej. 0 para puntos regulares); el endpoint rechaza la petición sin él.

Web Form¶

Una única operación, Submit (POST /contacts/web-form/), que crea o actualiza un contacto (upsert por email) desde un formulario web o una suscripción a newsletter. A diferencia del resto de operaciones, este endpoint se autentica por el body: además de hotel_chain y email, requiere api_user (username del ApiUser) o company_id.

El campo Source distingue entre Formulario Newsletter (6) y Formulario de contacto (7). Los campos adicionales incluyen nombre, apellidos, teléfono, idioma, país, IP del visitante, etiquetas y los consentimientos RGPD (accept_terms, accept_commercial_communications, accept_personalized_commercial_communications).

Nodo Fideltour Trigger¶

Arranca el workflow cuando HDH notifica un evento. Al activar el workflow, el nodo registra la suscripción en POST /api/v1/webhooks/zapier-webhooks-subscriptions/ (los mismos REST hooks que usa la app de Zapier) con la URL del webhook de n8n; al desactivar el workflow, la elimina. Cada ApiUser solo ve y gestiona sus propias suscripciones.

El nodo entrega en la salida el payload del webhook tal cual lo envía HDH. Los payloads por evento están documentados en la página de Zapier (son los mismos): ficha completa del contacto o movimiento más hotel_chain en los eventos de creación/actualización, y payloads reducidos en los eventos de nivel, desuscripción y segmentos.

Para que los triggers de contactos y movimientos funcionen, Fideltour debe estar configurado para enviar sus webhooks a los endpoints genéricos de HDH del cliente (misma configuración que para Zapier).

Casos de uso¶

Crear un contacto y registrar una estancia¶

Flujo básico de escritura: crear (o localizar) el contacto y encadenar la creación del movimiento reutilizando el ID que devuelve el primer nodo.

1. Nodo Fideltour con recurso Contact y operación Create. Rellenar Email y, en Additional Fields, los datos disponibles del huésped (nombre, apellidos, idioma, país).
2. Segundo nodo Fideltour con recurso Movement y operación Create. En Contact ID usar la expresión {{ $('Create Contact').first().json.id }} para vincular la estancia al contacto del paso 1, y rellenar Hotel Chain, Hotel, Date, Entrance, Departure y Localizer.

Este JSON puede pegarse directamente en el lienzo de n8n:

{
  "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 }]]
    }
  }
}

Alta automática en el programa loyalty¶

Usar el nodo Fideltour Trigger con el evento Contact Created (tipo 5) para arrancar un workflow cada vez que se crea un contacto en HotelDataHub, y encadenar la operación Loyalty → Sign In para inscribirlo en el programa de fidelización:

{
  "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 }]]
    }
  }
}

Entre el trigger y el sign-in se puede intercalar un nodo IF para inscribir solo a contactos que cumplan una condición (p. ej. source o consentimientos aceptados).

Suscripción a newsletter desde un formulario¶

Conectar cualquier fuente de leads (nodo n8n Form, un Webhook de la web del hotel, Typeform, etc.) con el recurso Web Form → Submit:

1. Nodo de entrada con los campos del formulario (email, nombre, consentimientos…).
2. Nodo Fideltour con recurso Web Form, operación Submit, hotel_chain, el Email mapeado del formulario, API User (o Company ID) y Source = Newsletter Form.
3. En Additional Fields, mapear los consentimientos RGPD (accept_terms, accept_commercial_communications) y, si se dispone de ella, la IP del visitante.

Al ser un upsert por email, el mismo flujo sirve para altas nuevas y para actualizar contactos existentes sin comprobar antes si existen.

Sumar puntos al hacer check-out¶

Recompensar la estancia al finalizarla, usando el evento Movement Updated (tipo 12):

1. Nodo Fideltour Trigger con evento Movement Updated.
2. Nodo IF que compruebe que el movimiento ha pasado a check-out realizado (p. ej. {{ $json.is_checkout_realized }} es true).
3. Nodo Fideltour con recurso Loyalty, operación Add Points: Contact ID = {{ $json.contact }}, Points calculados a partir del importe de la estancia (p. ej. {{ Math.floor($json.amount) }}), un Concept descriptivo ("Puntos por estancia {{ $json.localizer }}") y Point Type = 0.

Observación: el evento Movement Updated se dispara con cada actualización del movimiento, no solo en el check-out; el nodo IF es imprescindible para no duplicar puntos. Para más control se puede añadir una condición sobre sub_status (9 = Checked Out).

Consultar la reserva activa de una habitación¶

La operación Movement → Get by Room resuelve el caso típico de un sistema que solo conoce el número de habitación (chatbot de room service, tablet en habitación, llave digital): con room_number, hotel y entrance devuelve la reserva activa de esa habitación junto con los datos de su contacto, que se pueden usar en el resto del workflow para personalizar la respuesta o registrar consumos como nuevos movimientos (booking_type 11 = Room service, por ejemplo).

Workflow de prueba¶

El repositorio incluye un workflow que ejercita todas las operaciones del nodo: test-workflows/fideltour-all-operations.json. Para usarlo, importarlo en n8n y rellenar el nodo Config con los valores de la cuenta HDH propia (código de cadena, ID de hotel, credenciales) antes de ejecutarlo.

Recursos¶

• Paquete npm: n8n-nodes-fideltour
• Repositorio: github.com/Fideltour/n8n
• Documentación de la API de HotelDataHub
• Documentación de community nodes de n8n
• Página de Zapier: payloads de los webhooks y configuración de los endpoints genéricos, compartidos con n8n