Il tuo server sa cose che Bot Protection non può sapere: che una persona ha verificato la sua email, che ha pagato senza contestazioni, o che su una carta è arrivato un chargeback. Inviarle stabilisce quanto Bot Protection si fida di quel browser nelle decisioni successive. Non cambia nessuna regola né nessun peso: ciò che ha fatto un browser non cambia mai le decisioni di un altro.
Indica il visitatore con il request_id che ha risposto /v1/decide: conservalo con l'ordine e invialo quando conosci l'esito, settimane o mesi dopo. Una decisione presa con il token del tag indica la sessione di quel browser; una presa senza token non ne indica nessuna, e il feedback su di essa viene rifiutato. Va bene anche il token del visitatore (il cookie _kz): invia token al posto di 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"}]}'
| Esito | Quando |
|---|---|
verified_human | la persona ha dimostrato chi è: un link via email, un codice via telefono, una passkey |
good_customer | un ordine pagato, un abbonamento rinnovato, senza contestazioni |
chargeback | un pagamento contestato o stornato |
fraud | hai scoperto che l'account era falso o abusivo |
// 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})
Ogni elemento nomina la sua sessione con esattamente uno tra request_id e token; un batch ne contiene da 1 a 1.000. La risposta dice cosa è stato registrato: {"accepted": 1, "duplicates": 0, "rejected": 0, "errors": []}, dove ogni elemento rifiutato è {"index", "code", "detail"}, come forged per un request_id che non è tuo, o no_session per quello di una decisione presa senza token. Un body non valido è un problem 400, come gli errori di decide.
Invia un Idempotency-Key con ogni chiamata, da 1 a 255 caratteri ASCII visibili, come fanno gli SDK con un UUID v7. La stessa chiave con lo stesso body entro un'ora riceve di nuovo la prima risposta, con Idempotent-Replayed: true, e non registra nulla due volte; con un altro body è 422 idempotency_key_reused, e mentre la prima chiamata è ancora in corso, 409 idempotency_key_in_use. Così una chiamata che non ha avuto risposta, un 409, un 429 o un 5xx si può reinviare senza rischi con la sua chiave, e gli SDK lo fanno, qualche volta entro 5 secondi.
Il feedback è facoltativo e gratuito, e non conta mai come decisione. Gli esiti positivi possono alzare una decisione successiva dello stesso browser a human o human_high, anche mesi dopo, purché torni; quelli negativi tolgono quanto concesso.