[Документация Yandex Cloud](../../index.md) > [Yandex SmartCaptcha](../index.md) > Концепции > Валидация пользователя

# Валидация пользователя

SmartCaptcha проверяет запросы пользователей своими ML-алгоритмами и показывает [задание](tasks.md) только тем пользователям, запросы которых посчитает подозрительными.

При этом на странице необязательно размещать кнопку **Я не робот**.

{% note info %}

Чтобы сделать вашу защиту более эффективной, мы используем информацию об HTTP-запросах для развития моделей машинного обучения (ML). Вы можете отключить использование этой информации в [консоли управления](https://console.yandex.cloud) при создании капчи или позднее в ее настройках.

{% endnote %}

## Обычная капча {#usual-captcha}

Обычная капча — способ подключения виджета SmartCaptcha с кнопкой **Я не робот**, клик по которой отправит запрос пользователя в SmartCaptcha. Если сервис посчитает запрос подозрительным, он предложит пользователю решить [задание](tasks.md).

## Невидимая капча {#invisible-captcha}

Невидимая капча — способ подключения виджета SmartCaptcha, при котором кнопка **Я не робот** отсутствует на странице. Окно с заданием увидят только те пользователи, запросы которых сервис посчитает подозрительными.

Разработчик сам выбирает событие, когда сервис проверит пользователя.

## Результат проверки {#validation-result}

SmartCaptcha, проверив запрос, присваивает ему идентификатор — одноразовый токен с ограниченным сроком жизни. По этому токену вы можете запросить у сервиса результат проверки запроса пользователя.

{% note warning %}

* Токен действителен в течение 5 минут. По истечении этого времени он становится недействительным, и пользователю нужно снова пройти проверку.
* Токен можно использовать только один раз для запроса результата проверки. При повторной попытке валидировать тот же токен вы получите ответ `"status": "failed"` с сообщением `Invalid or expired Token`.

{% endnote %}

После проверки токен загружается в элемент `<input type="hidden" name="smart-token" value="<токен>" ...>` на странице пользователя. Например:

```HTML
<div id="captcha-container" class="smart-captcha" ...>
    <input type="hidden" name="smart-token" value="dD0xNjYyNDU3NDMzO2k9MmEwMjo2Yjg6YjA4MTpiNTk3OjoxOjFiO0Q9MjVCREY1RDgzMDBERjQ3QjExNkUyMDJDNjJFNEI3Q0Y0QjYzRkRDNzJEMkV********DNjMxODgzMUM0REZBNzI1QUE1QzUwO3U9MTY2MjQ1NzQzMzk5MTEwNjQxNTtoPTg4MWRjMDc2YzE3MjkxNGUwNDgwMTVkYzhl********">
    ...
</div>
```

Где:

* `<div id="captcha-container" class="smart-captcha" ...>` — элемент `div` с виджетом.
* `value` — значение токена.

Чтобы узнать результат проверки, отправьте POST-запрос на адрес `https://smartcaptcha.cloud.yandex.ru/validate`, передав параметры в формате `x-www-form-urlencoded`:

```
secret=<ключ_сервера>&token=<токен>&ip=<IP-адрес_пользователя>
```

Где:

* `secret` — [ключ сервера](keys.md);
* `token` — одноразовый токен, полученный после прохождения проверки;
* `ip` — IP-адрес пользователя, с которого пришел запрос на проверку токена. Этот параметр не обязателен, однако мы просим передавать IP-адрес пользователя при запросах. Это помогает улучшить качество работы SmartCaptcha.

## Ответ сервиса {#service-response}

В ответ сервис пришлет JSON-объект с полями `status` и `message`. Когда поле `status` принимает значение `ok`, в JSON-объект добавляется поле `host`. Оно показывает, на каком сайте была пройдена проверка. Например:

1. Это человек. Проверка пройдена на сайте `example.com`:

    ```json
    {
        "status": "ok",
        "message": "",
        "host": "example.com"
    }
    ```

1. Это человек. Проверка пройдена на сайте `example.com` через порт `8080`:

    ```json
    {
        "status": "ok",
        "message": "",
        "host": "example.com:8080"
    }
    ```

1. Пустое поле `host`. Может означать, что облако заблокировано, или произошел внутренний сбой сервиса:

    ```json
    {
        "status": "ok",
        "message": "",
        "host": ""
    }
    ```

1. Это робот:

    ```json
    {
        "status": "failed",
        "message": ""
    }
    ```

1. Запрос с поддельным или поврежденным токеном. Это робот:

    ```json
    {
        "status": "failed",
        "message": "Invalid or expired Token."
    }
    ```

### Обработка ответов {#response-handling}

Для корректной обработки ответов ориентируйтесь на поле `status`:

* `ok` — запрос обработан успешно.
* `failed` — произошла ошибка.

Ошибки делятся на два типа:

* **Это робот** — `"status": "failed"`, поле `message` пустое.
* **Ошибка в запросе** — `"status": "failed"`, поле `message` содержит описание ошибки.

Ошибки в запросе могут быть связаны с недействительным токеном или отсутствием серверного ключа. Рекомендуется выявлять и исправлять такие ошибки на этапе разработки и тестирования.

Поле `message` не предназначено для обработки в коде с помощью условий или сравнений. Используйте его только для диагностики.

## Ошибки в запросе {#errors}

Если запрос к `https://smartcaptcha.cloud.yandex.ru/validate` оформлен некорректно, сервис вернет ошибку. Например:

1. Запрос без ключа сервера:

    ```JSON
    {
        "status": "failed",
        "message": "Authentication failed. Secret has not provided."
    }
    ```

1. Запрос без токена или с поврежденным токеном:

    ```JSON
    {
        "status": "failed",
        "message": "Invalid or expired Token."
    }
    ```

{% note info %}

Чтобы при обработке запроса от пользователя не было задержки, ошибки HTTP-протокола (код ответа не 200) рекомендуется обрабатывать как ответ сервиса `"status": "ok"`.

{% endnote %}

## Что дальше {#whats-next}

* Как подключить [невидимую капчу](invisible-captcha.md).
* Капча в [React](react.md).