lktippnodes

n8n nodes for LK-Tippgeber: manage referrals, rewards and referrers and react to events from the referral portal

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.3.0
Author: Helixify

Documentation

n8n-nodes-lktippnodes

n8n-Nodes für das Empfehlungsportal LK-Tippgeber: Empfehlungen, Prämien und Tippgeber aus n8n
heraus verwalten und Workflows starten, sobald im Portal etwas passiert.

Das Paket ist für selbst gehostetes n8n gedacht und gehört zu einem LK-Tippgeber-Portal: Die Adresse des
Portals und einen API-Schlüssel tragen Sie in den Zugangsdaten ein.
Stand: Version 0.3.0 (neu: Folgeaufträge). Wer schon Workflows mit 0.1.0 gebaut hat, liest zuerst
Umstieg von 0.1.0.

Voraussetzungen

  • Selbst gehostetes n8n. Gebaut gegen n8n-workflow 2.48 (n8n 2.48). Ältere
    1.x-Versionen sind nicht geprüft.
  • n8n ist aus dem Internet per https erreichbar und kennt seine eigene Adresse. Der Trigger meldet
    im Portal die Adresse an, die n8n für sich selbst hält. Läuft n8n in Docker hinter einem Proxy, muss
    dafür WEBHOOK_URL=https://n8n.example.com/ gesetzt sein – sonst meldet n8n
    http://localhost:5678/… an, und das Portal lehnt das beim Aktivieren ab (es nimmt nur
    https-Adressen zu öffentlichen Zielen an).
  • Das Portal ist per https erreichbar, und es gibt einen API-Schlüssel
    (Admin → Schnittstellen → API-Schlüssel).

Was drin ist

Baustein Zweck
LK-Tippgeber API Zugangsdaten: Adresse des Portals und API-Schlüssel
LK-Tippgeber Action-Node: Daten ins Portal schreiben oder daraus lesen
LK-Tippgeber Trigger Startet einen Workflow bei Ereignissen im Portal

Action-Node „LK-Tippgeber“

Resource Operation Wofür
Reward Issue Prämie vergeben, z. B. wenn in Close eine Opportunity gewonnen wurde
Reward Mark as Paid Prämie als ausgezahlt markieren
Referral Update Status ändern, Close-Lead-ID speichern, Auftragswert oder Notizen setzen, Felder leeren
Referral Create Empfehlung für einen Tippgeber anlegen; gibt es sie bei ihm schon, kommt sie mit created: false zurück
Referral Get / Get Many Empfehlungen lesen und filtern (auch nach Auszahlungsstatus)
Referrer Create Tippgeber anlegen – siehe Tippgeber anlegen
Referrer Approve Wartenden Tippgeber freischalten – nur wartende, siehe Freischalten
Referrer Get / Get Many / Update Tippgeber lesen, Provisionssatz oder Stammdaten ändern, deaktivieren oder bewusst reaktivieren
Status Get Many Alle Status mit ihren Schlüsseln

Die Empfehlung finden

„Update“, „Issue“ und „Mark as Paid“ finden die Empfehlung über eines von drei Merkmalen
(Find Referral By). In dieser Reihenfolge sind sie zu empfehlen:

  1. Referral ID – die ID aus dem Portal, z. B. {{ $json.referral.id }} aus dem Trigger. Meint
    immer genau eine Empfehlung.
  2. Close Lead ID – die Close-ID, die als „External ID“ an der Empfehlung gespeichert ist. Der
    normale Weg für alles, was aus Close kommt.
  3. Lead Email – das schwächste Merkmal: Kontakte ohne E-Mail-Adresse werden nicht gefunden, und
    bei mehreren laufenden Empfehlungen zur selben Adresse antwortet das Portal mit einem Fehler.

Ein leerer Suchwert (der Ausdruck liefert nichts) ist immer ein Fehler, nie „nicht gefunden“.

Wenn es keine Empfehlung gibt

Die meisten Kontakte in Close sind keine Empfehlungen. Dafür gibt es an „Update“, „Issue“ und
„Mark as Paid“ die Auswahl If Referral Is Not Found:

  • Stop With an Error (Vorgabe) – der Node bricht ab wie bei jedem anderen Problem.
  • Return Nothing – das Element entfällt, die folgenden Nodes laufen dafür nicht. Das ist die
    richtige Einstellung für Abläufe, die bei jedem Close-Ereignis starten.

