Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta página explica como enviar feedback sobre a precisão das avaliações criadas pelo reCAPTCHA. Com essas informações,
o reCAPTCHA pode ajustar o modelo específico do site e fornecer
um melhor desempenho para o site ao longo do tempo.
Quando anotar avaliações
Ao criar uma avaliação, o reCAPTCHA fornece uma pontuação que
ajuda a entender o nível de risco que as interações do usuário representam.
Mais tarde, quando o site tiver mais informações sobre as interações do usuário
para determinar se a interação foi legítima ou fraudulenta, será possível confirmar
ou corrigir a avaliação do reCAPTCHA. Para fazer isso, envie os
IDs de avaliação do reCAPTCHA de volta ao Google rotulados como LEGITIMATE
ou FRAUDULENT.
Ao confirmar ou corrigir
a avaliação do reCAPTCHA, você melhora o desempenho dele
no seu site.
Para melhorar o desempenho do reCAPTCHA, é possível confirmar as
anotações como verdadeiros positivos e verdadeiros negativos, além das
anotações referentes a possíveis erros de avaliação.
Por exemplo, para um usuário que autenticou
usando o método de autenticação de dois fatores e recebeu uma pontuação alta de reCAPTCHA,
a avaliação pode ser anotada como LEGITIMATE. Como alternativa, se a pontuação do reCAPTCHA
era baixa e o site determinou que a interação foi fraudulenta
ou abusiva, a avaliação pode ser anotada como FRAUDULENT.
A lista a seguir mostra mais informações sobre alguns exemplos de interações de usuário
que indicam se ela é legítima ou
fraudulenta:
Estornos de cartão de crédito e outras evidências concretas de fraude indicam que uma
transação financeira anterior foi fraudulenta.
Uma conta nova que envia mensagens sinalizadas como spam por outros usuários
pode indicar que a criação da conta foi fraudulenta.
Um caso de suporte registrado se um usuário tiver dificuldade para fazer login na conta
pode indicar que a tentativa de login é legítima.
Uma compra ou reserva em um site que usa o reCAPTCHA para
se proteger contra a raspagem pode indicar que o usuário é legítimo.
Antes de começar
Verifique se você tem o seguinte papel do Identity and Access Management:
Agente do reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
Dependendo de onde você configurou o reCAPTCHA, siga a etapa
adequada:
Para integrações com o WAF, é possível extrair o ID de avaliação exclusivo do
token do reCAPTCHA. O ID de avaliação exclusivo é a
string alfanumérica única de 16 caracteres que aparece no final do
token reCAPTCHA após :U=. Por exemplo, se o token reCAPTCHA for
.................U=6ZZZZe73fZZZZZZ0, o ID de avaliação será 6ZZZZe73fZZZZZZ0.
Anotar uma avaliação
Determine as informações e os rótulos a serem adicionados no corpo JSON da solicitação, dependendo do seu caso de uso.
A tabela a seguir lista os rótulos e valores que podem ser usados para anotar
eventos:
Marcador
Descrição
Exemplo de solicitação
reasons
Opcional. Um rótulo para apoiar suas
avaliações.
Forneça detalhes do evento em tempo real no rótulo reasons alguns segundos ou minutos após o evento, porque eles influenciam a detecção em tempo real.
Para conferir a lista de
valores possíveis,
consulte valores de motivos.
Exemplo: para detectar aquisições de contas, anote se a senha inserida
estava correta com os valores CORRECT_PASSWORD ou
INCORRECT_PASSWORD. Se você tiver implantado sua própria MFA,
adicione os seguintes valores: INITIATED_TWO_FACTOR e
PASSED_TWO_FACTOR ou FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Opcional. Um rótulo para indicar a
legitimidade das avaliações.
Forneça fatos sobre eventos de login e
registro para validar ou corrigir suas avaliações de risco no
rótulo annotation.
Valores possíveis: LEGITIMATE
ou FRAUDULENT.
Você pode enviar essas informações a qualquer momento ou como parte de um job em lote.
No entanto, recomendamos enviar essas informações alguns segundos ou minutos
após o evento, porque elas influenciam a detecção em tempo real.
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create.
ANNOTATION_LABEL: o rótulo para indicar se a avaliação é legítima ou fraudulenta.
Os valores possíveis são LEGITIMATE ou FRAUDULENT.
ANNOTATION_REASON: descreve o contexto da anotação escolhida para esta avaliação.
Para saber mais sobre os valores possíveis, consulte Motivos para anotar uma avaliação.
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Você receberá um código de status bem-sucedido (2xx) e uma resposta vazia.
Chave de API
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create
ANNOTATION_LABEL: o rótulo para indicar se a avaliação é legítima ou fraudulenta.
Os valores possíveis são LEGITIMATE ou FRAUDULENT.
ANNOTATION_REASON: descreve o contexto da anotação escolhida para esta avaliação.
Para saber mais sobre os valores possíveis, consulte Motivos para anotar uma avaliação.
Método HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[],[],null,["# Annotate assessments\n\nThis page explains how you can provide feedback on the accuracy of the\nassessments created by reCAPTCHA. With this information,\nreCAPTCHA can tune your site-specific model and provide\nimproved performance for your site over time.\n\nWhen to annotate assessments\n----------------------------\n\nreCAPTCHA provides a score when creating an assessment that\nhelps you understand the level of risk user interactions pose.\nLater, when your site has more information about user interactions\nto determine if the interaction was legitimate or fraudulent, you can confirm or\ncorrect reCAPTCHA's assessment. To do this, you send the\nreCAPTCHA assessment IDs back to Google labeled as `LEGITIMATE`\nor `FRAUDULENT`.\nConfirming or correcting\nreCAPTCHA's assessment improves the performance of\nreCAPTCHA for your site.\n\nTo improve the performance of reCAPTCHA, you can confirm the\nannotations for **true positives** and **true negatives** in addition to the\nannotations for potential assessment errors.\nFor example, for a user who successfully authenticated using\na 2-factor-authentication method and received a high reCAPTCHA score, you can\nannotate the assessment as `LEGITIMATE`. Alternatively, if reCAPTCHA\nscore was low and your site determined that the interaction was fraudulent or\nabusive, you can annotate the assessment as `FRAUDULENT`.\n\nThe following list shows additional information about some sample user\ninteractions that indicate whether a user interaction is legitimate or\nfraudulent:\n\n- Credit card chargebacks or other concrete evidence of fraud indicate that an earlier financial transaction was fraudulent.\n- A new account that sends messages that are flagged as spam by other users might indicate that the account creation was fraudulent.\n- A support case filed if a user has difficulty logging in to their account might indicate that the login attempt is legitimate.\n- A purchase or booking on a site that uses reCAPTCHA to defend against scraping might indicate that the user is legitimate.\n\nBefore you begin\n----------------\n\n- Ensure that you have the following Identity and Access Management role:\n reCAPTCHA Enterprise Agent (`roles/recaptchaenterprise.agent`).\n\n- Depending on where you have set up reCAPTCHA, complete the\n appropriate step:\n\n - [Create an assessment for your website](/recaptcha/docs/create-assessment-website).\n - [Create an assessment for your mobile application](/recaptcha/docs/create-assessment-mobile).\n - [Set up your WAF integration](/recaptcha/docs/setup-overview-waf).\n\nRetrieve the assessment ID\n--------------------------\n\nTo annotate an assessment, retrieve the unique assessment ID in the\nfollowing ways:\n\n- For web and mobile integrations, you can retrieve the unique assessment ID\n from the assessment response.\n\n After you create an assessment, you receive a JSON response as shown in the\n following example.\n\n Retrieve the unique assessment ID from the `name` field in the JSON response. \n\n ```bash\n {\n 'tokenProperties': {\n 'valid': True,\n 'hostname': 'www.google.com',\n 'action': 'homepage',\n 'createTime': u'2019-03-28T12:24:17.894Z'\n },\n 'riskAnalysis': {\n 'score': 0.1,\n 'reasons': ['AUTOMATION']\n },\n 'event': {\n 'token': 'RESPONSE_TOKEN',\n 'siteKey': 'KEY_ID'\n },\n 'name': 'ASSESSMENT_ID'\n }\n ```\n- For WAF integrations, you can retrieve the unique assessment ID from the\n reCAPTCHA token. The unique assessment ID is the\n unique alphanumeric string of 16 characters that appears at the end of the\n reCAPTCHA token after `:U=`. For example, if the reCAPTCHA token is\n `.................U=6ZZZZe73fZZZZZZ0`, then the assessment ID is `6ZZZZe73fZZZZZZ0`.\n\nAnnotate an assessment\n----------------------\n\n1.\n\n Determine the information and labels to add in the request JSON body\n depending on your use case.\n\n The following table lists the labels and values that you can use to annotate\n events:\n\n \u003cbr /\u003e\n\n2. Annotate an assessment using the\n [`projects.assessments.annotate`](/recaptcha/docs/reference/rest/v1/projects.assessments/annotate)\n method with the gcloud CLI or an API key.\n\n **Note:** If you are using the `v1beta1` version of the API, we recommend using the `v1` version because the new features, such as reCAPTCHA account defender are available only on `v1` version. For migrating from `v1beta1` to `v1`, see [Migrate from v1beta API to v1 API](/recaptcha/docs/migration-v1). \n\n ### gcloud CLI\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call.\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) , or by using [Cloud Shell](/shell/docs), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Authorization: Bearer $(gcloud auth print-access-token)\" \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\"\n ```\n\n #### PowerShell\n\n | **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](/sdk/gcloud/reference/init) or [`gcloud auth login`](/sdk/gcloud/reference/auth/login) . You can check the currently active account by running [`gcloud auth list`](/sdk/gcloud/reference/auth/list).\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $cred = gcloud auth print-access-token\n $headers = @{ \"Authorization\" = \"Bearer $cred\" }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\n ### API key\n\n\n Before using any of the request data,\n make the following replacements:\n - \u003cvar translate=\"no\"\u003eASSESSMENT_ID\u003c/var\u003e: Value of the `name` field returned from the `projects.assessments.create` call\n - \u003cvar translate=\"no\"\u003eANNOTATION_LABEL\u003c/var\u003e: The label to indicate whether the assessment is legitimate or fraudulent. Possible values are `LEGITIMATE` or `FRAUDULENT`.\n - \u003cvar translate=\"no\"\u003eANNOTATION_REASON\u003c/var\u003e: Describes the context for the annotation that was chosen for this assessment. To learn about possible values, see [reasons for annotating an assessment](https://cloud.google.com/recaptcha/docs/reference/rest/v1/projects.assessments/annotate#reason).\n\n\n HTTP method and URL:\n\n ```\n POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\n ```\n\n\n Request JSON body:\n\n ```\n {\n \"annotation\": \"ANNOTATION_LABEL\"\n \"reasons\": \"ANNOTATION_REASON\"\n }\n ```\n\n To send your request, choose one of these options: \n\n #### curl\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n curl -X POST \\\n -H \"Content-Type: application/json; charset=utf-8\" \\\n -d @request.json \\\n \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\"\n ```\n\n #### PowerShell\n\n | **Note:** Create an [API key](https://cloud.google.com/docs/authentication/api-keys#creating_an_api_key) to authenticate with the API.\n\n\n Save the request body in a file named `request.json`,\n and execute the following command:\n\n ```\n $headers = @{ }\n\n Invoke-WebRequest `\n -Method POST `\n -Headers $headers `\n -ContentType: \"application/json; charset=utf-8\" `\n -InFile request.json `\n -Uri \"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY\" | Select-Object -Expand Content\n ```\n\n You should receive a successful status code (2xx) and an empty response.\n\n \u003cbr /\u003e\n\nWhat's next\n-----------\n\n- Learn about the [user accounts protection features of reCAPTCHA](/recaptcha/docs/protect-accounts-overview)."]]
