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": "jan@example.com",
  "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