Flows & Regeln — Plattform-API

Die Plattform-API ermöglicht die vollständige Verwaltung von Automatisierungsflows und Regeln über HTTP — für CI-Pipelines, externe Skripte oder eigene Integrationen.

Authentifizierung

Alle Endpunkte erfordern einen Bearer-API-Token im Authorization-Header:

Authorization: Bearer IHR_API_SCHLUESSEL

API-Schlüssel erstellen Sie unter Admin > Einstellungen > API-Schlüssel. Schreibende Operationen (POST, PATCH, DELETE) erfordern einen Schlüssel mit read_write-Berechtigung.

Weitere Informationen → API-Schlüssel.

---

Flow-Endpunkte

GET /api2/v1/flows — Flows auflisten

Gibt eine paginierte Liste aller Flows zurück.

Query-Parameter:

Parameter	Typ	Beschreibung
trigger	Text	Nur Flows mit diesem Trigger-Ereignistyp (z. B. order.placed)
enabled	true / false	Nur aktive oder inaktive Flows
page	Zahl	Seite (Standard: 1)
per_page	Zahl	Ergebnisse pro Seite (1–100, Standard: 20)

Beispielanfrage:

curl -H "Authorization: Bearer $API_KEY" \
  "https://ihreshop.de/api2/v1/flows?enabled=true&trigger=order.placed"

Beispielantwort:

