O seu servidor sabe coisas que o Bot Protection não sabe: que uma pessoa confirmou o email, pagou sem disputa, ou que um cartão teve chargeback. Enviar isso define quanto o Bot Protection confia naquele navegador nas próximas decisões. Não muda nenhuma regra nem nenhum peso: o que um navegador fez nunca muda as decisões de outro.
Identifique o visitante pelo request_id que o /v1/decide respondeu: guarde-o com o pedido e envie-o quando souber o resultado, semanas ou meses depois. Uma decisão feita com o token da tag identifica a sessão daquele navegador; uma feita sem token não identifica nenhuma, e o feedback sobre ela é recusado. O token do visitante (o cookie _kz) também serve: envie token no lugar de 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"}]}'
| Resultado | Quando |
|---|---|
verified_human | a pessoa provou quem é: um link por email, um código por telefone, uma passkey |
good_customer | um pedido pago, uma assinatura renovada, sem disputa |
chargeback | um pagamento contestado ou estornado |
fraud | você descobriu que a conta era falsa ou abusiva |
// 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})
Cada item nomeia a sua sessão por exatamente um entre request_id e token; um lote tem de 1 a 1.000. A resposta diz o que foi registrado: {"accepted": 1, "duplicates": 0, "rejected": 0, "errors": []}, onde cada item recusado é {"index", "code", "detail"}, como forged para um request_id que não é seu, ou no_session para um de uma decisão feita sem token. Um corpo inválido é um problem 400, como os erros do decide.
Envie um Idempotency-Key em cada chamada, de 1 a 255 caracteres ASCII visíveis, como os SDKs fazem com um UUID v7. A mesma chave com o mesmo corpo em até uma hora recebe a primeira resposta de novo, com Idempotent-Replayed: true, e não registra nada duas vezes; com outro corpo é 422 idempotency_key_reused, e enquanto a primeira chamada ainda roda, 409 idempotency_key_in_use. Assim, uma chamada sem resposta, um 409, um 429 ou um 5xx pode ser reenviada com segurança com a sua chave, e os SDKs fazem isso, algumas vezes em até 5 segundos.
O feedback é opcional e grátis, e nunca conta como decisão. Bons resultados podem elevar uma decisão posterior do mesmo navegador a human ou human_high, também meses depois, desde que ele volte; maus resultados desfazem isso.