Je server weet dingen die Bot Protection niet kan weten: dat iemand zijn e-mailadres heeft bevestigd, zonder geschil heeft betaald, of dat er een chargeback op een kaart kwam. Als je dat doorstuurt, bepaalt het hoeveel Bot Protection die browser vertrouwt bij de volgende beslissingen. Het verandert geen regel en geen gewicht: wat de ene browser deed, verandert nooit de beslissingen voor een andere.
Noem de bezoeker bij de request_id die /v1/decide antwoordde: bewaar die bij de bestelling en stuur hem wanneer je de uitkomst kent, weken of maanden later. Een beslissing met het token van de tag noemt de sessie van die browser; een beslissing zonder token noemt er geen, en feedback daarop wordt geweigerd. Het token van de bezoeker (de cookie _kz) kan ook: stuur token in plaats van 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"}]}'
| Uitkomst | Wanneer |
|---|---|
verified_human | de persoon heeft bewezen wie hij is: een link per e-mail, een code per telefoon, een passkey |
good_customer | een betaalde bestelling, een verlengd abonnement, zonder geschil |
chargeback | een betaling die is betwist of teruggeboekt |
fraud | je ontdekte dat het account nep of misbruikend was |
// 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})
Elk stuk noemt zijn sessie met precies één van request_id en token; een batch bevat er 1 tot 1.000. Het antwoord zegt wat er is vastgelegd: {"accepted": 1, "duplicates": 0, "rejected": 0, "errors": []}, waarbij elk geweigerd stuk {"index", "code", "detail"} is, zoals forged voor een request_id die niet van jou is, of no_session voor een van een beslissing zonder token. Een body die niet geldig is, is een 400-problem, zoals de fouten van decide.
Stuur bij elke call een Idempotency-Key mee, 1 tot 255 zichtbare ASCII-tekens, zoals de SDK's doen met een UUID v7. Dezelfde key met dezelfde body binnen een uur krijgt het eerste antwoord opnieuw, met Idempotent-Replayed: true, en legt niets twee keer vast; met een andere body is het 422 idempotency_key_reused, en zolang de eerste call nog loopt 409 idempotency_key_in_use. Een call zonder antwoord, of met een 409, 429 of 5xx, kun je dus veilig opnieuw sturen onder zijn key, en de SDK's doen dat, een paar keer binnen 5 seconden.
Feedback is optioneel en gratis, en telt nooit als beslissing. Goede uitkomsten kunnen een latere beslissing van dezelfde browser optillen naar human of human_high, ook maanden later, zolang hij terugkomt; slechte draaien dat terug.