„Return Nothing“ greift nur, wenn das Portal ausdrücklich antwortet „zu diesen Angaben gibt es keine
Empfehlung“ (Fehlercode referral_not_found). Alles andere bleibt ein Fehler und macht die Ausführung
rot: mehrere passende Empfehlungen, eine schon ausgezahlte Prämie, ein Auftragswert von 0, ein
widerrufener Schlüssel, ein Ausfall des Portals. So fällt keine Prämie still aus.

Fehler

Schlägt ein Aufruf fehl, bricht der Node ab. Die Überschrift des Fehlers ist die Meldung des Portals,
in der Beschreibung darunter stehen Fehlercode, HTTP-Status und – wenn das Portal sie liefert – die
betroffenen IDs. Das ist der richtige Normalfall: Ein roter Lauf fällt auf, und ein Fehler-Workflow
kann benachrichtigen.

Wer Fehler im Workflow selbst behandeln will, stellt den Node unter Settings → On Error auf
„Continue (using error output)“. Jedes gescheiterte Element kommt dann am Fehler-Ausgang an, mit:

Feld Inhalt
error Die Meldung als Text. Zum Anzeigen, nicht zum Verzweigen.
code Fehlercode des Portals, z. B. referral_not_found. null, wenn das Portal gar nicht geantwortet hat.
status HTTP-Status der Antwort (404, 409, 422, 500 …) oder null.
details Zusatzangaben des Portals, z. B. { "referral_ids": ["…", "…"] }, oder null.

n8n ergänzt am Fehler-Ausgang die Eingabedaten des Elements; die vier Felder oben setzt immer der
Node. Mit „Continue“ (ohne eigenen Fehler-Ausgang) fehlen die Eingabedaten – dort hilft
{{ $('Name des vorherigen Nodes').item.json }}.

Nicht pauschal auf „error vorhanden“ verzweigen – dann sieht ein Ausfall des Portals genauso aus
wie „kein Tippgeber-Kontakt“. Wenn überhaupt, dann so: hinter dem Fehler-Ausgang ein IF mit
{{ $json.code }} ist gleich referral_not_found → Ende; der andere Zweig führt in einen Node
„Stop and Error“ (Meldung {{ $json.error }}) oder in eine Benachrichtigung an das Team. Auch status
allein reicht nicht: Ein 404 ohne code heißt, dass unter der Adresse gar nicht das Portal antwortet.
Für den häufigsten Fall braucht es das alles nicht – dafür gibt es „If Referral Is Not Found“.

Die wichtigsten Codes:

code Status Bedeutung
referral_not_found 404 Zu den Angaben gibt es keine Empfehlung.
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.
ambiguous_referral 409 Mehrere laufende Empfehlungen passen. details.referral_ids nennt sie.
external_id_conflict, duplicate_referral 409 Die Close-ID oder der Kontakt gehört schon zu einer anderen Empfehlung.
opportunity_conflict, opportunity_required 409 Es gibt schon eine Prämie für einen anderen Auftrag – sie wird nicht überschrieben. Für einen weiteren Auftrag desselben Kunden: Follow-Up Order einschalten.
opportunity_unassigned 409 „Follow-Up Order“ an einer Empfehlung, deren Prämie von Hand und ohne Opportunity-ID vergeben wurde, mit anderem Betrag: Das Portal rät nicht, ob es derselbe Auftrag ist.
paid_locked 409 Die Prämie ist ausgezahlt und gesperrt.
reward_is_zero, reward_basis_missing 422 Es ergäbe sich keine Prämie, oder eine vorhandene entfiele.
deal_value_implausible 422 Auftragswert über 50.000 € – fast immer Cent im Euro-Feld.
validation_error, invalid_value 422 Ein Feld ist ungültig, z. B. ein leerer Status oder ein Satz mit mehr als vier Nachkommastellen.
unauthorized 401 Der API-Schlüssel ist falsch oder widerrufen.
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.
invalid_input, invalid_credentials – Vom Node selbst abgelehnt, bevor etwas gesendet wurde (leerer Suchwert, 0 als Betrag, Adresse des Portals ohne https).

Euro oder Cent

