@t4dt/n8n-nodes-t4data-cloud-messages

n8n Community Node für die t4data.cloud Messages- und Partner-API. Workflows können Nachrichten anlegen, abrufen, listen und als exportiert markieren sowie Partner inklusive GLN-Verknüpfungen abrufen.

Voraussetzungen

• n8n Version 2.x (empfohlen; der Node nutzt die aktuelle n8n-workflow-API).
• Zugangsdaten für die t4data.cloud API (OAuth2 API; dieselben Credentials für Messages und Partner).
• Berechtigung zur Installation von Community Nodes (je nach Hosting: Einstellung in der n8n-Instanz).

Installation

Über die n8n-Oberfläche (empfohlen)

1. Einstellungen → Community Nodes.
2. Install / Node installieren.
3. Paketname eingeben: @t4dt/n8n-nodes-t4data-cloud-messages
4. Nach der Installation n8n ggf. neu laden oder Seite aktualisieren.

Zugangsdaten: „t4data.cloud OAuth2 API“

Der Node verwendet den Credential-Typ t4data.cloud OAuth2 API. Er kombiniert OAuth2 (PKCE) mit einem öffentlichen Client-Schlüssel im Header apikey.

Pflichtfelder und Standard-Host

| Feld | Beschreibung | |------|----------------| | Use custom API base URL | Standard an (true): Ihr tragt eine eigene API-Basis-URL ein (bestehende Setups bleiben unverändert). Aus (false): Es wird die fest hinterlegte t4data.cloud-API unter https://api.t4data.cloud verwendet; die Felder API base URL und die OAuth-URLs dazu sind dann nicht nötig bzw. ausgeblendet. | | API base URL | Nur bei Use custom API base URL = an: vollständige Basis-URL ohne abschließenden Slash, z. B. https://ihre-api.example.com. Kein Pfad wie /auth/v1 anhängen. | | Publishable Key | Öffentlicher Client-Schlüssel für den Header apikey (wie im t4data.cloud-Portal dokumentiert). |

Die OAuth-Endpunkte ergeben sich aus der gewählten Basis (Standard-Host oder eigene URL):

• Authorization: {Basis-URL}/auth/v1/oauth/authorize
• Token: {Basis-URL}/auth/v1/oauth/token

OAuth2-Felder (Standard-n8n-Maske)

Je nach eurer OAuth-/Identity-Provider-Konfiguration tragt ihr zusätzlich ein:

• Client ID und Client Secret; PKCE ist voreingestellt.
• Die Redirect-URL, die n8n nach dem Login anzeigt bzw. in der Dokumentation zu eurem n8n-Setup steht, muss in den Redirect URLs der Auth-Konfiguration (bzw. eures IdP) erlaubt sein.

Grant Type ist im Credential als PKCE vorbelegt. Wenn ihr ein älteres Credential noch mit „Authorization Code“ ohne PKCE habt, legt die Zugangsdaten neu an oder verbindet sie erneut.

Verbindung testen

Über Test in den Credentials prüft n8n u. a. den Aufruf GET /auth/v1/user gegen eure API-Basis-URL. Schlägt der Test fehl, zuerst URL, Key und OAuth-Redirect prüfen.

Access-Token und automatischer Refresh

Die Auth liefert kurzlebige Access-Tokens (häufig etwa eine Stunde). Vor jedem API-Aufruf prüft der Node das JWT (exp) und refresht bei Bedarf über POST …/auth/v1/oauth/token mit Header apikey, in dieser Reihenfolge: bei gesetztem Client Secret zuerst confidential (Authorization: Basic … bzw. client_secret im Form-Body, siehe Supabase OAuth-Server / Refresh), sonst public (client_id + refresh_token im Body), danach optional GoTrue-Fallback …/auth/v1/token?grant_type=refresh_token mit JSON. Meldungen wie „Client authentication required“ bedeuten: OAuth-Client ist confidential — Client Secret in den n8n-Zugangsdaten eintragen.

Läuft die Verbindung trotzdem ab, typische Ursachen sind: abgelaufenes oder widerrufenes Refresh-Token, geänderte Client ID / Secret, oder Einschränkungen beim Identity-Provider.

Ressource: Message

| Operation | API (Kurz) | Zweck | |-----------|------------|--------| | Create | POST /functions/v1/message | Neue Nachricht mit Typ, Empfänger und JSON-Payload anlegen. | | Mark as Exported | PUT /functions/v1/message/{id}/exported | Nachricht als exportiert markieren. | | Get | GET /functions/v1/message/{id} | Eine Nachricht per UUID laden. | | Get Many | GET /functions/v1/message | Liste mit Filtern; der Node lädt bei Bedarf mehrere API-Seiten automatisch nach (siehe unten). |

