Product Custom Inputs: Shop API
Shop API von Product Custom Inputs für Headless-Clients: Endpunkte für Felder und Bestellpositions-Werte, POST-Body, curl-Beispiele, Zugriffsregeln und Fehlerformat.
Product Custom Inputs: Shop API
Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.
Headless-Clients nutzen die Shop API. Das ist ein eigener Schreibweg: Ein echter Add-to-Cart-Request läuft weder über CartItemType noch löst er sylius.cart_item_add aus, die Formular-Logik der Storefront greift dort also nie. Die Pfade unten gelten relativ zum API-Präfix deiner Sylius-Installation.
Endpunkte
Felddefinitionen
| Method | Path | Beschreibung |
|---|---|---|
| GET | /shop/product-custom-input-fields |
Öffentlich, nach Position sortiert, Filter ?products=<IRI oder ID> |
| GET | /shop/product-custom-input-fields/{id} |
Ein Feld |
| GET | /admin/product-custom-input-fields |
Admin, nur lesend |
| GET | /admin/product-custom-input-fields/{id} |
Admin, ein Feld |
| DELETE | /admin/product-custom-input-fields/{id} |
Admin, Feld löschen |
Anlegen und Ändern von Feldern ist über die API nicht möglich. Das geht nur im Admin.
Werte an Bestellpositionen
| Method | Path | Beschreibung |
|---|---|---|
| GET | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs |
Alle Werte der Position |
| GET | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs/{id} |
Ein Wert |
| POST | /shop/orders/{tokenValue}/items/{itemId}/custom-inputs |
Wert setzen oder überschreiben |
| GET | /admin/order-item-custom-input-values |
Admin, filterbar mit orderItem |
| GET | /admin/order-item-custom-input-values/{id} |
Admin, ein Wert |
Die Admin-Endpunkte erfordern die Admin-Authentifizierung mit ROLE_API_ACCESS.
POST-Body
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
field |
IRI | Ja | Das Custom Input Field, z. B. /api/v2/shop/product-custom-input-fields/3 |
value |
String | Nein | Der Wert im Textformat (siehe Konfiguration) |
Die Bestellposition ergibt sich aus dem Pfad und ist nicht im Body setzbar.
Beispiel
Felder eines Produkts abrufen:
curl -s "https://shop.example.com/api/v2/shop/product-custom-input-fields?products=/api/v2/shop/products/PLUGIN_X" \
-H "Accept: application/ld+json"
Wert für eine Position setzen:
curl -s -X POST "https://shop.example.com/api/v2/shop/orders/TOKEN123/items/42/custom-inputs" \
-H "Content-Type: application/ld+json" \
-H "Accept: application/ld+json" \
-d '{"field": "/api/v2/shop/product-custom-input-fields/3", "value": "Anna"}'
Ein erneutes POST für dasselbe Feld an derselben Position überschreibt den bisherigen Wert.
Zugriff und Fehler
Zugriff hat nur, wem die Bestellung gehört: ein angemeldeter Kunde für seine Bestellungen, ein anonymer Besucher nur für eine Gast-Bestellung. Für alles andere antwortet die API mit 404. Geschrieben wird nur, solange die Bestellung ein Warenkorb ist.
| Status | Ursache |
|---|---|
| 404 | Plugin im Admin deaktiviert (Schalter "Aktiviert"), Bestellung oder Position nicht gefunden oder nicht zugänglich, Bestellung ist kein Warenkorb mehr, Feld gehört nicht zum Produkt der Position |
| 422 | field fehlt, oder der Wert verletzt die Regeln des Feldtyps (Pflichtfeld, Länge, Bereich, Format, Auswahl, gesperrter Tag) |
Gleichzeitige POSTs für dasselbe Feld an derselben Position sind nicht abgesichert. Treffen zwei Requests zugleich ein, kann der zweite an der Unique-Constraint scheitern und mit einem Serverfehler antworten.