npm package: @t4dt/n8n-nodes-t4data-cloud-messages
Description: n8n module for t4data.cloud Messages API
Author: Robert Wall | T4DT GmbH
Latest version: 2.2.1

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

[n8n](https://n8n.io/) 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](https://supabase.com/docs/guides/auth/oauth-server/oauth-flows#refresh-request)), 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](https://portal.t4data.cloud) (Hinweis in den Credentials als `documentationUrl`)
- [n8n: Community Nodes](https://docs.n8n.io/integrations/community-nodes/installation/)
- Repository: siehe `package.json` → `repository.url`

## Lizenz

MIT (siehe Lizenzangabe im Paket).

## Support

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