Ihr Server weiß Dinge, die Bot Protection nicht wissen kann: dass ein Mensch seine E-Mail bestätigt oder ohne Streitfall bezahlt hat, oder dass eine Karte zurückgebucht wurde. Wenn Sie das senden, legt es fest, wie sehr Bot Protection diesem Browser bei den nächsten Entscheidungen vertraut. Es ändert keine Regel und kein Gewicht: Was ein Browser getan hat, ändert nie die Entscheidungen für einen anderen.
Benennen Sie den Besucher mit der request_id, die /v1/decide geantwortet hat: Speichern Sie sie mit der Bestellung und senden Sie sie, wenn Sie das Ergebnis erfahren, Wochen oder Monate später. Eine Entscheidung mit dem Token des Tags benennt die Session dieses Browsers; eine ohne Token benennt keine, und Feedback dazu wird abgelehnt. Das Token des Besuchers (das Cookie _kz) geht ebenfalls: Senden Sie token statt request_id.
curl -s -X POST https://korzen.dev/v1/feedback \ -H "Authorization: Bearer $KORZEN_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"feedback":[{"request_id":"<the decision request_id>","outcome":"good_customer"}]}'
| Ergebnis | Wann |
|---|---|
verified_human | der Mensch hat bewiesen, wer er ist: ein E-Mail-Link, ein Code per Telefon, ein Passkey |
good_customer | eine bezahlte Bestellung, ein verlängertes Abo, ohne Streitfall |
chargeback | eine angefochtene oder rückgängig gemachte Zahlung |
fraud | Sie haben festgestellt, dass das Konto gefälscht oder missbräuchlich war |
// Node: the SDK sends a UUID v7 as the Idempotency-Key, and again with each retry. await korzen.feedback([{ request_id: order.korzenRequestId, outcome: "chargeback" }]);
// Go: the same, with your own key (an order's id makes a later resend safe too). _, err := bot.Feedback(ctx, []korzen.Feedback{{RequestID: order.KorzenRequestID, Outcome: "chargeback"}}, korzen.Batch{IdempotencyKey: "chargeback-" + order.ID})
Jedes Stück nennt seine Session mit genau einem von request_id und token; ein Batch enthält 1 bis 1.000. Die Antwort sagt, was erfasst wurde: {"accepted": 1, "duplicates": 0, "rejected": 0, "errors": []}, wobei jedes abgelehnte Stück {"index", "code", "detail"} ist, etwa forged für eine request_id, die nicht Ihre ist, oder no_session für eine aus einer Entscheidung ohne Token. Ein ungültiger Body ist ein 400-Problem, wie die Fehler von decide.
Senden Sie mit jedem Aufruf einen Idempotency-Key, 1 bis 255 sichtbare ASCII-Zeichen, wie es die SDKs mit einer UUID v7 tun. Derselbe Schlüssel mit demselben Body innerhalb einer Stunde bekommt wieder die erste Antwort, mit Idempotent-Replayed: true, und nichts wird doppelt erfasst; mit einem anderen Body ist es 422 idempotency_key_reused, und solange der erste Aufruf noch läuft, 409 idempotency_key_in_use. Ein Aufruf ohne Antwort, mit 409, 429 oder 5xx lässt sich also unter seinem Schlüssel gefahrlos erneut senden, und die SDKs tun das, einige Male innerhalb von 5 Sekunden.
Feedback ist freiwillig und kostenlos und zählt nie als Entscheidung. Gute Ergebnisse können eine spätere Entscheidung desselben Browsers auf human oder human_high heben, auch Monate später, solange er wiederkommt; schlechte nehmen das wieder zurück.