Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
En esta página, se explica cómo puedes enviar comentarios sobre la exactitud de las evaluaciones que crea reCAPTCHA. Con esta información, reCAPTCHA puede ajustar el modelo específico de tu sitio y proporcionar un rendimiento mejorado con el tiempo.
Cuándo anotar las evaluaciones
reCAPTCHA proporciona una puntuación cuando creas una evaluación que te ayuda a comprender el nivel de riesgo que representan las interacciones de los usuarios.
Más adelante, cuando tu sitio tenga más información sobre las interacciones del usuario para determinar si la interacción fue legítima o fraudulenta, podrás confirmar o corregir la evaluación de reCAPTCHA. Para ello, envía los IDs de evaluación de reCAPTCHA a Google etiquetados como LEGITIMATE o FRAUDULENT.
Confirmar o corregir la evaluación de reCAPTCHA mejora el rendimiento de reCAPTCHA en tu sitio.
Para mejorar el rendimiento de reCAPTCHA, puedes confirmar las anotaciones de positivos verdaderos y negativos verdaderos, además de las anotaciones de posibles errores de evaluación.
Por ejemplo, para un usuario que se autenticó correctamente con un método de autenticación de 2 factores y recibió una puntuación alta de reCAPTCHA, puedes anotar la evaluación como LEGITIMATE. Como alternativa, si la puntuación de reCAPTCHA fue baja y tu sitio determinó que la interacción fue fraudulenta o abusiva, puedes anotar la evaluación como FRAUDULENT.
En la siguiente lista, se muestra información adicional sobre algunas interacciones de usuario de muestra que indican si una interacción de usuario es legítima o fraudulenta:
Las devoluciones de cargos de tarjetas de crédito o cualquier otra evidencia concreta de fraude indican que una transacción financiera anterior fue fraudulenta.
Una cuenta nueva que envía mensajes marcados como spam por otros usuarios podría indicar que la creación de la cuenta fue fraudulenta.
Un caso de asistencia presentado si un usuario tiene dificultades para acceder a su cuenta puede indicar que el intento de acceso es legítimo.
Una compra o reserva en un sitio que usa reCAPTCHA para defenderse contra el raspado podría indicar que el usuario es legítimo.
Antes de comenzar
Asegúrate de tener el siguiente rol de administración de identidades y accesos: Agente de reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).
Según dónde hayas configurado reCAPTCHA, completa el paso correspondiente:
En el caso de las integraciones de WAF, puedes recuperar el ID de evaluación único del
token de reCAPTCHA. El ID de evaluación único es la cadena alfanumérica única de 16 caracteres que aparece al final del token de reCAPTCHA después de :U=. Por ejemplo, si el token de reCAPTCHA es .................U=6ZZZZe73fZZZZZZ0, el ID de evaluación es 6ZZZZe73fZZZZZZ0.
Cómo anotar una evaluación
Determina la información y las etiquetas que debes agregar en el cuerpo JSON de la solicitud según tu caso de uso.
En la siguiente tabla, se enumeran las etiquetas y los valores que puedes usar para anotar eventos:
Etiqueta
Descripción
Ejemplo de solicitud
reasons
Opcional. Una etiqueta para respaldar tus
evaluaciones.
Proporciona detalles del evento en tiempo real en la etiqueta reasons en unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.
Ejemplo: Para detectar apropiaciones de cuentas, anota si la contraseña ingresada era correcta con valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si implementaste tu propia MFA, puedes agregar los siguientes valores: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR o FAILED_TWO_FACTOR.
{
"reasons": ["INCORRECT_PASSWORD"]
}
annotation
Opcional. Es una etiqueta para indicar la legitimidad de las evaluaciones.
Proporciona datos sobre los eventos de acceso y registro para validar o corregir tus evaluaciones de riesgos en la etiqueta annotation.
Valores posibles: LEGITIMATE o FRAUDULENT.
Puedes enviar esta información en cualquier momento o como parte de un trabajo por lotes.
Sin embargo, te recomendamos que envíes esta información unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
ASSESSMENT_ID: Es el valor del campo name que se muestra desde la llamada projects.assessments.create.
ANNOTATION_LABEL: Es la etiqueta que indica si la evaluación es legítima o fraudulenta.
Los valores posibles son LEGITIMATE o FRAUDULENT.
ANNOTATION_REASON: Describe el contexto de la anotación que se eligió para esta evaluación.
Para obtener información sobre los valores posibles, consulta los motivos para anotar una evaluación.
Método HTTP y URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Deberías recibir un código de estado exitoso (2xx) y una respuesta vacía.
Clave de API
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
ASSESSMENT_ID: Es el valor del campo name que se muestra desde la llamada projects.assessments.create.
ANNOTATION_LABEL: Es la etiqueta que indica si la evaluación es legítima o fraudulenta.
Los valores posibles son LEGITIMATE o FRAUDULENT.
ANNOTATION_REASON: Describe el contexto de la anotación que se eligió para esta evaluación.
Para obtener información sobre los valores posibles, consulta los motivos para anotar una evaluación.
Método HTTP y URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 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)."]]