Felder je Operation (Message)

Create

• Message Type: Schlüssel des Nachrichtentyps (freie Zeichenkette, muss in eurer API erlaubt sein).
• Receiver ID: UUID des Empfängers (wird zur Laufzeit validiert).
• Data (JSON): Beliebiges JSON-Objekt als Nutzdaten der Nachricht.

Mark as Exported / Get

• Message ID: UUID der Nachricht.

Get Many

• Include Exported: Ob bereits exportierte Nachrichten in der Antwort enthalten sein sollen.
• Type Filter: Optional nur einen bestimmten message_type laden; leer = alle Typen.
• Created After / Created Before: Optionaler Zeitraumfilter (created_at).
• Limit: Maximale Anzahl Datensätze, die der Node insgesamt zurückgibt (Standard 50). Erlaubt sind positive Werte bis 1.000.000.

Ressource: Partner

Entspricht der Edge Function GET /functions/v1/partners (Benutzerkontext per OAuth; gleicher apikey-Header wie bei Messages).

| Operation | API (Kurz) | Zweck | |-----------|------------|--------| | Get Many | GET /functions/v1/partners | Alle für den angemeldeten Benutzer sichtbaren Partner inkl. GLN-Links in einem Aufruf laden. |

Felder je Operation (Partner)

Keine zusätzlichen Parameter; die Auswahl Resource → Partner und Operation → Get Many genügt.

Ausgabe (Partner)

Die HTTP-Antwort ist typischerweise { "partners": [ … ] }; der Node liefert pro Partner ein n8n-Item (mit pairedItem zum Eingabe-Item). Die Felder entsprechen der API, u. a.:

• Partner: id, name, active, created_at
• glns: Array flacher Verknüpfungen mit gln_id, gln (Nummer als String), is_primary, role, optional gln_created_at, link_created_at

Ausgabe und „ein Item vs. viele Items“

• Create, Mark as Exported, Get (Message): je Eingabe-Item typischerweise ein Ausgabe-Item mit JSON (bei Create u. a. die neue id).
• Get Many (Message): Es werden pro gefundener Nachricht ein n8n-Item erzeugt (alle mit Bezug zum gleichen Eingabe-Item über pairedItem), bis das konfigurierte Limit erreicht ist oder keine weiteren Daten kommen.
• Get Many (Partner): ein Item pro Partner aus der kompletten Partnerliste der API.

Struktur einer Nachricht in den JSON-Daten entspricht u. a. den Feldern id, created_at, data, exported_at, message_type, sender_id, receiver_id (wie von der API geliefert).

Pagination (Message: Get Many)

Gilt nur für Message → Get Many: Die API wird intern mit Seitengröße bis 1000 abgefragt. Setzt ihr z. B. Limit auf 2500, führt der Node mehrere Requests aus, bis 2500 Datensätze gesammelt oder keine weiteren Ergebnisse mehr vorliegen. So müsst ihr in n8n keine eigene Offset-Schleife bauen. Partner nutzt einen einzelnen GET-Aufruf ohne clientseitige Pagination.

Fehlerbehandlung

• Ungültige UUIDs für Message ID oder Receiver ID führen zu einer klaren Fehlermeldung im Node.
• HTTP-Fehler der API (4xx/5xx) werden als NodeOperationError mit Statuscode und API-Meldung ausgegeben.
• Mit Continue On Fail am Node werden Fehler pro Item als fehlerhafte Ausgabe weitergegeben, statt den gesamten Lauf zu stoppen.

Häufige Probleme

| Symptom | Mögliche Ursache | |--------|-------------------| | OAuth / PKCE-Fehler | Credential neu anlegen; Redirect-URL beim Identity-Provider prüfen; PKCE als Grant Type verwenden. | | 401 / 403 | Abgelaufenes Token: Verbindung erneuern; Publishable Key und OAuth-Client prüfen. | | Leere oder falsche OAuth-URLs | API base URL ohne Slash am Ende; Schema https:// nicht vergessen. | | Test schlägt fehl | Netzwerk/Firewall zur API; falsche Basis-URL; Auth für /auth/v1/user nicht freigegeben. |

Weitere Links

• t4data.cloud Portal (Hinweis in den Credentials als documentationUrl)
• n8n: Community Nodes
• Repository: siehe package.json → repository.url

Lizenz

MIT (siehe Lizenzangabe im Paket).

Support

Ansprechpartner und Firma siehe author in der package.json (T4DT GmbH).