Close liefert den Wert einer Opportunity in Cent (149000 = 1.490,00 €). Mit der falschen Einheit
wird die Prämie hundertmal zu hoch oder zu niedrig.

  • Reward → Issue fragt die Einheit mit der ersten Auswahl ab: Reward Basis = „Deal Value in
    Cents“ (Vorgabe, passend zu Close), „Deal Value in Euros“ oder „Fixed Amount“ (Euro).
  • Referral → Update kennt beim Feld „Deal Value“ nur Euro. Kommt der Wert aus Close, im Ausdruck
    durch 100 teilen: {{ $json.value / 100 }}.
  • Das Portal weist Auftragswerte über 50.000 € zurück (deal_value_implausible). Stimmt der Betrag
    wirklich, das Zusatzfeld Confirm Deal Value hinzufügen.

Alle Beträge in den Antworten und Ereignissen des Portals sind Euro.

Leere Felder, Felder leeren und der Wert 0

Für „Referral → Update“ und „Referrer → Update“ gilt:

  • Nur Felder mit einem Wert werden gesendet. Ein hinzugefügtes, aber leeres Feld (oder ein
    Ausdruck, der nichts liefert) ändert nichts – es löscht weder einen Text noch eine Prämie. Zahlenfelder
    sind ohne Vorgabe; „nicht ausgefüllt“ ist nie 0.
  • Ausnahme Status: Ein leerer Status geht ans Portal und wird dort abgelehnt (422). Wer Close-Status
    per Ausdruck auf Portal-Status abbildet, merkt so, wenn eine Zuordnung fehlt, statt einen grünen Lauf
    ohne Wirkung zu bekommen.
  • Leeren geht nur über „Fields to Clear“ – dort die Felder ankreuzen, deren gespeicherter Wert
    entfernt werden soll (Telefon, Notiz, Firma, eigener Provisionssatz, Auftragswert …).
  • 0 als Auftragswert oder feste Prämie lehnt der Node ab, weil damit eine schon vergebene Prämie
    entfiele. Ist genau das gewollt (oder soll der Auftragswert geleert werden, obwohl es eine Prämie
    gibt), zusätzlich Allow Removing the Reward hinzufügen. Ohne diese Bestätigung lehnt auch das
    Portal ab (reward_is_zero).
  • Bleibt nach alledem nichts zu senden, sagt der Node das („Nothing to update: … is empty“), statt einen
    leeren Aufruf zu schicken.

Tippgeber anlegen: created und der Passwort-Link

„Referrer → Create“ gibt den Tippgeber zurück, dazu created und set_password_url:

  • created: true – neu angelegt. set_password_url ist der Einmal-Link, über den der Tippgeber
    sein Passwort setzt.
  • created: false – zu der E-Mail-Adresse gab es schon einen Tippgeber. Er kommt unverändert
    zurück; mitgeschickte Angaben (Name, Firma, Provisionssatz) werden nicht übernommen – dafür ist
    „Referrer → Update“ da.
  • set_password_url gibt es nur, solange das Konto aktiv ist und noch kein Passwort hat. Sonst ist
    das Feld null (warum, steht in has_password und status). Jeder neue Link entwertet den
    vorherigen: Verschickt wird immer der aus der letzten Antwort.

Das Portal verschickt für so angelegte Tippgeber nichts von selbst. Der Workflow muss
set_password_url zustellen – und nur, wenn der Link nicht null ist. Eine Begrüßung nur bei
created: true schicken, sonst bekommt ein Bestandskunde sie bei jedem weiteren Auftrag.

„Referral → Create“ verhält sich genauso: created: false heißt, dass dieser Tippgeber den Kontakt
schon empfohlen hat; ein Folgeschritt (Lead in Close anlegen) darf dann nicht noch einmal laufen.

Freischalten und Reaktivieren

  • Referrer → Approve schaltet ein Konto frei, das auf Freischaltung wartet (status: pending). Das
    Portal meldet das genau einmal („Referrer Approved“, dazu die E-Mail „Konto freigeschaltet“, wenn ein
    Postfach hinterlegt ist). Ist das Konto schon aktiv, kommt es unverändert zurück – eine Wiederholung
    ist folgenlos. Ist es deaktiviert oder abgelehnt, bricht der Node mit referrer_not_pending ab:
    Ein Freigabe-Workflow soll eine Entscheidung des Teams nicht rückgängig machen.
  • Referrer → Update → Active = an: reaktiviert bewusst auch ein deaktiviertes Konto, ohne die
    Freischalt-Meldung (bei einem wartenden Konto ist es die Freischaltung, mit Meldung).
    Active = aus: deaktiviert und beendet alle Sitzungen.

