247APPS

easyReturns Benutzerhandbuch

Shopify Flow mit easyReturns verwenden

Zuletzt aktualisiert:

Mit Shopify Flow kannst du auf Ereignisse aus easyReturns reagieren, zum Beispiel eine Nachricht senden oder eine Bestellung kennzeichnen. Die Automation wird in Shopify Flow eingerichtet, nicht in den easyReturns-Einstellungen.

Voraussetzungen

  • Shopify Flow ist für deinen Shop verfügbar und installiert.
  • easyReturns ist im Shop installiert und authentifiziert.
  • Der zugrunde liegende Retouren- oder Widerrufsworkflow ist eingerichtet.

Flow erstellen

  1. Öffne Shopify Flow im Shopify-Admin.
  2. Erstelle einen neuen Workflow.
  3. Wähle einen easyReturns-Trigger.
  4. Ergänze Bedingungen und die gewünschte Shopify-Flow-Aktion.
  5. Speichere und aktiviere den Workflow.
  6. Löse das Ereignis mit einem geeigneten Testvorgang aus.
  7. Prüfe Ausführung und Ergebnis im Shopify-Flow-Protokoll.

Verfügbare Ereignisse

easyReturns stellt Ereignisse für folgende Workflowphasen bereit:

  • Retourenanfrage eingegangen,
  • Retoure erstellt beziehungsweise genehmigt,
  • Retoure abgelehnt,
  • Retoure durch den Kunden storniert,
  • Retoure geschlossen,
  • Label erstellt,
  • Wareneingang vollständig,
  • Widerruf eingegangen,
  • Widerruf genehmigt,
  • Widerruf abgelehnt.

Welche Daten ein Trigger bereitstellt, siehst du bei seiner Auswahl in Shopify Flow.

Einheitliche Retouren-Trigger

Alle acht Retouren-Trigger verwenden dieselben Datenfelder. Bestehende Handles, Order-Referenzen, URLs und die bisherigen Felder unter Return bleiben erhalten.

Trigger Ausloeser
Return requested (return-requested) Tatsaechlicher Wechsel zu REQUESTED, auch bei automatischer Genehmigung; bei Umwandlung eines Widerrufs erst nach vollstaendiger Artikelanlage
Return created (return-created) Eine neue Shopify-Return-ID wird am Vorgang gespeichert
Return approved (return-approved) Wechsel zu OPEN durch Genehmigung; Wiedereroeffnung desselben geschlossenen Returns ist keine erneute Genehmigung
Return declined (return-declined) Wechsel zu DECLINED, mit gespeichertem Ablehnungsgrund
Return closed (return-closed) Wechsel zu CLOSED, auch bei Abschluss durch Shopify und anschliessender Synchronisation
Return canceled by customer (return-canceled-by-customer) Wechsel zu CANCELED_BY_CUSTOMER, getrennt von einer Haendlerablehnung
Label created (label-created) Ein neues Label und gegebenenfalls sein QR-Code wurden erfolgreich gespeichert
Goods Received - Wareneingang (goods-received) Die empfangenen Mengen wechseln von unvollstaendig zu vollstaendig

Gemeinsame Retourendaten

Feld Inhalt
Order-Referenz Shopify-Bestellung, in Flow als order verfuegbar
Retoure / Bestellnummer Retouren-UUID / sichtbare Bestellnummer
Status / PreviousStatus Neuer / vorheriger Retourenstatus; vor dem ersten Status ist der vorherige Wert leer
EventType Trigger-Handle, beispielsweise label-created; unterscheidet auch Ereignisse mit demselben Status
EventId / OccurredAt Ereignis-UUID / Zeitpunkt im ISO-8601-Format mit Zeitzone
Email / Name Kunden-E-Mail / Kundenname aus den Bestellmetadaten, soweit vorhanden
Datum / Uhrzeit Erstellungsdatum und -uhrzeit der Retoure
Portal URL / App URL Kundenportal / Haendleransicht
Ablehnungsgrund Gespeicherte Ablehnungs- beziehungsweise Kundenstornonotiz, sonst leer
Return.shopifyId / Return.name Shopify-Return-GID / Retourenname, sofern bereits angelegt
Return.comment / Return.images Kundenkommentar / hochgeladene Dateien mit url
Return.items Artikel mit name, quantity, receivedQuantity, reason und returnOption
Return.provider Eingestellter Rueckversandanbieter
Return.trackingNumber / Return.trackingUrl Trackingdaten des Labels, soweit vorhanden