{
  "items": [
    {
      "id": "abc-123",
      "name": "VIP-Bestellung",
      "trigger": "order.placed",
      "enabled": true,
      "priority": 10,
      "ruleId": null,
      "actionCount": 2,
      "lastExecutionAt": 1714302000,
      "lastExecutionStatus": "succeeded"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 20,
  "totalPages": 1
}

---

POST /api2/v1/flows — Flow erstellen

Erstellt einen neuen Flow mit Trigger, optionaler Regel und Aktionen-Array. Gibt den erstellten Flow mit Status 201 zurück.

Request-Body:

{
  "name": "Ausverkauft-Alarm",
  "trigger": "product.out_of_stock",
  "description": "Benachrichtigt das Team, wenn ein Produkt ausverkauft ist.",
  "enabled": true,
  "priority": 0,
  "ruleId": null,
  "actions": [
    {
      "type": "create_notification",
      "position": 0,
      "config": {
        "title": "Produkt ausverkauft: {{trigger.name}}",
        "message": "SKU {{trigger.sku}} hat keinen Bestand mehr."
      },
      "onError": "stop"
    }
  ]
}

Pflichtfelder: name, trigger

Aktions-Objekt:

Feld	Typ	Pflicht	Beschreibung
type	Text	Ja	Aktionstyp (z. B. send_email, webhook, conditional, llm_call)
position	Zahl	Ja	Position innerhalb des Eltern-Scopes
config	Objekt	Nein	Aktionskonfiguration (typspezifisch)
parentId	UUID	Nein	Eltern-Aktions-ID für Bedingungsverzweigungen
branch	Text	Nein	Verzweigungsname (then, else, else-if-0)
outputVariable	Text	Nein	Variablenname für das Aktionsergebnis
onError	Text	Nein	stop (Standard), continue oder retry

---

GET /api2/v1/flows/:id — Einzelnen Flow abrufen

Gibt den vollständigen Flow mit Aktionen-Array zurück.

curl -H "Authorization: Bearer $API_KEY" \
  "https://ihreshop.de/api2/v1/flows/abc-123"

---

PATCH /api2/v1/flows/:id — Flow aktualisieren

Aktualisiert ausgewählte Felder eines Flows. Nicht übermittelte Felder bleiben unverändert. Wird actions übergeben, ersetzt es alle bestehenden Aktionen.

curl -X PATCH \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false, "priority": 5}' \
  "https://ihreshop.de/api2/v1/flows/abc-123"

---

DELETE /api2/v1/flows/:id — Flow löschen

Löscht einen Flow dauerhaft. Gibt 204 No Content zurück. Die Ausführungshistorie bleibt zu Prüfzwecken erhalten.

curl -X DELETE \
  -H "Authorization: Bearer $API_KEY" \
  "https://ihreshop.de/api2/v1/flows/abc-123"

---

POST /api2/v1/flows/:id/toggle — Flow aktivieren/deaktivieren

Wechselt den enabled-Status des Flows.

Antwort:

{ "enabled": false }

---

POST /api2/v1/flows/:id/duplicate — Flow duplizieren

Erstellt eine Kopie des Flows mit allen Aktionen ("(Copy)" wird an den Namen angehängt). Die Kopie startet deaktiviert. Gibt den neuen Flow mit Status 201 zurück.

---

POST /api2/v1/flows/:id/test — Testausführung starten

Stellt eine Testausführung mit Beispiel-Triggerdaten in die Warteschlange. Gibt die neue Ausführungs-UUID zurück (Status 201).

Antwort:

{ "executionId": "exec-xyz-789" }

---

GET /api2/v1/flows/:id/executions — Ausführungshistorie abrufen

Gibt die paginierte Ausführungshistorie eines Flows zurück.

Query-Parameter:

Parameter	Beschreibung
status	queued, running, succeeded, failed, cancelled, delayed
page	Seite (Standard: 1)
per_page	Ergebnisse pro Seite (Standard: 20)

Beispielantwort:

{
  "items": [
    {
      "id": "exec-xyz-789",
      "flowId": "abc-123",
      "status": "succeeded",
      "trigger": "product.out_of_stock",
      "startedAt": 1714302000,
      "finishedAt": 1714302003
    }
  ],
  "total": 12,
  "page": 1,
  "perPage": 20,
  "totalPages": 1
}

---

Regel-Endpunkte

GET /api2/v1/rules — Regeln auflisten

Gibt eine paginierte Liste aller Regeln zurück.

Query-Parameter: page, per_page

---

POST /api2/v1/rules — Regel erstellen

{
  "name": "Großkunde DE",
  "enabled": true,
  "priority": 10,
  "conditionGroups": [
    {
      "operator": "AND",
      "conditions": [
        { "type": "cart_subtotal", "op": "gte", "value": 500 },
        { "type": "shipping_country", "op": "eq", "value": "DE" }
      ]
    }
  ]
}

Pflichtfelder: name, conditionGroups

---

GET /api2/v1/rules/:id — Einzelne Regel abrufen

Gibt die vollständige Regeldefinition inkl. Bedingungsgruppen zurück.

---

PATCH /api2/v1/rules/:id — Regel aktualisieren

Aktualisiert ausgewählte Felder. Geschützte Regeln lehnen Änderungen an conditionGroups ab (409).

---

DELETE /api2/v1/rules/:id — Regel löschen

Schlägt mit 409 fehl, wenn die Regel noch von Rabatten oder Versandregeln verwendet wird.

---

POST /api2/v1/rules/:id/test — Regel testen

Wertet eine Regel gegen ein bereitgestelltes Kontext-Objekt aus und gibt das Ergebnis mit einer Aufschlüsselung pro Bedingung zurück.

Request-Body:

{
  "context": {
    "cartSubtotal": 750,
    "shippingCountry": "DE",
    "customerLoggedIn": true
  }
}

Antwort:

{
  "matched": true,
  "breakdown": [
    {
      "groupIndex": 0,
      "groupOperator": "AND",
      "conditionIndex": 0,
      "conditionType": "cart_subtotal",
      "conditionOp": "gte",
      "result": true
    },
    {
      "groupIndex": 0,
      "groupOperator": "AND",
      "conditionIndex": 1,
      "conditionType": "shipping_country",
      "conditionOp": "eq",
      "result": true
    }
  ]
}

---

Fehler-Codes

HTTP-Status	Bedeutung
400	Ungültiger JSON-Body oder fehlende Pflichtfelder
401	Fehlender oder ungültiger API-Schlüssel
403	Schlüssel hat nicht die erforderliche read_write-Berechtigung
404	Flow oder Regel nicht gefunden
409	Konflikt (z. B. Löschen einer verwendeten Regel; geschützte Regel)
422	Validierungsfehler (z. B. unbekannter Aktionstyp)