ALTCHA: Shop API / Headless

ALTCHA Spam-Schutz für Sylius - Shop-API-Nutzung im Headless-Betrieb: Challenge-Endpunkt, Proof per Header oder Body mitsenden, Fehlerformat mit Statuscodes und reason

English Version

Zurück zur Übersicht

ALTCHA: Shop API / Headless

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

Das Plugin schützt dieselben Schutzziele auch in der Shop API. Der Ablauf besteht aus zwei Schritten: Challenge abrufen, lösen und die Lösung mit der geschützten Anfrage mitsenden.

# 1. Challenge abrufen (gleiches Format wie beim Widget)
curl https://shop.example/api/v2/shop/altcha/challenge

# 2. mit einer beliebigen ALTCHA-Client-Library lösen und die Lösung mit der geschützten Anfrage senden
curl -X POST https://shop.example/api/v2/shop/customers/token \
     -H 'Content-Type: application/json' \
     -H 'X-Altcha-Payload: <base64 payload>' \
     -d '{"email":"...","password":"..."}'

Endpunkte

Methode	Pfad	Beschreibung
`GET`	`%sylius.security.api_shop_route%/altcha/challenge`	Liefert eine Challenge im selben Format wie der Storefront-Endpunkt (`/altcha/challenge`)
jede geschützte Operation	-	Nimmt die Lösung als Header `X-Altcha-Payload` entgegen oder als Feld `altcha` im JSON-Body (`application/json`, `application/ld+json`, Merge-Patch) bzw. im Formular-Body

Der Challenge-Endpunkt ist öffentlich und pro Client auf 30 Aufrufe pro Minute begrenzt, weil jeder Aufruf eine Schlüsselableitung kostet. Das ist der Standardwert: Pro Channel lässt er sich zwischen 1 und 1000 einstellen (siehe Konfiguration). Ein Channel, für den ALTCHA nicht aktiviert ist, antwortet mit 404.

API-Anfragen werden an ihren Routennamen (sylius_api_*) erkannt, über das Präfix %sylius.security.api_shop_route%. Ein angepasstes API-Präfix erfordert daher keine zusätzliche Konfiguration im Plugin.

Fehlerformat

Eine abgelehnte Anfrage liefert HTTP 422 (bei Rate-Limit 429) mit einem JSON-Body:

{ "message": "Your message could not be accepted", "reason": "gibberish" }

Feld	Beschreibung
`message`	Neutrale, lesbare Meldung. Sie wird in der Sprache übersetzt, die der Channel für die Anfrage auflöst, weil die API kein `_locale` in der URL hat.
`reason`	Stabiler, maschinenlesbarer Code, unabhängig von der Sprache (zum Beispiel `disposable_email`, `gibberish`, `rate_limited`)

Die möglichen Werte von reason gehören zur Abwärtskompatibilität des Plugins, in einem Minor-Release können neue hinzukommen. Behandle unbekannte Werte in deinem Client deshalb wie eine allgemeine Ablehnung (siehe Erweiterbarkeit und Kompatibilität).