Status-, Artikel-, Datei- und Trackingdaten bilden einen Snapshot des jeweiligen Ereignisses. Bei Label- und Wareneingangsereignissen bleibt Status normalerweise unveraendert; PreviousStatus entspricht dann Status.

Wichtige Unterschiede zur bisherigen Ausloesung

  • Status-Trigger werden erst nach erfolgreichem Speichern und Datenbank-Commit versendet. Wiederholtes Speichern desselben Status sowie Rollbacks erzeugen kein weiteres Statusereignis.
  • Return approved wird nicht mehr nochmals durch die Labelerstellung ausgeloest. Wenn ein Workflow auf ein verfuegbares Label angewiesen ist, verwende Label created. Bei der Genehmigung muss noch kein Label vorliegen.
  • Return created und Return approved sind unterschiedliche Ereignisse und koennen beide bei demselben Genehmigungsvorgang auftreten. Abonniere fuer dieselbe externe Aktion nicht beide, wenn sie nur einmal ausgefuehrt werden soll.
  • Der Wareneingangsjob wird erst nach Commit eingereiht, wartet weiterhin zehn Sekunden und prueft erneut, ob alle Artikel vollstaendig empfangen sind. Seine Daten, Ereigniszeit und Event-ID stammen bereits vom ausloesenden Mengenwechsel. Bei einer Wiederholung desselben Jobs bleibt die Event-ID erhalten.
  • Eine neu vorgenommene vollstaendige Wareneingangsbuchung nach zwischenzeitlicher Mengenreduzierung ist ein neues Ereignis. Eine globale Exactly-once-Zustellung oder Reihenfolgegarantie besteht nicht; der Empfaenger muss EventId zur Deduplizierung verwenden.
  • Fuer Wiedereroeffnung, allgemeine Retourenaenderungen und Haendlerstornierung werden keine neuen Trigger eingefuehrt.

Retouren per HTTP weiterleiten

Die unten beschriebene Aktion Send HTTP request, ihre Tarifvoraussetzung und ihre Fehlerbehandlung gelten ebenso fuer Retouren. Waehle einen der oben genannten Retouren-Trigger und verwende beispielsweise diesen Body:

{
  "event_id": {{ eventId | json }},
  "event_type": {{ eventType | json }},
  "occurred_at": {{ occurredAt | json }},
  "return_id": {{ retoure | json }},
  "order_id": {{ order.id | json }},
  "status": {{ status | json }},
  "previous_status": {{ previousStatus | json }},
  "decline_reason": {{ ablehnungsgrund | json }}
}

Fuege weitere Artikel- und Trackingfelder ueber den Flow-Variablenwaehler hinzu. Shopify wandelt die Feldnamen fuer Liquid in camelCase um. Die erweiterten Extensions muessen zusammen mit dem Backend bereitgestellt und die Workflows im Testshop geprueft werden; die Bereitstellung ist unten beschrieben.

Widerrufsstatus an ein eigenes System senden

Die easyReturns-Trigger reichen aus, um einen externen Dienst per HTTP ueber die drei fachlichen Widerrufsstatus zu informieren. Eigene Shopify-Webhook-Themen fuer Widerrufe sind dafuer nicht erforderlich. Der Haendler abonniert ein Ereignis, indem er den entsprechenden Workflow in Shopify Flow aktiviert.

