Support Form: Shop API

Support Form für Sylius - Shop API für Headless-Clients: Endpunkte für Zusatzfelder, Betreff-Auswahl und Absenden, POST-Body, curl-Beispiele, Admin-Endpunkte und Fehlerformat

English Version

Zurück zur Übersicht

Support Form: Shop API

Live Demo: Teste dieses und weitere Plugins live — ohne Installation, ohne Risiko: demo.markus-michalski.net

Headless-Clients nutzen die Shop API statt des Formulars unter /support. Beide Wege teilen sich dieselbe Verarbeitung. Die Antworten auf deine Zusatzfelder prüft die API mit den Regeln des Storefront-Formulars, sodass Pflichtangaben, Längen, E-Mail-Format und erlaubte Auswahloptionen identisch sind. Die Pfade unten gelten relativ zum API-Präfix deiner Sylius-Installation, bei Sylius ist das /api/v2.

Endpunkte

Method	Path	Beschreibung
GET	`/shop/support-form-fields`	Öffentlich: die Zusatzfelder, nach Position sortiert
GET	`/shop/support-form-fields/{id}`	Öffentlich: ein Zusatzfeld
GET	`/shop/support-form-subject-choices`	Öffentlich: die Betreff-Auswahl des aktuellen Channels als Liste aus `value` und `label`
POST	`/shop/support-requests`	Öffentlich: eine Anfrage absenden
GET	`/admin/support-requests`	Admin: alle Anfragen, neueste zuerst
GET	`/admin/support-requests/{id}`	Admin: eine Anfrage

Die Admin-Endpunkte verlangen ROLE_API_ACCESS, dieselbe Berechtigung wie jede andere Admin-API-Ressource von Sylius. Eine öffentliche Liste der Anfragen gibt es bewusst nicht, weil sie personenbezogene Daten enthalten. Anlegen, Ändern und Löschen von Feldern oder Konfigurationen ist über die API nicht möglich, das geht nur im Admin.

POST-Body

Feld	Typ	Pflicht	Beschreibung
`subject`	String	Ja	Der Betreff. Hat der Channel eine Auswahlliste, muss es einer der `value`-Werte aus `/shop/support-form-subject-choices` sein. Ohne Auswahlliste ist jeder Text erlaubt.
`consent`	Boolean	Ja	Muss `true` sein
`answers`	Objekt	Nein	Antworten auf die Zusatzfelder, als Schlüssel die ID des Feldes, zum Beispiel `{"12": "jane@example.com"}`

Kanal, Zeitpunkt, E-Mail-Adresse und gespeicherte Antworten setzt der Server. Die Adresse der Anfrage leitet er aus der ersten beantworteten Angabe eines Feldes vom Typ E-Mail ab, genau wie im Formular.

Checkbox-Felder akzeptieren nur echte JSON-Werte true oder false. Werte wie "0", 0 oder "false" lehnt die API ab.

Beispiele

Betreff-Auswahl des Channels abrufen:

curl -s "https://shop.example.com/api/v2/shop/support-form-subject-choices" \
  -H "Accept: application/ld+json"

Die Antwort ist leer, wenn der Channel keine Konfiguration hat oder die aktive Liste leer ist. Dann ist ein freier Text als Betreff erlaubt.

Zusatzfelder abrufen, um das Formular im Frontend aufzubauen:

curl -s "https://shop.example.com/api/v2/shop/support-form-fields" \
  -H "Accept: application/ld+json"

Anfrage absenden:

curl -s -X POST "https://shop.example.com/api/v2/shop/support-requests" \
  -H "Content-Type: application/ld+json" \
  -H "Accept: application/ld+json" \
  -d '{"subject": "Order arrived damaged", "consent": true, "answers": {"12": "jane@example.com"}}'

Eine gültige Anfrage beantwortet die API mit 201. Die Antwort enthält id, createdAt, email und subject.

Fehlerformat

Es gilt das Standard-Fehlerformat von API Platform. Bei Validierungsfehlern liefert die Antwort eine Liste violations mit propertyPath, message und code. Fehler in einer Antwort auf ein Zusatzfeld haben den Pfad answers[<ID>]. Eine ID, die zu keinem Feld gehört, meldet „This field does not exist.“

Status	Ursache
201	Anfrage gespeichert
400	Falscher Datentyp bei `answers`, zum Beispiel ein String statt eines Objekts. Auf API Platform 4 gilt das auch für `consent`.
422	`subject` fehlt oder ist leer, `consent` fehlt oder ist nicht `true`, der Betreff steht nicht in der Auswahlliste, eine Antwort verletzt die Regeln ihres Feldes, oder eine Erweiterung hat die Anfrage abgelehnt. Auf API Platform 5 gilt das auch für einen falschen Datentyp bei `consent`.
401 / 403	Nur Admin-Endpunkte: Token fehlt oder hat kein `ROLE_API_ACCESS`

Der Statuscode bei einem falschen Datentyp von consent hängt von der API-Platform-Version ab: 400 auf API Platform 4, 422 auf API Platform 5. Alle anderen Statuscodes sind auf beiden Versionen gleich.

Lehnt eine Erweiterung die Anfrage über das Event PRE_PERSIST ab (siehe Erweiterbarkeit), antwortet die API mit 422. Als Meldung steht der Ablehnungsgrund der Erweiterung in der Antwort, ohne Grund der Text „Submission rejected.“.