n8n-nodes-aplikacja-ofertowania

Community node dla n8n umożliwiający tworzenie ofert w Aplikacji do Ofertowania.

Spis treści

• Instalacja
• Konfiguracja credentiala
• Operacje
• Przykładowy workflow
• Mapowanie pól formularza
• Rozwiązywanie problemów

Instalacja

Self-hosted n8n (zalecane)

Opcja 1: Przez UI (n8n >= 0.199.0)

1. Otwórz Settings → Community Nodes
2. Kliknij Install a community node
3. Wpisz: n8n-nodes-aplikacja-ofertowania
4. Kliknij Install

Opcja 2: Z linii poleceń

# W katalogu ~/.n8n (lub N8N_USER_FOLDER)
cd ~/.n8n
npm install n8n-nodes-aplikacja-ofertowania

Zrestartuj n8n po instalacji.

Opcja 3: Instalacja lokalna (development)

# Sklonuj repo
cd /ścieżka/do/aplikacja-do-ofertowania/n8n-nodes-aplikacja-ofertowania

# Zainstaluj zależności i zbuduj
npm install
npm run build

# Skopiuj lub zlinkuj do katalogu n8n
# Linux/Mac:
ln -s $(pwd) ~/.n8n/custom/n8n-nodes-aplikacja-ofertowania

# Lub zamontuj przez Docker:
# docker run -v $(pwd):/home/node/.n8n/custom/n8n-nodes-aplikacja-ofertowania n8nio/n8n

n8n Cloud

Community nodes nie są dostępne w n8n Cloud. Użyj self-hosted n8n.

Konfiguracja credentiala

1. Wygeneruj klucz API

1. Zaloguj się do panelu admina swojego tenanta
2. Przejdź do Ustawienia → Klucze API (/admin/api-keys)
3. Kliknij Utwórz nowy klucz
4. Podaj nazwę (np. "n8n integration")
5. Upewnij się, że klucz ma scope: offers:write i offers:read
6. Skopiuj klucz — zobaczysz go tylko raz!

2. Utwórz credential w n8n

1. W n8n otwórz Credentials → Add Credential
2. Wybierz Aplikacja do Ofertowania API
3. Wypełnij pola:
   • Base URL: Pełny URL twojego tenanta, np. https://twoj-slug.systemofert.kijowski.com.pl
   • API Key: Klucz skopiowany w kroku 1 (format: ofr_...)
4. Kliknij Save

n8n automatycznie zweryfikuje połączenie przez wywołanie GET /api/templates.

Operacje

Offer → Create

Tworzy nową ofertę na podstawie szablonu.

| Pole | Typ | Wymagane | Opis | |------|-----|----------|------| | Template | dropdown | ✅ | Szablon oferty do użycia | | Recipient Name | string | ❌ | Imię i nazwisko odbiorcy | | Recipient Email | string | ❌ | Email odbiorcy (wymagany jeśli Send Email = true) | | Title | string | ❌ | Tytuł oferty (obsługuje Mustache placeholdery) | | Use JSON Mode | boolean | ❌ | Przełącz na tryb JSON dla wartości | | Values | key-value / JSON | ❌ | Wartości placeholderów szablonu | | Send Email | boolean | ❌ | Czy wysłać email do odbiorcy |

Additional Fields:

| Pole | Opis | |------|------| | CTA Type | none, accept, lub calendly | | Calendly URL | URL do Calendly (gdy CTA = calendly) | | Logo URL | URL logo do wyświetlenia na ofercie | | Mail Template ID | UUID szablonu maila | | Nav Button Bg | Kolor tła przycisku nawigacji | | Nav Button Accent | Kolor akcentu przycisku | | Image Replacements | Zamiany URL obrazów | | Font Replacements | Zamiany URL fontów |

Output:

{
  "success": true,
  "offerId": "uuid-oferty",
  "token": "abc123xyz",
  "status": "cold",
  "url": "https://tenant.example.com/o/abc123xyz",
  "emailQueued": true
}

Przykładowy workflow