Tarifvoraussetzung: Shopify Flow und die Aktion Send HTTP request muessen verfuegbar sein. Laut Shopify ist diese Aktion nur in Grow, Advanced und Plus, nicht in Basic, enthalten. Diese Grenze betrifft den Shopify-Tarif, nicht den easyReturns-Tarif.

Abgleich mit Shopify-Return-Webhooks

Shopify-Returns und rechtliche Widerrufe sind unterschiedliche Vorgaenge. Die folgenden Entsprechungen sind fachliche Zuordnungen; easyReturns registriert damit keine neuen Shopify-Webhook-Themen.

Shopify-Thema Widerrufsphase easyReturns-Flow-Trigger
RETURNS_REQUEST Eingereicht: created → requested Withdrawal requested (withdrawal-requested)
RETURNS_APPROVE Genehmigt: Wechsel zu approved Withdrawal approved (withdrawal-approved)
RETURNS_DECLINE Abgelehnt: Wechsel zu declined Withdrawal declined (withdrawal-declined)
RETURNS_CANCEL Kein eigener Widerrufsstatus Kein entsprechender Trigger; Bestellstorno ist ein separater Vorgang
RETURNS_CLOSE Kein eigener Widerrufsstatus Ein genehmigter Widerruf wird nicht spaeter als Widerruf geschlossen
RETURNS_REOPEN Kein eigener Widerrufsstatus Kein eigener Wiedereroeffnungsprozess fuer Widerrufe
RETURNS_PROCESS Retourenabwicklung, kein Widerrufsstatus Gegebenenfalls Ereignisse der verknuepften Retoure verwenden
RETURNS_UPDATE Allgemeine Aenderung, kein einzelner Status Kein allgemeiner Widerrufs-Update-Trigger

created ist ein noch nicht eingereichter Entwurf und loest keinen Trigger aus. Das Loeschen eines Entwurfs ist kein RETURNS_CANCEL. Eine spaeter aus einem Widerruf erzeugte Retoure hat einen eigenen Lifecycle.

Einheitliche Daten der drei Widerrufs-Trigger

Alle drei Trigger stellen dieselben Felder bereit. Bestehende Handles und Felder bleiben erhalten:

Feld Inhalt
Order-Referenz Shopify-Bestellung, in Flow als order verfuegbar
Widerruf Eindeutige UUID des Widerrufs
Bestellnummer Sichtbare Bestellnummer
Status / PreviousStatus Neuer / vorheriger Status, beispielsweise approved / requested
EventId UUID dieses Statusereignisses, zur Deduplizierung beim Empfaenger
OccurredAt Zeitpunkt des Statusereignisses im ISO-8601-Format mit Zeitzone
Email / Name E-Mail-Adresse / Name des Kunden
Datum / Uhrzeit Erstellungsdatum und -uhrzeit des Widerrufs, nicht des Statuswechsels
URL Oeffentliche Detail-URL des Widerrufs
Ablehnungsgrund Gespeicherter Ablehnungsgrund, sonst leere Zeichenfolge
Withdrawal.reason / Withdrawal.comment Widerrufsgrund / Kundenkommentar
Withdrawal.items Ausgewaehlte Artikel mit name und ganzzahliger quantity; Mengen von null werden nicht uebertragen

Der interne Haendlerkommentar wird nicht uebertragen. Artikel und Kommentare sind ein Snapshot zum Zeitpunkt des jeweiligen Statuswechsels.

