02 Retouren-Check v2¶

ℹ️ v2 seit 14.05.2026 produktiv. Vorgängerversion v1 (9qzWLsxK4GhEgrTN) ist abgelöst — sie hatte den n8n Cloud Starter 60s-Code-Node-Hardlimit gerissen sobald ≥60 fällige Sendungen anstanden (0 Items prozessiert, kein Sheet-Update, 3 Min Wall-Clock-Zeit). v2 löst das mit SplitInBatches+Wait-Pattern für DHL. Plus Prime-Branch für Amazon-RSA-Retouren. Liegt im Folder 02 Retourencheck in Susi Projects.

Wird vom DAILY mokebo-ops Sync automatisch befüllt — bitte nicht manuell editieren.

Status: ✓ Live (v2) Letzter Erfolgs-Run: — Erfolgsquote 7d: — Trigger: Cron, täglich 9:00 Uhr Node-Count: —

🟢 Auf einen Blick¶

Architektur¶

flowchart TB
  Cron[Cron 9:00] --> GLSToken[GLS Token holen
früh am Start]
  GLSToken --> SheetRead[Fällige Checks holen
Sheet 'Tracking']
  SheetRead --> Filter[naechster_check ≤ heute]
  Filter --> Switch{Switch by Carrier}
  Switch -- GLS --> GLSCode[GLS Tracking
parallel im Code-Node]
  Switch -- DHL --> DHLLoop[SplitInBatches 1
+ HTTP + Code + Sheet + Wait]
  Switch -- GLS-Prime / DHL-Prime --> Prime[Prime markieren
status: amazon_extern]
  GLSCode --> Merge[GLS+DHL+Prime Sync
3-Input Merge]
  DHLLoop --> Merge
  Prime --> PrimeSheet[Prime Sheet-Update]
  PrimeSheet --> Merge
  Merge --> StatusDecide[Status entscheiden]
  StatusDecide --> SheetUpd[Sheet pro Item updaten]
  SheetUpd --> EndState{End-Zustand?}
  EndState -- zugestellt --> ZdGutschrift[Zendesk: Gutschrift erstellen]
  EndState -- in_transit_überfällig --> ZdNachfrage[Zendesk: Carrier-Nachfrage]
  EndState -- nicht_versendet_geschlossen --> ZdAbgeschlossen[Zendesk: 21d nicht versendet]
  ZdGutschrift --> ClearCheck[naechster_check leeren
für alle Gruppen-Pakete]
  ZdNachfrage --> ClearCheck
  ZdAbgeschlossen --> ClearCheck
  ClearCheck --> WriteTicket[Ticket-ID zurück ins Sheet]

Subworkflow-Calls¶

Auto-generiert aus den executeWorkflow-Nodes — bitte nicht manuell editieren.

• (keine — eigenständiger Workflow)

Trigger & Datenfluss¶

• Trigger: Cron, täglich 9:00 Uhr.
• Quelle: Sheet Retouren-Tracking, Tab Tracking (gleiches Sheet wie 01).
• APIs:
• GLS: POST https://api.gls-group.net/oauth2/v1/token (Token früh am Start), dann GET …/track-and-trace-v1/tracking/simple/trackids/{nr}?showEvents=true — alle GLS-Items in einem Code-Node sequenziell.
• DHL: GET https://api-eu.dhl.com/track/shipments?trackingNumber={nr} mit DHL-API-Key-Header — pro Item ein eigener Pipeline-Durchlauf via SplitInBatches(1) → HTTP Request → Code → Sheet-Update → Wait(5.5s).
• Zendesk: Ticket-Create bei drei End-Zuständen.
• Sheet-Update pro Item statt batch — committet Progress sofort, auch wenn der Workflow das 5-Min-Limit reißen würde.

Status-Lebenszyklus¶

stateDiagram-v2
  [*] --> offen: 01 schreibt
  offen --> in_transit: Carrier sagt 'transit'
  offen --> nicht_versendet_geschlossen: 21 Tage + immer noch not_shipped
  offen --> amazon_extern: GLS-Prime / DHL-Prime erkannt
  in_transit --> zugestellt: delivered
  in_transit --> in_transit_ueberfaellig: 10 Tage transit
  zugestellt --> ticket_erstellt: Gutschrift-Ticket erzeugt
  in_transit_ueberfaellig --> ticket_erstellt: Nachfrage-Ticket
  nicht_versendet_geschlossen --> ticket_erstellt: Abschluss-Ticket
  amazon_extern --> [*]: kein weiteres Tracking
  ticket_erstellt --> [*]

Sieben Stati: offen, in_transit, zugestellt, in_transit_ueberfaellig, nicht_versendet_geschlossen, amazon_extern (neu in v2), ticket_erstellt.

Rate-Limit-Konstanten (aktueller Übergangs-Patch)¶

In Tracking prüfen + Status bestimmen Code-Node (Stand 13.05.2026):

Grund: DHL Default Free Tier = 250 Calls/Tag + 1 Call/5s Spike Arrest. Vor Patch feuerten wir 10× zu schnell. Nach DHL-Upgrade-Approval (siehe Asana-Task) Konstanten zurückdrehen.

Bekannte Stolpersteine / Edge-Cases¶

