お客様のサーバーは、Bot Protection にはわからないことを知っています。ある人がメールアドレスを確認したこと、異議申し立てなく支払ったこと、あるいはカードにチャージバックが発生したことなどです。これを送ると、次の判定で Bot Protection がそのブラウザーをどこまで信頼するかが決まります。ルールや重みは変わりません。あるブラウザーの行動が、別のブラウザーの判定を変えることはありません。
訪問者は、/v1/decide が返した request_id で指定します。注文と一緒に保存しておき、数週間後や数か月後に結果がわかったときに送ってください。タグの token を付けた判定はそのブラウザーのセッションを指します。token なしの判定はどのセッションも指さないため、そのフィードバックは拒否されます。訪問者の token（_kz Cookie）でも指定できます。request_id の代わりに token を送ってください。
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"}]}'
| 結果 | 送るタイミング |
|---|---|
verified_human | 本人であることが証明されたとき（メールのリンク、電話の確認コード、パスキー） |
good_customer | 異議申し立てのない支払い済みの注文やサブスクリプションの更新 |
chargeback | 支払いに異議が申し立てられた、または取り消されたとき |
fraud | アカウントが偽物または悪用目的だと判明したとき |
// 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})
各項目は、request_id と token のちょうど一方でセッションを指定します。1 回のバッチは 1〜1,000 件です。応答は記録された内容を示します：{"accepted": 1, "duplicates": 0, "rejected": 0, "errors": []}。拒否された各項目は {"index", "code", "detail"} で、たとえば自分のものではない request_id には forged、token なしで行われた判定のものには no_session が付きます。有効でないボディは 400 の problem で、decide のエラーと同じです。
各呼び出しには Idempotency-Key（表示可能な ASCII 文字 1〜255 字）を付けてください。SDK は UUID v7 を付けます。1 時間以内に同じキーと同じボディで送ると、最初の応答が Idempotent-Replayed: true 付きで再び返り、二重には記録されません。別のボディなら 422 idempotency_key_reused、最初の呼び出しがまだ実行中なら 409 idempotency_key_in_use です。そのため、応答がなかった呼び出しや、409、429、5xx を受けた呼び出しは、同じキーで安全に再送できます。SDK は 5 秒以内に数回再送します。
フィードバックは任意かつ無料で、判定としてカウントされることはありません。良い結果は、同じブラウザーが戻ってくる限り、数か月後でもその後の判定を human や human_high に引き上げることがあり、悪い結果はそれを取り消します。