Webhook → Create Offer → Respond

Typowy przypadek: formularz na stronie wysyła dane przez webhook, n8n tworzy ofertę.

┌─────────────┐     ┌──────────────────────────┐     ┌─────────────────┐
│   Webhook   │────▶│ Aplikacja do Ofertowania │────▶│ Respond Webhook │
│   (trigger) │     │     (Create Offer)       │     │                 │
└─────────────┘     └──────────────────────────┘     └─────────────────┘

Konfiguracja Webhook node:

• HTTP Method: POST
• Path: /create-offer
• Response Mode: Last Node

Konfiguracja Aplikacja do Ofertowania node:

• Template: Wybierz z listy
• Recipient Name: {{ $json.body.name }}
• Recipient Email: {{ $json.body.email }}
• Title: Oferta dla {{ $json.body.name }}
• Use JSON Mode: ✅ ON
• Values (JSON): {{ JSON.stringify($json.body) }}
• Send Email: ✅ ON

Konfiguracja Respond to Webhook node:

{
  "success": true,
  "offerUrl": "{{ $json.url }}"
}

Workflow JSON (do importu)

{
  "name": "Create Offer from Form",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "create-offer",
        "responseMode": "lastNode"
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300]
    },
    {
      "parameters": {
        "resource": "offer",
        "operation": "create",
        "templateId": "={{ $json.body.templateId }}",
        "recipientName": "={{ $json.body.name }}",
        "recipientEmail": "={{ $json.body.email }}",
        "title": "Oferta dla {{ $json.body.name }}",
        "useJsonMode": true,
        "valuesJson": "={{ JSON.stringify($json.body.values || {}) }}",
        "sendEmail": true
      },
      "name": "Create Offer",
      "type": "n8n-nodes-aplikacja-ofertowania.aplikacjaOfertowania",
      "position": [500, 300],
      "credentials": {
        "aplikacjaOfertowaniaApi": {
          "id": "your-credential-id",
          "name": "Aplikacja do Ofertowania API"
        }
      }
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={{ { success: true, offerUrl: $json.url } }}"
      },
      "name": "Respond",
      "type": "n8n-nodes-base.respondToWebhook",
      "position": [750, 300]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{ "node": "Create Offer", "type": "main", "index": 0 }]]
    },
    "Create Offer": {
      "main": [[{ "node": "Respond", "type": "main", "index": 0 }]]
    }
  }
}

Mapowanie pól formularza

Jeśli twój szablon używa placeholderów Mustache:

<p>Szanowny/a {{imie}} {{nazwisko}},</p>
<p>Przygotowaliśmy dla Ciebie ofertę o wartości {{cena}} PLN.</p>

To webhook z formularza powinien wysłać:

{
  "name": "Jan Kowalski",
  "email": "[email protected]",
  "values": {
    "imie": "Jan",
    "nazwisko": "Kowalski",
    "cena": "5000"
  }
}

A w node Values (JSON): {{ JSON.stringify($json.body.values) }}

Rozwiązywanie problemów

"Nieprawidłowy klucz API"

• Sprawdź czy klucz zaczyna się od ofr_
• Upewnij się, że Base URL jest poprawny (bez końcowego /)
• Wygeneruj nowy klucz w panelu admina

"Klucz API nie ma uprawnień offers:read"

Wygeneruj nowy klucz z scopami: offers:read, offers:write

"Nie znaleziono szablonu"

• Sprawdź czy szablon istnieje w panelu admina
• Upewnij się, że klucz API należy do tego samego tenanta

Dropdown "Template" jest pusty

• Sprawdź połączenie z API (credential test)
• Upewnij się, że tenant ma co najmniej jeden szablon

Email nie został wysłany

• Sprawdź czy Recipient Email jest wypełniony
• Sprawdź konfigurację SMTP w panelu admina (/admin/settings/smtp)
• Sprawdź czy Send Email = true

Development

cd n8n-nodes-aplikacja-ofertowania

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Lint
npm run lint

# Format
npm run format

Licencja

MIT