n8n-nodes-lktippnodes 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Helixify
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,455 @@
1
- # Temporary Holding Version
1
+ # n8n-nodes-lktippnodes
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ n8n-Nodes für das Empfehlungsportal **LK-Tippgeber**: Empfehlungen, Prämien und Tippgeber aus n8n
4
+ heraus verwalten und Workflows starten, sobald im Portal etwas passiert.
5
+
6
+ Das Paket ist für selbst gehostetes n8n gedacht und gehört zu einem LK-Tippgeber-Portal: Die Adresse des
7
+ Portals und einen API-Schlüssel tragen Sie in den Zugangsdaten ein.
8
+ Stand: Version 0.2.0. Wer schon Workflows mit 0.1.0 gebaut hat, liest zuerst
9
+ [Umstieg von 0.1.0](#umstieg-von-010).
10
+
11
+ ## Voraussetzungen
12
+
13
+ - **Selbst gehostetes n8n.** Gebaut gegen `n8n-workflow` 2.48 (n8n 2.48). Ältere
14
+ 1.x-Versionen sind nicht geprüft.
15
+ - **n8n ist aus dem Internet per https erreichbar und kennt seine eigene Adresse.** Der Trigger meldet
16
+ im Portal die Adresse an, die n8n für sich selbst hält. Läuft n8n in Docker hinter einem Proxy, muss
17
+ dafür `WEBHOOK_URL=https://n8n.example.com/` gesetzt sein – sonst meldet n8n
18
+ `http://localhost:5678/…` an, und das Portal lehnt das beim Aktivieren ab (es nimmt nur
19
+ https-Adressen zu öffentlichen Zielen an).
20
+ - **Das Portal ist per https erreichbar**, und es gibt einen API-Schlüssel
21
+ (Admin → Schnittstellen → API-Schlüssel).
22
+
23
+ ## Was drin ist
24
+
25
+ | Baustein | Zweck |
26
+ | ------------------------ | --------------------------------------------------------- |
27
+ | **LK-Tippgeber API** | Zugangsdaten: Adresse des Portals und API-Schlüssel |
28
+ | **LK-Tippgeber** | Action-Node: Daten ins Portal schreiben oder daraus lesen |
29
+ | **LK-Tippgeber Trigger** | Startet einen Workflow bei Ereignissen im Portal |
30
+
31
+ ## Action-Node „LK-Tippgeber“
32
+
33
+ | Resource | Operation | Wofür |
34
+ | ------------ | ----------------------- | --------------------------------------------------------------------------------------------------------- |
35
+ | **Reward** | Issue | Prämie vergeben, z. B. wenn in Close eine Opportunity gewonnen wurde |
36
+ | **Reward** | Mark as Paid | Prämie als ausgezahlt markieren |
37
+ | **Referral** | Update | Status ändern, Close-Lead-ID speichern, Auftragswert oder Notizen setzen, Felder leeren |
38
+ | **Referral** | Create | Empfehlung für einen Tippgeber anlegen; gibt es sie bei ihm schon, kommt sie mit `created: false` zurück |
39
+ | **Referral** | Get / Get Many | Empfehlungen lesen und filtern (auch nach Auszahlungsstatus) |
40
+ | **Referrer** | Create | Tippgeber anlegen – siehe [Tippgeber anlegen](#tippgeber-anlegen-created-und-der-passwort-link) |
41
+ | **Referrer** | Approve | Wartenden Tippgeber freischalten – nur wartende, siehe [Freischalten](#freischalten-und-reaktivieren) |
42
+ | **Referrer** | Get / Get Many / Update | Tippgeber lesen, Provisionssatz oder Stammdaten ändern, deaktivieren oder bewusst reaktivieren |
43
+ | **Status** | Get Many | Alle Status mit ihren Schlüsseln |
44
+
45
+ ### Die Empfehlung finden
46
+
47
+ „Update“, „Issue“ und „Mark as Paid“ finden die Empfehlung über eines von drei Merkmalen
48
+ (**Find Referral By**). In dieser Reihenfolge sind sie zu empfehlen:
49
+
50
+ 1. **Referral ID** – die ID aus dem Portal, z. B. `{{ $json.referral.id }}` aus dem Trigger. Meint
51
+ immer genau eine Empfehlung.
52
+ 2. **Close Lead ID** – die Close-ID, die als „External ID“ an der Empfehlung gespeichert ist. Der
53
+ normale Weg für alles, was aus Close kommt.
54
+ 3. **Lead Email** – das schwächste Merkmal: Kontakte ohne E-Mail-Adresse werden nicht gefunden, und
55
+ bei mehreren laufenden Empfehlungen zur selben Adresse antwortet das Portal mit einem Fehler.
56
+
57
+ Ein leerer Suchwert (der Ausdruck liefert nichts) ist immer ein Fehler, nie „nicht gefunden“.
58
+
59
+ ### Wenn es keine Empfehlung gibt
60
+
61
+ Die meisten Kontakte in Close sind keine Empfehlungen. Dafür gibt es an „Update“, „Issue“ und
62
+ „Mark as Paid“ die Auswahl **If Referral Is Not Found**:
63
+
64
+ - **Stop With an Error** (Vorgabe) – der Node bricht ab wie bei jedem anderen Problem.
65
+ - **Return Nothing** – das Element entfällt, die folgenden Nodes laufen dafür nicht. Das ist die
66
+ richtige Einstellung für Abläufe, die bei jedem Close-Ereignis starten.
67
+
68
+ „Return Nothing“ greift **nur**, wenn das Portal ausdrücklich antwortet „zu diesen Angaben gibt es keine
69
+ Empfehlung“ (Fehlercode `referral_not_found`). Alles andere bleibt ein Fehler und macht die Ausführung
70
+ rot: mehrere passende Empfehlungen, eine schon ausgezahlte Prämie, ein Auftragswert von 0, ein
71
+ widerrufener Schlüssel, ein Ausfall des Portals. So fällt keine Prämie still aus.
72
+
73
+ ### Fehler
74
+
75
+ Schlägt ein Aufruf fehl, bricht der Node ab. Die Überschrift des Fehlers ist die Meldung des Portals,
76
+ in der Beschreibung darunter stehen Fehlercode, HTTP-Status und – wenn das Portal sie liefert – die
77
+ betroffenen IDs. Das ist der richtige Normalfall: Ein roter Lauf fällt auf, und ein Fehler-Workflow
78
+ kann benachrichtigen.
79
+
80
+ Wer Fehler im Workflow selbst behandeln will, stellt den Node unter Settings → **On Error** auf
81
+ „Continue (using error output)“. Jedes gescheiterte Element kommt dann am Fehler-Ausgang an, mit:
82
+
83
+ | Feld | Inhalt |
84
+ | --------- | --------------------------------------------------------------------------------------------------------- |
85
+ | `error` | Die Meldung als Text. Zum Anzeigen, **nicht** zum Verzweigen. |
86
+ | `code` | Fehlercode des Portals, z. B. `referral_not_found`. `null`, wenn das Portal gar nicht geantwortet hat. |
87
+ | `status` | HTTP-Status der Antwort (404, 409, 422, 500 …) oder `null`. |
88
+ | `details` | Zusatzangaben des Portals, z. B. `{ "referral_ids": ["…", "…"] }`, oder `null`. |
89
+
90
+ n8n ergänzt am Fehler-Ausgang die Eingabedaten des Elements; die vier Felder oben setzt immer der
91
+ Node. Mit „Continue“ (ohne eigenen Fehler-Ausgang) fehlen die Eingabedaten – dort hilft
92
+ `{{ $('Name des vorherigen Nodes').item.json }}`.
93
+
94
+ **Nicht pauschal auf „`error` vorhanden“ verzweigen** – dann sieht ein Ausfall des Portals genauso aus
95
+ wie „kein Tippgeber-Kontakt“. Wenn überhaupt, dann so: hinter dem Fehler-Ausgang ein IF mit
96
+ `{{ $json.code }}` **ist gleich** `referral_not_found` → Ende; der andere Zweig führt in einen Node
97
+ „Stop and Error“ (Meldung `{{ $json.error }}`) oder in eine Benachrichtigung an das Team. Auch `status`
98
+ allein reicht nicht: Ein 404 ohne `code` heißt, dass unter der Adresse gar nicht das Portal antwortet.
99
+ Für den häufigsten Fall braucht es das alles nicht – dafür gibt es „If Referral Is Not Found“.
100
+
101
+ Die wichtigsten Codes:
102
+
103
+ | `code` | Status | Bedeutung |
104
+ | --------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
105
+ | `referral_not_found` | 404 | Zu den Angaben gibt es keine Empfehlung. |
106
+ | `referral_conflict` | 409 | Die Close-ID hängt an einer alten, nicht zustande gekommenen Empfehlung, und zum selben Kontakt gibt es eine laufende eines anderen Tippgebers. `details` nennt beide. |
107
+ | `ambiguous_referral` | 409 | Mehrere laufende Empfehlungen passen. `details.referral_ids` nennt sie. |
108
+ | `external_id_conflict`, `duplicate_referral` | 409 | Die Close-ID oder der Kontakt gehört schon zu einer anderen Empfehlung. |
109
+ | `opportunity_conflict`, `opportunity_required`| 409 | Es gibt schon eine Prämie für einen anderen Auftrag – sie wird nicht überschrieben. |
110
+ | `paid_locked` | 409 | Die Prämie ist ausgezahlt und gesperrt. |
111
+ | `reward_is_zero`, `reward_basis_missing` | 422 | Es ergäbe sich keine Prämie, oder eine vorhandene entfiele. |
112
+ | `deal_value_implausible` | 422 | Auftragswert über 50.000 € – fast immer Cent im Euro-Feld. |
113
+ | `validation_error`, `invalid_value` | 422 | Ein Feld ist ungültig, z. B. ein leerer Status oder ein Satz mit mehr als vier Nachkommastellen. |
114
+ | `unauthorized` | 401 | Der API-Schlüssel ist falsch oder widerrufen. |
115
+ | `referrer_not_pending` | – / 409| „Approve“ für ein Konto, das nicht (mehr) auf Freischaltung wartet. Vom Node vorab geprüft; vom Portal, wenn zwischendurch jemand abgelehnt hat. |
116
+ | `invalid_input`, `invalid_credentials` | – | Vom Node selbst abgelehnt, bevor etwas gesendet wurde (leerer Suchwert, 0 als Betrag, Adresse des Portals ohne https). |
117
+
118
+ ### Euro oder Cent
119
+
120
+ Close liefert den Wert einer Opportunity **in Cent** (149000 = 1.490,00 €). Mit der falschen Einheit
121
+ wird die Prämie hundertmal zu hoch oder zu niedrig.
122
+
123
+ - **Reward → Issue** fragt die Einheit mit der ersten Auswahl ab: **Reward Basis** = „Deal Value in
124
+ Cents“ (Vorgabe, passend zu Close), „Deal Value in Euros“ oder „Fixed Amount“ (Euro).
125
+ - **Referral → Update** kennt beim Feld „Deal Value“ nur Euro. Kommt der Wert aus Close, im Ausdruck
126
+ durch 100 teilen: `{{ $json.value / 100 }}`.
127
+ - Das Portal weist Auftragswerte über 50.000 € zurück (`deal_value_implausible`). Stimmt der Betrag
128
+ wirklich, das Zusatzfeld **Confirm Deal Value** hinzufügen.
129
+
130
+ Alle Beträge in den Antworten und Ereignissen des Portals sind Euro.
131
+
132
+ ### Leere Felder, Felder leeren und der Wert 0
133
+
134
+ Für „Referral → Update“ und „Referrer → Update“ gilt:
135
+
136
+ - **Nur Felder mit einem Wert werden gesendet.** Ein hinzugefügtes, aber leeres Feld (oder ein
137
+ Ausdruck, der nichts liefert) ändert nichts – es löscht weder einen Text noch eine Prämie. Zahlenfelder
138
+ sind ohne Vorgabe; „nicht ausgefüllt“ ist nie 0.
139
+ - **Ausnahme Status:** Ein leerer Status geht ans Portal und wird dort abgelehnt (422). Wer Close-Status
140
+ per Ausdruck auf Portal-Status abbildet, merkt so, wenn eine Zuordnung fehlt, statt einen grünen Lauf
141
+ ohne Wirkung zu bekommen.
142
+ - **Leeren geht nur über „Fields to Clear“** – dort die Felder ankreuzen, deren gespeicherter Wert
143
+ entfernt werden soll (Telefon, Notiz, Firma, eigener Provisionssatz, Auftragswert …).
144
+ - **0 als Auftragswert oder feste Prämie lehnt der Node ab**, weil damit eine schon vergebene Prämie
145
+ entfiele. Ist genau das gewollt (oder soll der Auftragswert geleert werden, obwohl es eine Prämie
146
+ gibt), zusätzlich **Allow Removing the Reward** hinzufügen. Ohne diese Bestätigung lehnt auch das
147
+ Portal ab (`reward_is_zero`).
148
+ - Bleibt nach alledem nichts zu senden, sagt der Node das („Nothing to update: … is empty“), statt einen
149
+ leeren Aufruf zu schicken.
150
+
151
+ ### Tippgeber anlegen: `created` und der Passwort-Link
152
+
153
+ „Referrer → Create“ gibt den Tippgeber zurück, dazu `created` und `set_password_url`:
154
+
155
+ - **`created: true`** – neu angelegt. `set_password_url` ist der Einmal-Link, über den der Tippgeber
156
+ sein Passwort setzt.
157
+ - **`created: false`** – zu der E-Mail-Adresse gab es schon einen Tippgeber. Er kommt **unverändert**
158
+ zurück; mitgeschickte Angaben (Name, Firma, Provisionssatz) werden nicht übernommen – dafür ist
159
+ „Referrer → Update“ da.
160
+ - **`set_password_url`** gibt es nur, solange das Konto aktiv ist und noch kein Passwort hat. Sonst ist
161
+ das Feld `null` (warum, steht in `has_password` und `status`). Jeder neue Link entwertet den
162
+ vorherigen: Verschickt wird immer der aus der letzten Antwort.
163
+
164
+ **Das Portal verschickt für so angelegte Tippgeber nichts von selbst.** Der Workflow muss
165
+ `set_password_url` zustellen – und nur, wenn der Link nicht `null` ist. Eine Begrüßung nur bei
166
+ `created: true` schicken, sonst bekommt ein Bestandskunde sie bei jedem weiteren Auftrag.
167
+
168
+ „Referral → Create“ verhält sich genauso: `created: false` heißt, dass dieser Tippgeber den Kontakt
169
+ schon empfohlen hat; ein Folgeschritt (Lead in Close anlegen) darf dann nicht noch einmal laufen.
170
+
171
+ ### Freischalten und Reaktivieren
172
+
173
+ - **Referrer → Approve** schaltet ein Konto frei, das auf Freischaltung wartet (`status: pending`). Das
174
+ Portal meldet das genau einmal („Referrer Approved“, dazu die E-Mail „Konto freigeschaltet“, wenn ein
175
+ Postfach hinterlegt ist). Ist das Konto schon aktiv, kommt es unverändert zurück – eine Wiederholung
176
+ ist folgenlos. Ist es **deaktiviert oder abgelehnt**, bricht der Node mit `referrer_not_pending` ab:
177
+ Ein Freigabe-Workflow soll eine Entscheidung des Teams nicht rückgängig machen.
178
+ - **Referrer → Update → Active** = an: reaktiviert bewusst auch ein deaktiviertes Konto, ohne die
179
+ Freischalt-Meldung (bei einem wartenden Konto ist es die Freischaltung, mit Meldung).
180
+ **Active** = aus: deaktiviert und beendet alle Sitzungen.
181
+
182
+ ### Als Werkzeug für KI-Agenten
183
+
184
+ Der Node lässt sich in n8n als Werkzeug an einen KI-Agenten hängen (das verlangt das Prüfwerkzeug von
185
+ n8n für Community-Nodes). Ein Agent kann damit auch Prämien vergeben und als ausgezahlt markieren.
186
+ Nur anschließen, wenn das gewollt ist, und dann mit einem eigenen API-Schlüssel, der sich einzeln
187
+ widerrufen lässt.
188
+
189
+ ## Trigger-Node „LK-Tippgeber Trigger“
190
+
191
+ Ereignisse: neue Empfehlung, Status geändert, Prämie vergeben, Prämie ausgezahlt, Prämie entfallen,
192
+ Auszahlung zurückgenommen, neuer Tippgeber (wartende mit `status: pending`), Tippgeber freigeschaltet.
193
+
194
+ Der Trigger **meldet sich selbst im Portal an**, sobald der Workflow aktiviert wird, und wieder ab, wenn
195
+ er deaktiviert wird. Im Portal erscheint er unter Admin → Schnittstellen als „n8n: <Name des
196
+ Workflows>“. Es muss dort nichts von Hand eingetragen werden.
197
+
198
+ Im Workflow stehen die Daten direkt zur Verfügung:
199
+
200
+ ```
201
+ {{ $json.event }} referral.created
202
+ {{ $json.event_id }} Kennung des Ereignisses
203
+ {{ $json.triggered_by }} lead · referrer · admin · api · system
204
+ {{ $json.referral.id }} ID der Empfehlung – damit arbeiten die Folgeschritte
205
+ {{ $json.referral.email }} kann leer sein
206
+ {{ $json.referral.referrer.email }}
207
+ ```
208
+
209
+ ### Doppelte Läufe verhindern (`event_id`)
210
+
211
+ Das Portal wartet je Zustellung 8 Sekunden auf eine Antwort und versucht es bei Zeitüberschreitung
212
+ oder einem Fehler von n8n bis zu dreimal. Kam der erste Versuch in Wahrheit an, läuft der Workflow
213
+ doppelt – mit doppeltem Lead in Close oder doppelter E-Mail. Jeder Versuch desselben Ereignisses trägt
214
+ dieselbe **`event_id`** (im Portal `id` bzw. Kopfzeile `X-LK-Event-Id`).
215
+
216
+ Direkt hinter den Trigger gehört deshalb der Node **Remove Duplicates** mit
217
+
218
+ - Operation: **Remove Items Processed in Previous Executions**
219
+ - Keep Items Where: **Value Is New**
220
+ - Value to Dedupe On: `{{ $json.event_id }}`
221
+
222
+ Der Trigger antwortet sofort, Wiederholungen sind also selten – aber nach einem Neustart von n8n oder
223
+ einem hängenden Proxy kommen sie vor. Der Node selbst merkt sich keine Kennungen. Die Schritte ins
224
+ Portal sind ohnehin wiederholbar: Dieselbe Prämie zweimal vergeben ändert beim zweiten Mal nichts.
225
+
226
+ ### Sicherheit
227
+
228
+ Portal und Node tauschen beim Anmelden ein Geheimnis aus; das Portal schickt es mit jedem Ereignis mit.
229
+ Der Node nimmt nur Aufrufe mit diesem Geheimnis an. Hat der Workflow kein Geheimnis gespeichert, wird
230
+ **alles** abgewiesen (401) – auch an der Test-Adresse des Editors. Dann den Workflow einmal aus- und
231
+ wieder einschalten. Ein Ereignis von Hand per `curl` einzuspielen geht deshalb nicht.
232
+
233
+ ### Ausprobieren
234
+
235
+ - **Im Editor:** „Listen for test event“ anklicken. Der Node meldet dafür vorübergehend die
236
+ Test-Adresse im Portal an. Dann das Ereignis im Portal auslösen (z. B. eine Empfehlung anlegen) oder
237
+ dort beim neuen Eintrag „Test senden“ drücken – das kommt als `event: test.ping` an.
238
+ - **Am aktiven Workflow:** „Test senden“ im Portal prüft nur die Verbindung. Der Node bestätigt den
239
+ Empfang, **startet den Workflow aber nicht** – die Folgeschritte liefen sonst ohne Empfehlung.
240
+
241
+ ### Schleifen vermeiden
242
+
243
+ Änderungen, die selbst über die API kamen (also aus n8n), lösen den Trigger nur aus, wenn **Include
244
+ Changes Made via API** eingeschaltet ist. Eingeschaltet droht eine Schleife, sobald derselbe Workflow
245
+ wieder ins Portal schreibt – Beispiel: Trigger „Referral Status Changed“ → Workflow setzt selbst einen
246
+ Status → Trigger feuert erneut. Wer die Option braucht, filtert direkt hinter dem Trigger mit einem IF
247
+ auf `{{ $json.triggered_by }}` **ist nicht gleich** `api`, oder trennt Lesen und Schreiben in zwei
248
+ Workflows.
249
+
250
+ ### Wenn nichts ankommt
251
+
252
+ n8n zeigt einen Workflow als aktiv, solange er eingeschaltet ist – ob das Portal ihm etwas schickt,
253
+ steht im Portal unter Admin → Schnittstellen (Liste der Trigger und Zustellprotokoll).
254
+
255
+ | Lage | Was passiert | Was zu tun ist |
256
+ | --- | --- | --- |
257
+ | **Trigger im Portal pausiert** | Solange n8n läuft, kommt nichts an, ohne dass n8n es merkt. Beim nächsten Aktivieren oder Neustart scheitert das Aktivieren mit „… is paused in the portal“. n8n schaltet einen pausierten Trigger nie selbst wieder ein und löscht ihn auch nicht. | Im Portal wieder einschalten, dann den Workflow aktivieren. Wird der Workflow nicht mehr gebraucht, den pausierten Eintrag im Portal löschen. |
258
+ | **API-Schlüssel gewechselt** | Die Trigger gehören dem alten Schlüssel. Wird der widerrufen, pausiert das Portal sie; das Aktivieren mit dem neuen Schlüssel scheitert mit „… nicht mit diesem API-Schlüssel angelegt“. | Am saubersten vor dem Wechsel: Workflows deaktivieren, solange der alte Schlüssel noch gilt (der Node meldet sich damit ab), Schlüssel tauschen, wieder aktivieren. Ist der alte Schlüssel schon widerrufen: die alten „n8n: …“-Einträge im Portal löschen, dann jeden Workflow mit Trigger aus- und wieder einschalten. |
259
+ | **Adresse von n8n geändert** (neue Domain, `WEBHOOK_URL` korrigiert) | Beim nächsten Aktivieren oder Neustart meldet der Node die neue Adresse an und entfernt den Eintrag für die alte. | Nichts. Steht danach doch noch ein Eintrag mit der alten Adresse im Portal, dort löschen. |
260
+ | **Portal war beim Deaktivieren nicht erreichbar** | Der Eintrag bleibt im Portal aktiv; n8n schreibt eine Warnung ins Protokoll und merkt sich den Eintrag. | Workflow noch einmal aktivieren und deaktivieren, oder den Eintrag im Portal löschen. |
261
+ | **Portal auf eine neue Datenbank umgezogen** | Die Anmeldungen lagen in der alten Datenbank. | Neuen API-Schlüssel eintragen, jeden Workflow mit Trigger aus- und wieder einschalten. |
262
+ | **Adresse oder Geheimnis eines „n8n: …“-Eintrags im Portal von Hand geändert** | Der Node weist jede Zustellung ab (401 im Zustellprotokoll). | Workflow aus- und wieder einschalten. Diese Einträge im Portal nur pausieren oder löschen, nicht bearbeiten. |
263
+ | **n8n-Instanz kopiert** (Sicherung auf einem zweiten Server eingespielt) | Aktiviert die Kopie dieselben Workflows mit demselben Schlüssel, übernimmt sie deren Anmeldung; die erste Instanz bekommt bis zu ihrem nächsten Neustart nichts mehr. | Auf der Kopie die Workflows nicht aktivieren oder einen eigenen Schlüssel verwenden. |
264
+
265
+ Zurückgebliebene Einträge sind nicht harmlos: Das Portal schickt weiter jedes Ereignis dorthin, das
266
+ Zustellprotokoll füllt sich mit Fehlschlägen, und bei 50 Einträgen lassen sich keine neuen anmelden.
267
+
268
+ Der Name im Portal („n8n: <Workflow>“) zieht nach einem Umbenennen beim nächsten Aktivieren oder
269
+ Neustart von n8n nach.
270
+
271
+ ### „Passwort-Link angefordert“ und die E-Mails des Portals
272
+
273
+ Nicht dabei ist das Ereignis „Passwort-Link angefordert“: Es enthält einen Zugangs-Link und geht deshalb
274
+ nur an Trigger, die ein Admin im Portal von Hand anlegt (Admin → Schnittstellen → Trigger anlegen, als
275
+ Adresse die URL eines normalen n8n-Webhook-Nodes). Ein API-Schlüssel allein soll nicht an fremde Konten
276
+ kommen.
277
+
278
+ Einfacher ist es ohne n8n: Ist im Portal unter Einstellungen → E-Mail-Versand ein Postfach hinterlegt,
279
+ verschickt das Portal selbst
280
+
281
+ - den Link nach „Passwort vergessen“ (das Ereignis geht dann an keinen Trigger mehr),
282
+ - die Nachricht „Ihr Konto ist freigeschaltet“ beim Freischalten – auch wenn n8n freischaltet. Ein
283
+ Workflow auf „Referrer Approved“ sollte dann keine zweite schicken,
284
+ - Einladungen, **wenn ein Admin sie im Portal auslöst** („Einladung per E-Mail senden“, Sammelversand
285
+ nach einem Import).
286
+
287
+ Für Tippgeber, die n8n über „Referrer → Create“ anlegt, verschickt das Portal **keine** Einladung – siehe
288
+ [Tippgeber anlegen](#tippgeber-anlegen-created-und-der-passwort-link).
289
+
290
+ ## Installation
291
+
292
+ ### Über die Oberfläche von n8n (empfohlen)
293
+
294
+ In n8n: **Settings → Community Nodes → Install**, als Paketnamen `n8n-nodes-lktippnodes` eintragen, bestätigen.
295
+ Updates erscheinen danach an derselben Stelle. Voraussetzung: Community-Nodes sind auf der Instanz nicht
296
+ abgeschaltet (`N8N_COMMUNITY_PACKAGES_ENABLED`, Standard: an).
297
+
298
+ ### Von Hand aus der Installationsdatei (Docker)
299
+
300
+ Für Instanzen ohne Zugriff auf npm oder für eine noch nicht veröffentlichte Fassung.
301
+
302
+ Die Installationsdatei heißt `n8n-nodes-lktippnodes-0.2.0.tgz` und liegt in diesem Ordner. Sie wird
303
+ nicht versioniert (`.gitignore`); fehlt sie, entsteht sie mit `npm install && npm run build && npm pack`.
304
+ Die Befehle gehen von einem Container namens `n8n` aus – der tatsächliche Name steht in `docker ps`.
305
+
306
+ ```bash
307
+ # 1. Datei auf den Server kopieren
308
+ scp n8n-nodes-lktippnodes-0.2.0.tgz root@DEIN-SERVER:/root/
309
+
310
+ # 2. Auf dem Server: in den Container legen und installieren
311
+ docker cp /root/n8n-nodes-lktippnodes-0.2.0.tgz n8n:/tmp/
312
+ docker exec -u node n8n sh -c "mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes && npm install --omit=peer /tmp/n8n-nodes-lktippnodes-0.2.0.tgz"
313
+
314
+ # 3. n8n neu starten
315
+ docker restart n8n
316
+ ```
317
+
318
+ Danach lassen sich die Nodes im Editor über die Suche nach „LK-Tippgeber“ finden.
319
+
320
+ Dazu gehört:
321
+
322
+ - **`--omit=peer`** – das Paket hat keine eigenen Abhängigkeiten; `n8n-workflow` bringt n8n mit. Ohne
323
+ den Schalter lädt npm zusätzlich die neueste Version von `n8n-workflow` samt Abhängigkeiten aus dem
324
+ Netz (der Container bräuchte Zugang zur npm-Registry), und die Nodes liefen mit einer zweiten Kopie
325
+ davon. Das Paket kommt mit beidem zurecht, nötig ist es nicht.
326
+ - **`~/.n8n` muss ein Volume sein.** Das Paket liegt unter `~/.n8n/nodes`; ohne Volume ist es nach dem
327
+ Neuanlegen des Containers weg. Die `.tgz` unter `/tmp` wird nach der Installation nicht mehr gebraucht.
328
+ - **Queue-Modus:** Worker (und eigene Webhook-Prozesse) brauchen das Paket ebenfalls – Schritt 2 und 3 in
329
+ jedem dieser Container wiederholen.
330
+ - **Update von 0.1.0:** dieselben drei Schritte mit der neuen Datei. Wurde 0.1.0 ohne `--omit=peer`
331
+ installiert, liegt unter `~/.n8n/nodes/node_modules` womöglich noch eine eigene Kopie von
332
+ `n8n-workflow`. Sie darf liegen bleiben – der Node arbeitet mit ihr genauso.
333
+
334
+ Dieser Ablauf ist nicht in einem Docker-Container nachgestellt, sondern aus dem Verhalten von npm und
335
+ aus dem Quelltext von n8n 2.48 abgeleitet (n8n lädt jedes `n8n-nodes-*`-Paket aus `~/.n8n/nodes`).
336
+
337
+ ## Einrichten
338
+
339
+ 1. Im Portal unter **Admin → Schnittstellen → API-Schlüssel** einen Schlüssel erzeugen.
340
+ 2. In n8n neue Zugangsdaten **LK-Tippgeber API** anlegen: Adresse des Portals (mit `https://`, ohne
341
+ `/api`) und den Schlüssel eintragen. „Test“ prüft beides. Eine `http://`-Adresse wird abgelehnt –
342
+ der Schlüssel ginge sonst unverschlüsselt über die Leitung (Ausnahme: `localhost` zum Testen).
343
+ 3. Nodes in einen Workflow ziehen.
344
+
345
+ ## Typischer Ablauf mit Close
346
+
347
+ **1. Neue Empfehlung → Lead in Close.**
348
+ **LK-Tippgeber Trigger** (Referral Created) → **Remove Duplicates** auf `event_id` → Lead in Close
349
+ suchen oder anlegen → **LK-Tippgeber** (Referral → Update) mit
350
+
351
+ - Find Referral By: **Referral ID**, Lookup Value: `{{ $('LK-Tippgeber Trigger').item.json.referral.id }}`
352
+ - Update Fields → External ID: die Close-Lead-ID
353
+
354
+ Die Referral ID meint genau die Empfehlung, die den Trigger ausgelöst hat. Die E-Mail-Adresse taugt hier
355
+ nicht: Empfehlungen können ohne Adresse angelegt sein, und Close verwendet einen vorhandenen Lead
356
+ wieder, wenn derselbe Kontakt später noch einmal empfohlen wird. Dann hängt die Close-ID noch an der
357
+ alten, nicht zustande gekommenen Empfehlung. Das Portal entscheidet in dem Fall so:
358
+
359
+ - Hat **derselbe Tippgeber** den Kontakt erneut empfohlen, gilt die laufende Empfehlung.
360
+ - Hat ein **anderer Tippgeber** den Kontakt empfohlen, rät das Portal nicht: Aufrufe, die diese
361
+ Close-ID nennen (als Suchmerkmal oder als „External ID“ neben der E-Mail), enden mit 409
362
+ `referral_conflict` – in `details` stehen beide IDs. Davon hängt ab, wer die Prämie bekommt. Mit der
363
+ Referral ID aus dem Trigger tritt das in Schritt 1 nicht auf: Sie schreibt die Close-ID an die neue
364
+ Empfehlung, und ab dann finden Schritt 2 und 3 über die Close-ID die richtige.
365
+
366
+ Antwortet Schritt 1 trotzdem mit einem 409 (`external_id_conflict` oder `duplicate_referral`: die
367
+ Close-ID gehört schon zu einer anderen laufenden Empfehlung), ist das ein Fall für einen Menschen – den
368
+ Fehler nicht wegfiltern.
369
+
370
+ **2. Statuswechsel in Close → Status im Portal.**
371
+ **LK-Tippgeber** (Referral → Update), Find Referral By: **Close Lead ID**, If Referral Is Not Found:
372
+ **Return Nothing**. Für Leads, die keine Empfehlung sind, endet der Workflow hier ohne Fehler. Der
373
+ Status-Ausdruck muss für jeden Close-Status einen Schlüssel des Portals liefern (Status → Get Many
374
+ zeigt sie); liefert er nichts, lehnt das Portal ab, und der Lauf wird rot.
375
+
376
+ **3. Opportunity in Close gewonnen → Prämie.**
377
+ **LK-Tippgeber** (Reward → Issue) mit
378
+
379
+ - Find Referral By: **Close Lead ID**, If Referral Is Not Found: **Return Nothing**
380
+ - Reward Basis: **Deal Value in Cents**, Deal Value: der Wert der Opportunity aus Close
381
+ - **External Opportunity ID**: die ID der Opportunity aus Close – immer mitgeben
382
+
383
+ Mit der Opportunity-ID weist das Portal eine zweite gewonnene Opportunity desselben Leads zurück (409
384
+ `opportunity_conflict`), statt die Prämie zu überschreiben; ohne sie lässt sich eine Korrektur nicht
385
+ von einem zweiten Auftrag unterscheiden (409 `opportunity_required`). Derselbe Aufruf noch einmal
386
+ ändert nichts. `reopened: true` in der Antwort heißt, dass die Empfehlung vorher „nicht zustande
387
+ gekommen“ war. Hat die Opportunity in Close keinen Wert, bricht der Node ab – eine Prämie von 0 € gibt
388
+ es nicht.
389
+
390
+ **4. Tippgeber über die Prämie informieren.**
391
+ Ein eigener Workflow: **LK-Tippgeber Trigger** (Reward Issued) mit eingeschaltetem **Include Changes
392
+ Made via API** → **Remove Duplicates** auf `event_id` → E-Mail an
393
+ `{{ $json.referral.referrer.email }}` mit `{{ $json.referral.reward_amount }}`. Das Ereignis kommt nur,
394
+ wenn sich an der Prämie wirklich etwas geändert hat – auch für Prämien, die das Team im Admin-Bereich
395
+ vergibt. Die Option ist nötig, weil die Prämie aus Schritt 3 über die API kam; eine Schleife entsteht
396
+ nicht, solange dieser Workflow nicht selbst ins Portal schreibt.
397
+
398
+ Nicht zu empfehlen ist die E-Mail direkt hinter Schritt 3: „Issue“ antwortet auch dann mit der Prämie,
399
+ wenn sich nichts geändert hat. Läuft der Workflow ein zweites Mal (Close meldet den Gewinn erneut, ein
400
+ Lauf wird wiederholt), ginge die E-Mail noch einmal raus.
401
+
402
+ ## Umstieg von 0.1.0
403
+
404
+ Vorhandene Nodes behalten in n8n ihre Version (1) und damit ihre bisherigen Vorgaben: „Find Referral
405
+ By“ = Lead Email, „Reward Basis“ mit getrenntem „Deal Value Unit“ = Euros. Hier ändert sich nichts
406
+ still. Bei „Issue“ einmal nachsehen, ob die Einheit zum Wert passt – ein Hinweis steht jetzt am Feld.
407
+ Neu eingefügte Nodes sind Version 2: Vorgabe Referral ID, die Einheit steckt in „Reward Basis“
408
+ (Vorgabe Cents), „External Opportunity ID“ ist ein sichtbares Feld.
409
+
410
+ Für **alle** Nodes, auch die vorhandenen, gilt ab 0.2.0:
411
+
412
+ | Was | Vorher | Jetzt |
413
+ | --- | --- | --- |
414
+ | Fehler mit „Continue On Fail“ / „On Error: Continue“ | `{ error }` mit wechselndem Text | `{ error, code, status, details }`; die Meldung ist die des Portals |
415
+ | „Referrer → Approve“ bei deaktiviertem Konto | Konto wurde wieder aktiv | Fehler `referrer_not_pending`; reaktivieren über Update → Active |
416
+ | Leerer Status in „Referral → Update“ | stillschweigend übergangen | 422 vom Portal |
417
+ | „Deal Value“ / „Fixed Reward“ = 0 in „Referral → Update“ | Prämie entfiel | abgelehnt, außer mit „Allow Removing the Reward“ |
418
+ | Leere Zahlen- und Textfelder in „Update“, auch `{{ null }}` | Zahl: Wert gelöscht · Text: übergangen · `null`: gelöscht | nichts wird gesendet; Leeren über „Fields to Clear“ |
419
+ | Vorgabe neu hinzugefügter Zahlenfelder (Deal Value, Fixed Reward, Commission Rate, Amount) | 0 bzw. 10 | leer |
420
+ | Leerer Suchwert, leere ID | Fehler des Portals bzw. Aufruf der Listen-Route | klare Meldung des Nodes, nichts wird gesendet |
421
+ | Ausgabe von „Create“ | nur der Datensatz | zusätzlich `created`; bei „Issue“ zusätzlich `reopened` |
422
+ | „Updated Since“ ohne Zeitzone | als UTC gelesen | in der Zeitzone des Workflows gelesen |
423
+ | Adresse des Portals mit `http://` | wurde benutzt | abgelehnt (außer `localhost`) |
424
+ | Trigger: Ausgabe | `event`, `sent_at`, `triggered_by`, Daten | zusätzlich `event_id` |
425
+ | Trigger: „Test senden“ am aktiven Workflow | startete den Workflow | wird nur bestätigt |
426
+ | Trigger: Workflow ohne gespeichertes Geheimnis | ließ alles durch | weist alles ab (401) |
427
+ | Trigger: im Portal pausiert | n8n zeigte „aktiv“ | Aktivieren scheitert mit Meldung |
428
+
429
+ Zugangsdaten und Trigger bleiben, wie sie sind: Workflows müssen nach dem Update nicht neu aktiviert
430
+ werden.
431
+
432
+ ## Entwicklung
433
+
434
+ ```bash
435
+ npm install
436
+ npm run lint # Prüfung mit dem offiziellen n8n-Werkzeug
437
+ npm run build # nach dist/
438
+ npm run dev # startet ein lokales n8n mit den Nodes auf http://localhost:5678
439
+ npm pack # erzeugt die .tgz für die Installation
440
+ ```
441
+
442
+ Aufbau: `credentials/` (Zugangsdaten), `nodes/LkTippgeber/` (Action-Node, Felder in
443
+ `descriptions.ts`, HTTP-Aufrufe und Fehlerbehandlung in `GenericFunctions.ts`),
444
+ `nodes/LkTippgeberTrigger/` (Trigger).
445
+
446
+ Prüfen ohne n8n und ohne laufendes Portal: `node .claude/checks/a9-runde2-check.js` im Projektordner
447
+ (nach `npm run build`). Gegen eine laufende lokale Instanz: `.claude/checks/n8n-harness.js`.
448
+
449
+ - **Keine Portal-Adresse im Paket:** Das Feld „Base URL“ der Zugangsdaten ist nicht vorbelegt; die Hilfe-Links
450
+ zeigen auf die Seite des Pakets bei npm. Zugangsdaten, die mit einer früheren Fassung angelegt wurden und in
451
+ denen die damals vorbelegte Adresse nie geändert wurde, nach dem Update einmal öffnen und die Adresse prüfen.
452
+ - **Lizenz:** MIT, siehe `LICENSE`.
453
+ - **Zwei Versionen des Nodes:** Wer eine Vorgabe ändert, legt dafür eine neue Version an (siehe Kopf
454
+ von `descriptions.ts`) – n8n speichert Werte nicht, die der Vorgabe entsprechen, eine geänderte
455
+ Vorgabe würde vorhandene Workflows also still umstellen.
@@ -0,0 +1,10 @@
1
+ import type { ICredentialDataDecryptedObject, ICredentialTestRequest, ICredentialType, Icon, IHttpRequestOptions, INodeProperties } from 'n8n-workflow';
2
+ export declare class LkTippgeberApi implements ICredentialType {
3
+ name: string;
4
+ displayName: string;
5
+ icon: Icon;
6
+ documentationUrl: string;
7
+ properties: INodeProperties[];
8
+ authenticate(credentials: ICredentialDataDecryptedObject, requestOptions: IHttpRequestOptions): Promise<IHttpRequestOptions>;
9
+ test: ICredentialTestRequest;
10
+ }
@@ -0,0 +1,55 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.LkTippgeberApi = void 0;
4
+ const GenericFunctions_1 = require("../nodes/LkTippgeber/GenericFunctions");
5
+ class LkTippgeberApi {
6
+ constructor() {
7
+ this.name = 'lkTippgeberApi';
8
+ this.displayName = 'LK-Tippgeber API';
9
+ this.icon = {
10
+ light: 'file:../nodes/LkTippgeber/lkTippgeber.svg',
11
+ dark: 'file:../nodes/LkTippgeber/lkTippgeber.dark.svg',
12
+ };
13
+ this.documentationUrl = 'https://www.npmjs.com/package/n8n-nodes-lktippnodes';
14
+ this.properties = [
15
+ {
16
+ displayName: 'Base URL',
17
+ name: 'baseUrl',
18
+ type: 'string',
19
+ required: true,
20
+ default: '',
21
+ placeholder: 'https://tippgeber.example.com',
22
+ description: 'Address of your LK-Tippgeber portal, starting with https:// and without /api or a trailing slash',
23
+ },
24
+ {
25
+ displayName: 'API Key',
26
+ name: 'apiKey',
27
+ type: 'string',
28
+ typeOptions: { password: true },
29
+ required: true,
30
+ default: '',
31
+ description: 'Create a key in the portal under Admin → Schnittstellen → API-Schlüssel. It is shown only once.',
32
+ },
33
+ ];
34
+ this.test = {
35
+ request: {
36
+ baseURL: '={{$credentials.baseUrl.trim().replace(/\\/+$/, "")}}',
37
+ url: '/api/v1/ping',
38
+ method: 'GET',
39
+ },
40
+ };
41
+ }
42
+ async authenticate(credentials, requestOptions) {
43
+ var _a;
44
+ const problem = (0, GenericFunctions_1.baseUrlProblem)(credentials.baseUrl);
45
+ if (problem)
46
+ throw new Error(problem);
47
+ requestOptions.headers = {
48
+ ...requestOptions.headers,
49
+ Authorization: `Bearer ${String((_a = credentials.apiKey) !== null && _a !== void 0 ? _a : '').trim()}`,
50
+ };
51
+ return requestOptions;
52
+ }
53
+ }
54
+ exports.LkTippgeberApi = LkTippgeberApi;
55
+ //# sourceMappingURL=LkTippgeberApi.credentials.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"LkTippgeberApi.credentials.js","sourceRoot":"","sources":["../../credentials/LkTippgeberApi.credentials.ts"],"names":[],"mappings":";;;AASA,4EAAuE;AAEvE,MAAa,cAAc;IAA3B;QACC,SAAI,GAAG,gBAAgB,CAAC;QAExB,gBAAW,GAAG,kBAAkB,CAAC;QAEjC,SAAI,GAAS;YACZ,KAAK,EAAE,2CAA2C;YAClD,IAAI,EAAE,gDAAgD;SACtD,CAAC;QAGF,qBAAgB,GAAG,qDAAqD,CAAC;QAEzE,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBAGd,OAAO,EAAE,EAAE;gBACX,WAAW,EAAE,+BAA+B;gBAC5C,WAAW,EACV,kGAAkG;aACnG;YACD;gBACC,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EACV,iGAAiG;aAClG;SACD,CAAC;QAkBF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,uDAAuD;gBAChE,GAAG,EAAE,cAAc;gBACnB,MAAM,EAAE,KAAK;aACb;SACD,CAAC;IACH,CAAC;IArBA,KAAK,CAAC,YAAY,CACjB,WAA2C,EAC3C,cAAmC;;QAEnC,MAAM,OAAO,GAAG,IAAA,iCAAc,EAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;QACtC,cAAc,CAAC,OAAO,GAAG;YACxB,GAAG,cAAc,CAAC,OAAO;YACzB,aAAa,EAAE,UAAU,MAAM,CAAC,MAAA,WAAW,CAAC,MAAM,mCAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE;SAClE,CAAC;QACF,OAAO,cAAc,CAAC;IACvB,CAAC;CAUD;AA7DD,wCA6DC"}
@@ -0,0 +1,25 @@
1
+ import type { IDataObject, IExecuteFunctions, IHookFunctions, IHttpRequestMethods, ILoadOptionsFunctions, INode, IWebhookFunctions } from 'n8n-workflow';
2
+ import { NodeOperationError } from 'n8n-workflow';
3
+ type Context = IExecuteFunctions | ILoadOptionsFunctions | IHookFunctions | IWebhookFunctions;
4
+ export type Failure = {
5
+ error: string;
6
+ code: string | null;
7
+ status: number | null;
8
+ details: IDataObject | null;
9
+ };
10
+ export declare function failureOf(error: unknown): Failure;
11
+ export declare function inputError(node: INode, message: string, options?: {
12
+ itemIndex?: number;
13
+ code?: string;
14
+ description?: string;
15
+ }): NodeOperationError;
16
+ export declare function baseUrlProblem(raw: unknown): string | null;
17
+ export declare function lkApiRequest(this: Context, method: IHttpRequestMethods, path: string, body?: IDataObject, qs?: IDataObject): Promise<IDataObject>;
18
+ export declare function lkApiRequestAllItems(this: IExecuteFunctions, path: string, qs: IDataObject, limit?: number): Promise<IDataObject[]>;
19
+ export declare function textValue(value: unknown): string | undefined;
20
+ export declare function numberValue(value: unknown): number | undefined;
21
+ export declare function cleanRate(rate: number): number;
22
+ export declare function compact(input: IDataObject): IDataObject;
23
+ export declare function toInstant(value: unknown, timeZone: () => string): string | undefined;
24
+ export declare function safeEqual(a: string, b: string): boolean;
25
+ export {};