HTTP-Workflow einrichten

  1. Erstelle einen Workflow mit easyReturns → Withdrawal requested.

  2. Fuege die Aktion Send HTTP request hinzu.

  3. Waehle POST und die HTTPS-URL deines eigenen Empfangsdienstes.

  4. Setze Content-Type: application/json. Falls dein Dienst einen Token verwendet, hinterlege ihn unter Flow → Settings → Secrets und verwende beispielsweise Authorization: Bearer {{secrets.easyreturns_endpoint_token}}. Verwende keine offen eingetragenen Zugangsdaten.

  5. Fuege die benoetigten Triggerdaten ueber Variable hinzufuegen in den Body ein. Beispielsweise:

    {
      "event_id": {{ eventId | json }},
      "occurred_at": {{ occurredAt | json }},
      "withdrawal_id": {{ widerruf | json }},
      "order_id": {{ order.id | json }},
      "status": {{ status | json }},
      "previous_status": {{ previousStatus | json }},
      "decline_reason": {{ ablehnungsgrund | json }}
    }
    

    Shopify Flow wandelt die Feldnamen fuer Liquid-Variablen in camelCase um. Nutze die von Flow im Variablenwaehler erzeugten Pfade, falls die Darstellung abweicht. Der json-Filter sorgt fuer korrektes Escaping, insbesondere bei Anfuehrungszeichen und Zeilenumbruechen. Uebertrage Kundendaten und Artikel nur, wenn dein Empfangsdienst sie benoetigt.

  6. Konfiguriere die Fehlerbehandlung: beispielsweise bei 5xx und 429 Retry, bei permanenten 4xx Fail. Die Aktion wartet maximal 30 Sekunden auf eine Antwort; bei entsprechender Konfiguration wiederholt Shopify fehlgeschlagene Requests bis zu 24 Stunden.

  7. Aktiviere den Workflow und pruefe ihn mit einem Testwiderruf im Flow-Ausfuehrungsprotokoll und deinem Empfangsdienst.

  8. Wiederhole die Einrichtung fuer Withdrawal approved und Withdrawal declined. Alle drei koennen dieselbe Empfangs-URL und denselben JSON-Aufbau verwenden.

Der Empfaenger sollte nach Annahme schnell mit 2xx antworten und wiederholte Zustellungen anhand von event_id idempotent verarbeiten. Eine erneute fachliche Statusaenderung desselben Widerrufs erhaelt eine neue Event-ID. Die zeitliche Reihenfolge der externen HTTP-Zustellung ist nicht garantiert.

Ausloeseverhalten und Bereitstellung

  • Der Trigger entsteht erst nach erfolgreichem Speichern und Datenbank-Commit des Statuswechsels. Ein Rollback loest keinen Flow aus.
  • Erneutes Speichern desselben Status oder Aenderungen nur an Kommentaren loesen keinen weiteren Status-Trigger aus.
  • Eine automatische Genehmigung erzeugt sowohl Withdrawal requested als auch Withdrawal approved, jeweils mit eigenem Status-Snapshot. Scheitert die Genehmigung, entsteht nur Withdrawal requested.
  • Es werden keine Ereignisse fuer bereits vorhandene historische Status nachgesendet.
  • Die erweiterten Flow-Extensions muessen zunaechst mit Shopify CLI gegen die Test-App geprueft und anschliessend zusammen mit dem Backend veroeffentlicht werden. Fuer Produktion ist die Konfiguration shopify.app.prod.toml vorgesehen; der Release erfolgt nach Freigabe mit shopify app deploy --config prod. Erst danach stehen die neuen Felder in produktiven Workflows zur Verfuegung. Vorhandene Workflows behalten ihre bisherigen Felder; zusaetzliche Daten muessen in ihren Aktionen ausgewaehlt werden.
  • Der lokale Queue-Dispatch ist automatisiert getestet. Die reale Ausfuehrung in Shopify Flow und die Zustellung an den Haendler-Endpunkt muessen nach dem Extension-Deployment im Testshop geprueft werden.

Shopify-Referenzen

Wichtige Hinweise

  • Kundenbenachrichtigungen von easyReturns und Shopify Flow sind getrennte Systeme. Beide können auf denselben Statuswechsel reagieren.
  • easyReturns stößt den Trigger an; Ausführung, Bedingungen, Aktionen und Protokolle liegen anschließend bei Shopify.
  • Plane Flow-Aktionen so, dass eine wiederholte Ausführung keine unerwünschten Folgen hat.

Verwandte Themen