Als Werkzeug für KI-Agenten

Der Node lässt sich in n8n als Werkzeug an einen KI-Agenten hängen (das verlangt das Prüfwerkzeug von
n8n für Community-Nodes). Ein Agent kann damit auch Prämien vergeben und als ausgezahlt markieren.
Nur anschließen, wenn das gewollt ist, und dann mit einem eigenen API-Schlüssel, der sich einzeln
widerrufen lässt.

Trigger-Node „LK-Tippgeber Trigger“

Ereignisse: neue Empfehlung, Status geändert, Prämie vergeben, Prämie ausgezahlt, Prämie entfallen,
Auszahlung zurückgenommen, neuer Tippgeber (wartende mit status: pending), Tippgeber freigeschaltet.

Der Trigger meldet sich selbst im Portal an, sobald der Workflow aktiviert wird, und wieder ab, wenn
er deaktiviert wird. Im Portal erscheint er unter Admin → Schnittstellen als „n8n: “. Es muss dort nichts von Hand eingetragen werden.

Im Workflow stehen die Daten direkt zur Verfügung:

{{ $json.event }}                    referral.created
{{ $json.event_id }}                 Kennung des Ereignisses
{{ $json.triggered_by }}             lead · referrer · admin · api · system
{{ $json.referral.id }}              ID der Empfehlung – damit arbeiten die Folgeschritte
{{ $json.referral.email }}           kann leer sein
{{ $json.referral.referrer.email }}

Doppelte Läufe verhindern (event_id)

Das Portal wartet je Zustellung 8 Sekunden auf eine Antwort und versucht es bei Zeitüberschreitung
oder einem Fehler von n8n bis zu dreimal. Kam der erste Versuch in Wahrheit an, läuft der Workflow
doppelt – mit doppeltem Lead in Close oder doppelter E-Mail. Jeder Versuch desselben Ereignisses trägt
dieselbe event_id (im Portal id bzw. Kopfzeile X-LK-Event-Id).

Direkt hinter den Trigger gehört deshalb der Node Remove Duplicates mit

  • Operation: Remove Items Processed in Previous Executions
  • Keep Items Where: Value Is New
  • Value to Dedupe On: {{ $json.event_id }}

Der Trigger antwortet sofort, Wiederholungen sind also selten – aber nach einem Neustart von n8n oder
einem hängenden Proxy kommen sie vor. Der Node selbst merkt sich keine Kennungen. Die Schritte ins
Portal sind ohnehin wiederholbar: Dieselbe Prämie zweimal vergeben ändert beim zweiten Mal nichts.

Sicherheit

Portal und Node tauschen beim Anmelden ein Geheimnis aus; das Portal schickt es mit jedem Ereignis mit.
Der Node nimmt nur Aufrufe mit diesem Geheimnis an. Hat der Workflow kein Geheimnis gespeichert, wird
alles abgewiesen (401) – auch an der Test-Adresse des Editors. Dann den Workflow einmal aus- und
wieder einschalten. Ein Ereignis von Hand per curl einzuspielen geht deshalb nicht.

Ausprobieren

  • Im Editor: „Listen for test event“ anklicken. Der Node meldet dafür vorübergehend die
    Test-Adresse im Portal an. Dann das Ereignis im Portal auslösen (z. B. eine Empfehlung anlegen) oder
    dort beim neuen Eintrag „Test senden“ drücken – das kommt als event: test.ping an.
  • Am aktiven Workflow: „Test senden“ im Portal prüft nur die Verbindung. Der Node bestätigt den
    Empfang, startet den Workflow aber nicht – die Folgeschritte liefen sonst ohne Empfehlung.

Schleifen vermeiden

Änderungen, die selbst über die API kamen (also aus n8n), lösen den Trigger nur aus, wenn Include
Changes Made via API
eingeschaltet ist. Eingeschaltet droht eine Schleife, sobald derselbe Workflow
wieder ins Portal schreibt – Beispiel: Trigger „Referral Status Changed“ → Workflow setzt selbst einen
Status → Trigger feuert erneut. Wer die Option braucht, filtert direkt hinter dem Trigger mit einem IF
auf {{ $json.triggered_by }} ist nicht gleich api, oder trennt Lesen und Schreiben in zwei
Workflows.