• n8n Cloud Starter 60s-Code-Node-Hardlimit war der Grund für den v2-Refactor. Bei ≥60 fälligen Items lief der alte Mega-Code-Node ins Timeout. v2 löst das mit SplitInBatches+Wait-Pattern. Wichtig: Wenn du Logik in v2 zurück in einen einzigen Code-Node stopfst, kommt das Problem zurück.
• GLS PREADVICE = Label registriert, Paket noch nicht abgegeben → not_shipped, NICHT transit. War lange falsch klassifiziert. Fix 12.05.2026. In entscheideStatus zusätzlich inTransitSeit = '' Reset im not_shipped-Branch.
• Carrier-Patch (12.05.): (data.carrier || '').toUpperCase().startsWith('DHL'/'GLS') statt === 'DHL'/'GLS'. Routet auch DHL-Prime, GLS-Prime, GLSShipping korrekt — Prime-Items landen aber im neuen Prime-Branch (siehe Architektur).
• Prime-Branch für GLS-Prime + DHL-Prime markiert Items mit status: 'amazon_extern' und überspringt das Tracking. Verhindert ewige Filter-Schleifen für Amazon-RSA-Items. Wenn du Hermes als Prime-Variante hinzufügst (Phase 2 von SUB Retoure), müsstest du diesen Branch erweitern.
• Amazon-Retouren werden öfter geprüft: naechster_check = heute + 2 für Referrer 4.01 (Amazon Germany), +7 für Rest. Logik in 01 Retouren-Erfassung.
• DHL-API-Key hardcoded im Code-Node (YHUf5olNW7whASeQGu1HT99VpTmCqkJ0, App mkb_retouren_tracking) → bei Rotation Code-Node manuell editieren. Empfehlung: nach n8n-Credential umziehen (siehe Empfehlungen-Section).
• DHL 429-Behandlung in v2: Retry-Backoffs [6000, 12000, 30000] ms — bei 429 werden bis zu 3 Retries mit zunehmenden Pausen gemacht. Wenn alle scheitern: Item bleibt unverändert, fließt morgen wieder rein.
• Mapping-Resolver-Issue (14.05.): n8n's AI-Builder hatte beim ersten create_workflow_from_code 10 von 16 Sheet-Update-Mappings von $json.foo auf $('Fällige Checks holen').item.json.foo umgemodelt → Sheet-Update scheiterte mit "Paired item data unavailable". Fix: GLS Token holen ganz an den Workflow-Start verschoben + Sample-Outputs aller Code-Nodes auf alle 16 Felder erweitert + pairedItem-Tracking in jedem Code-Node.
• Ticket-Erstellung leert naechster_check für alle Pakete der Gruppe (v2-Feature). Vorher blieb das Datum stehen, sichtbar im Sheet als Inkonsistenz.

Empfehlungen — noch nicht umgesetzt¶

Aus retouren check/retouren-workflows-empfehlungen.md im Hauptordner. Priorisiert nach Aufwand/Wirkung:

Debug-Anleitung¶

1. n8n → 02 Retouren-Check v2 → Executions → Filter heute + Failed.
2. Wenn Run grün aber Sheet nicht geupdatet pro Item: schau in einen DHL-Loop-Iteration ob die Sheet-Update-Mapping-Expressions als $json.foo (nicht $('Fällige Checks holen').item.json.foo) stehen. Wenn umgemodelt → Mapping-Resolver-Issue (siehe Stolpersteine).
3. Wenn Carrier-spezifischer Fehler: schau, ob GLS Token holen lief (am Start, vor Switch).
4. Wenn DHL-Calls 429 werfen: einzelne Items werden geskippt, fließen morgen wieder rein — sehen letztes_tracking_event = "SKIPPED: DHL-API gedrosselt".
5. Bei Workflow-Crash: 00 Error-Notifier (WEmKVe9EjmwVJzKa) postet automatisch in #03_customer-support (sofern in Workflow-Settings als Error Workflow gesetzt).

Entscheidungen / Geschichte¶

• 2026-05-14: v2-Refactor live. SplitInBatches+Wait für DHL, GLS parallel, Sheet-Update pro Item, Prime-Branch für GLS-Prime/DHL-Prime → amazon_extern. Workflow-ID OZV6aC8jzVAQMAES im Folder 02 Retourencheck. Vorgängerversion v1 (9qzWLsxK4GhEgrTN) deprecated wegen 60s-Hardlimit. Zwischenversion sPGNJxFM8TUgkNiP archiviert.
• 2026-05-14: Mapping-Resolver-Issue gefixt (GLS-Token an Start + pairedItem-Tracking + 16-Felder Sample-Outputs).
• 2026-05-14: Feature-Erweiterung Ticket-Erstellung — leert naechster_check für alle Gruppen-Pakete (verhindert Inkonsistenz).
• 2026-05-13: REASON_MAP [OLD]-Markierung in 01 Retouren-Erfassung — Plenty hat Legacy-IDs markiert.
• 2026-05-13: COUNTRY_MAP 21: 'NL — Niederlande' ergänzt (mokebo-spezifisch, weicht von Plenty-Default 25 ab).
• 2026-05-13: Übergangs-Patch DHL Rate Limit (Konstanten siehe oben).
• 2026-05-12: Carrier-Patch (startsWith statt ===) für DHL-Prime / GLS-Prime-Unterstützung.
• 2026-05-12: GLS PREADVICE als not_shipped statt transit klassifizieren.
• (älter): 21 Tage als Cutoff für nicht_versendet_geschlossen, 10 Tage transit als in_transit_ueberfaellig-Schwelle.

Verwandte Workflows¶

• 01 Retouren-Erfassung — schreibt die Zeilen, die v2 dann trackt.
• SUB Retoure — legt Amazon-RSA-Retouren in Plenty an, die v1 dann als Prime-Items sieht.
• 00 Error-Notifier (WEmKVe9EjmwVJzKa) — zentraler Error-Handler. Postet bei Workflow-Crashes nach #03_customer-support. Liegt in Susi Projects, ggf. noch nicht in allen Workflow-Settings als Error Workflow gesetzt.