Wenn nichts ankommt

n8n zeigt einen Workflow als aktiv, solange er eingeschaltet ist – ob das Portal ihm etwas schickt,
steht im Portal unter Admin → Schnittstellen (Liste der Trigger und Zustellprotokoll).

Lage Was passiert Was zu tun ist
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.
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.
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.
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.
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.
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.
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.

Zurückgebliebene Einträge sind nicht harmlos: Das Portal schickt weiter jedes Ereignis dorthin, das
Zustellprotokoll füllt sich mit Fehlschlägen, und bei 50 Einträgen lassen sich keine neuen anmelden.

Der Name im Portal („n8n: “) zieht nach einem Umbenennen beim nächsten Aktivieren oder
Neustart von n8n nach.

„Passwort-Link angefordert“ und die E-Mails des Portals

Nicht dabei ist das Ereignis „Passwort-Link angefordert“: Es enthält einen Zugangs-Link und geht deshalb
nur an Trigger, die ein Admin im Portal von Hand anlegt (Admin → Schnittstellen → Trigger anlegen, als
Adresse die URL eines normalen n8n-Webhook-Nodes). Ein API-Schlüssel allein soll nicht an fremde Konten
kommen.

Einfacher ist es ohne n8n: Ist im Portal unter Einstellungen → E-Mail-Versand ein Postfach hinterlegt,
verschickt das Portal selbst

  • den Link nach „Passwort vergessen“ (das Ereignis geht dann an keinen Trigger mehr),
  • die Nachricht „Ihr Konto ist freigeschaltet“ beim Freischalten – auch wenn n8n freischaltet. Ein
    Workflow auf „Referrer Approved“ sollte dann keine zweite schicken,
  • Einladungen, wenn ein Admin sie im Portal auslöst („Einladung per E-Mail senden“, Sammelversand
    nach einem Import).

Für Tippgeber, die n8n über „Referrer → Create“ anlegt, verschickt das Portal keine Einladung – siehe
Tippgeber anlegen.

Installation

Über die Oberfläche von n8n (empfohlen)

In n8n: Settings → Community Nodes → Install, als Paketnamen n8n-nodes-lktippnodes eintragen, bestätigen.
Updates erscheinen danach an derselben Stelle. Voraussetzung: Community-Nodes sind auf der Instanz nicht
abgeschaltet (N8N_COMMUNITY_PACKAGES_ENABLED, Standard: an).

Von Hand aus der Installationsdatei (Docker)

Für Instanzen ohne Zugriff auf npm oder für eine noch nicht veröffentlichte Fassung.

Die Installationsdatei heißt n8n-nodes-lktippnodes-0.3.0.tgz und liegt in diesem Ordner. Sie wird
nicht versioniert (.gitignore); fehlt sie, entsteht sie mit npm install && npm run build && npm pack.
Die Befehle gehen von einem Container namens n8n aus – der tatsächliche Name steht in docker ps.

# 1. Datei auf den Server kopieren
scp n8n-nodes-lktippnodes-0.3.0.tgz root@DEIN-SERVER:/root/

# 2. Auf dem Server: in den Container legen und installieren
docker cp /root/n8n-nodes-lktippnodes-0.3.0.tgz n8n:/tmp/
docker exec -u node n8n sh -c "mkdir -p ~/.n8n/nodes && cd ~/.n8n/nodes && npm install --omit=peer /tmp/n8n-nodes-lktippnodes-0.3.0.tgz"

# 3. n8n neu starten
docker restart n8n

Danach lassen sich die Nodes im Editor über die Suche nach „LK-Tippgeber“ finden.

Dazu gehört:

  • --omit=peer – das Paket hat keine eigenen Abhängigkeiten; n8n-workflow bringt n8n mit. Ohne
    den Schalter lädt npm zusätzlich die neueste Version von n8n-workflow samt Abhängigkeiten aus dem
    Netz (der Container bräuchte Zugang zur npm-Registry), und die Nodes liefen mit einer zweiten Kopie
    davon. Das Paket kommt mit beidem zurecht, nötig ist es nicht.
  • ~/.n8n muss ein Volume sein. Das Paket liegt unter ~/.n8n/nodes; ohne Volume ist es nach dem
    Neuanlegen des Containers weg. Die .tgz unter /tmp wird nach der Installation nicht mehr gebraucht.
  • Queue-Modus: Worker (und eigene Webhook-Prozesse) brauchen das Paket ebenfalls – Schritt 2 und 3 in
    jedem dieser Container wiederholen.
  • Update von 0.1.0: dieselben drei Schritte mit der neuen Datei. Wurde 0.1.0 ohne --omit=peer
    installiert, liegt unter ~/.n8n/nodes/node_modules womöglich noch eine eigene Kopie von
    n8n-workflow. Sie darf liegen bleiben – der Node arbeitet mit ihr genauso.

Dieser Ablauf ist nicht in einem Docker-Container nachgestellt, sondern aus dem Verhalten von npm und
aus dem Quelltext von n8n 2.48 abgeleitet (n8n lädt jedes n8n-nodes-*-Paket aus ~/.n8n/nodes).

Einrichten

  1. Im Portal unter Admin → Schnittstellen → API-Schlüssel einen Schlüssel erzeugen.
  2. In n8n neue Zugangsdaten LK-Tippgeber API anlegen: Adresse des Portals (mit https://, ohne
    /api) und den Schlüssel eintragen. „Test“ prüft beides. Eine http://-Adresse wird abgelehnt –
    der Schlüssel ginge sonst unverschlüsselt über die Leitung (Ausnahme: localhost zum Testen).
  3. Nodes in einen Workflow ziehen.

Typischer Ablauf mit Close

1. Neue Empfehlung → Lead in Close.
LK-Tippgeber Trigger (Referral Created) → Remove Duplicates auf event_id → Lead in Close
suchen oder anlegen → LK-Tippgeber (Referral → Update) mit

  • Find Referral By: Referral ID, Lookup Value: {{ $('LK-Tippgeber Trigger').item.json.referral.id }}
  • Update Fields → External ID: die Close-Lead-ID

Die Referral ID meint genau die Empfehlung, die den Trigger ausgelöst hat. Die E-Mail-Adresse taugt hier
nicht: Empfehlungen können ohne Adresse angelegt sein, und Close verwendet einen vorhandenen Lead
wieder, wenn derselbe Kontakt später noch einmal empfohlen wird. Dann hängt die Close-ID noch an der
alten, nicht zustande gekommenen Empfehlung. Das Portal entscheidet in dem Fall so:

  • Hat derselbe Tippgeber den Kontakt erneut empfohlen, gilt die laufende Empfehlung.
  • Hat ein anderer Tippgeber den Kontakt empfohlen, rät das Portal nicht: Aufrufe, die diese
    Close-ID nennen (als Suchmerkmal oder als „External ID“ neben der E-Mail), enden mit 409
    referral_conflict – in details stehen beide IDs. Davon hängt ab, wer die Prämie bekommt. Mit der
    Referral ID aus dem Trigger tritt das in Schritt 1 nicht auf: Sie schreibt die Close-ID an die neue
    Empfehlung, und ab dann finden Schritt 2 und 3 über die Close-ID die richtige.

Antwortet Schritt 1 trotzdem mit einem 409 (external_id_conflict oder duplicate_referral: die
Close-ID gehört schon zu einer anderen laufenden Empfehlung), ist das ein Fall für einen Menschen – den
Fehler nicht wegfiltern.

2. Statuswechsel in Close → Status im Portal.
LK-Tippgeber (Referral → Update), Find Referral By: Close Lead ID, If Referral Is Not Found:
Return Nothing. Für Leads, die keine Empfehlung sind, endet der Workflow hier ohne Fehler. Der
Status-Ausdruck muss für jeden Close-Status einen Schlüssel des Portals liefern (Status → Get Many
zeigt sie); liefert er nichts, lehnt das Portal ab, und der Lauf wird rot.

3. Opportunity in Close gewonnen → Prämie.
LK-Tippgeber (Reward → Issue) mit

  • Find Referral By: Close Lead ID, If Referral Is Not Found: Return Nothing
  • Reward Basis: Deal Value in Cents, Deal Value: der Wert der Opportunity aus Close
  • External Opportunity ID: die ID der Opportunity aus Close – immer mitgeben

Mit der Opportunity-ID weist das Portal eine zweite gewonnene Opportunity desselben Leads zurück (409
opportunity_conflict), statt die Prämie zu überschreiben; ohne sie lässt sich eine Korrektur nicht
von einem zweiten Auftrag unterscheiden (409 opportunity_required). Derselbe Aufruf noch einmal
ändert nichts. reopened: true in der Antwort heißt, dass die Empfehlung vorher „nicht zustande
gekommen“ war. Hat die Opportunity in Close keinen Wert, bricht der Node ab – eine Prämie von 0 € gibt
es nicht.

Soll ein Tippgeber auch für spätere Aufträge desselben Kunden eine Prämie bekommen, zusätzlich
Follow-Up Order einschalten – siehe Folgeaufträge.

4. Tippgeber über die Prämie informieren.
Ein eigener Workflow: LK-Tippgeber Trigger (Reward Issued) mit eingeschaltetem Include Changes
Made via API
→ Remove Duplicates auf event_id → E-Mail an
{{ $json.referral.referrer.email }} mit {{ $json.referral.reward_amount }}. Das Ereignis kommt nur,
wenn sich an der Prämie wirklich etwas geändert hat – auch für Prämien, die das Team im Admin-Bereich
vergibt. Die Option ist nötig, weil die Prämie aus Schritt 3 über die API kam; eine Schleife entsteht
nicht, solange dieser Workflow nicht selbst ins Portal schreibt.

Nicht zu empfehlen ist die E-Mail direkt hinter Schritt 3: „Issue“ antwortet auch dann mit der Prämie,
wenn sich nichts geändert hat. Läuft der Workflow ein zweites Mal (Close meldet den Gewinn erneut, ein
Lauf wird wiederholt), ginge die E-Mail noch einmal raus.

Folgeaufträge

Ein Kontakt lässt sich nur einmal empfehlen. Kauft er später noch einmal, gibt es dafür keinen zweiten
Eintrag als Empfehlung, sondern einen Folgeauftrag: einen eigenen Eintrag mit eigener Prämie und
eigener Auszahlung, der an der ursprünglichen Empfehlung hängt und demselben Tippgeber gehört.

In Reward → Issue den Schalter Follow-Up Order einschalten und die External Opportunity ID
mitgeben. Derselbe Node deckt dann alle Fälle ab – er kann fest hinter „Opportunity gewonnen“ stehen:

Stand im Portal Was „Issue“ mit „Follow-Up Order“ tut
Die Empfehlung hat noch keine Prämie erster Auftrag: Prämie an der Empfehlung (wie ohne Schalter)
Diese Opportunity ist schon vergütet (an der Empfehlung oder einem Folgeauftrag) nichts Neues: derselbe Auftrag, höchstens eine Korrektur des Werts
Die Empfehlung hat eine Prämie zu einer anderen Opportunity Folgeauftrag: neuer Eintrag, eigene Prämie; die erste bleibt unberührt
Die Empfehlung hat eine Prämie ohne Opportunity-ID (von Hand im Portal vergeben) gleicher Betrag: gilt als derselbe Auftrag, die ID wird nachgetragen · anderer Betrag: 409 opportunity_unassigned

Was Sie dazu wissen sollten:

  • Ausgabe. Bei einem neuen Folgeauftrag steht created: true in der Ausgabe, follow_up_of nennt
    die ID der ursprünglichen Empfehlung, id ist die ID des Folgeauftrags. Bei einer Empfehlung ist
    follow_up_of leer.
  • Prämie. Gerechnet wird mit dem Satz, den der Tippgeber heute hat (oder mit „Commission Rate“ bzw.
    „Fixed Amount“) – nicht mit dem Satz, der beim ersten Auftrag galt.
  • Ohne Opportunity-ID gibt es keinen Folgeauftrag. Der Node bricht dann ab: Jeder wiederholte Lauf
    ergäbe sonst eine weitere Prämie.
  • Trigger. Ein Folgeauftrag löst „Reward Issued“ aus (und „Reward Paid“ mit „Mark as Paid“), aber
    nicht „Referral Created“ – der Kontakt ist nicht neu. In den Daten des Ereignisses steht
    referral.follow_up_of.
  • Suchen. „Find Referral By“ = Close Lead ID oder Lead Email meint immer die ursprüngliche
    Empfehlung. Ein Folgeauftrag wird über seine Referral ID angesprochen (die id aus der Ausgabe
    von „Issue“ oder aus dem Trigger) – etwa für Reward → Mark as Paid oder „Referral → Update“.
    „Issue“ selbst findet den richtigen Auftrag über die Opportunity-ID.
  • Ohne den Schalter bleibt alles wie bisher: Eine zweite Opportunity desselben Leads wird mit 409
    opportunity_conflict abgelehnt.
  • Im Portal lässt sich ein Folgeauftrag auch von Hand anlegen: Empfehlung öffnen → „Folgeaufträge“ →
    „Anlegen“.

Umstieg von 0.1.0

Vorhandene Nodes behalten in n8n ihre Version (1) und damit ihre bisherigen Vorgaben: „Find Referral
By“ = Lead Email, „Reward Basis“ mit getrenntem „Deal Value Unit“ = Euros. Hier ändert sich nichts
still. Bei „Issue“ einmal nachsehen, ob die Einheit zum Wert passt – ein Hinweis steht jetzt am Feld.
Neu eingefügte Nodes sind Version 2: Vorgabe Referral ID, die Einheit steckt in „Reward Basis“
(Vorgabe Cents), „External Opportunity ID“ ist ein sichtbares Feld.

Für alle Nodes, auch die vorhandenen, gilt ab 0.2.0:

Was Vorher Jetzt
Fehler mit „Continue On Fail“ / „On Error: Continue“ { error } mit wechselndem Text { error, code, status, details }; die Meldung ist die des Portals
„Referrer → Approve“ bei deaktiviertem Konto Konto wurde wieder aktiv Fehler referrer_not_pending; reaktivieren über Update → Active
Leerer Status in „Referral → Update“ stillschweigend übergangen 422 vom Portal
„Deal Value“ / „Fixed Reward“ = 0 in „Referral → Update“ Prämie entfiel abgelehnt, außer mit „Allow Removing the Reward“
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“
Vorgabe neu hinzugefügter Zahlenfelder (Deal Value, Fixed Reward, Commission Rate, Amount) 0 bzw. 10 leer
Leerer Suchwert, leere ID Fehler des Portals bzw. Aufruf der Listen-Route klare Meldung des Nodes, nichts wird gesendet
Ausgabe von „Create“ nur der Datensatz zusätzlich created; bei „Issue“ zusätzlich reopened
„Updated Since“ ohne Zeitzone als UTC gelesen in der Zeitzone des Workflows gelesen
Adresse des Portals mit http:// wurde benutzt abgelehnt (außer localhost)
Trigger: Ausgabe event, sent_at, triggered_by, Daten zusätzlich event_id
Trigger: „Test senden“ am aktiven Workflow startete den Workflow wird nur bestätigt
Trigger: Workflow ohne gespeichertes Geheimnis ließ alles durch weist alles ab (401)
Trigger: im Portal pausiert n8n zeigte „aktiv“ Aktivieren scheitert mit Meldung

Zugangsdaten und Trigger bleiben, wie sie sind: Workflows müssen nach dem Update nicht neu aktiviert
werden.

Entwicklung

npm install
npm run lint     # Prüfung mit dem offiziellen n8n-Werkzeug
npm run build    # nach dist/
npm run dev      # startet ein lokales n8n mit den Nodes auf http://localhost:5678
npm pack         # erzeugt die .tgz für die Installation

Aufbau: credentials/ (Zugangsdaten), nodes/LkTippgeber/ (Action-Node, Felder in
descriptions.ts, HTTP-Aufrufe und Fehlerbehandlung in GenericFunctions.ts),
nodes/LkTippgeberTrigger/ (Trigger).

Prüfen ohne n8n und ohne laufendes Portal: node .claude/checks/a9-runde2-check.js im Projektordner
(nach npm run build). Gegen eine laufende lokale Instanz: .claude/checks/n8n-harness.js.

  • Keine Portal-Adresse im Paket: Das Feld „Base URL“ der Zugangsdaten ist nicht vorbelegt; die Hilfe-Links
    zeigen auf die Seite des Pakets bei npm. Zugangsdaten, die mit einer früheren Fassung angelegt wurden und in
    denen die damals vorbelegte Adresse nie geändert wurde, nach dem Update einmal öffnen und die Adresse prüfen.
  • Lizenz: MIT, siehe LICENSE.
  • Zwei Versionen des Nodes: Wer eine Vorgabe ändert, legt dafür eine neue Version an (siehe Kopf
    von descriptions.ts) – n8n speichert Werte nicht, die der Vorgabe entsprechen, eine geänderte
    Vorgabe würde vorhandene Workflows also still umstellen.

Discussion