Как читать результат Signup Protection

Используйте внешнее action ответа, чтобы решить, как продолжить регистрацию. Доставляемый email-адрес все равно может потребовать подтверждения из-за сигналов визита. Сигнал, требующий подтверждения, не устанавливает, что посетитель — бот.

Примеры ниже описывают совмещенный ответ POST /v1/signup-checks. Это вымышленные сокращенные иллюстрации отдельных полей, а не полные ответы API или измерения реальных посетителей.

В каком порядке читать ответ

Прочитайте внешнее action: allow, allow_with_email_confirmation или reject. Рекомендация учитывает обе части проверки.
Прочитайте email.action и email.status, чтобы понять решение email. Почтовые reason_codes объясняют свидетельства и ограничения.
Прочитайте signals.status: оценены ли сигналы, непригоден ли токен или недоступен сервис.
Изучите signals.findings и signal_codes, чтобы найти причины подтверждения. Поля not_evaluated и not_evaluated_classes, при наличии, показывают сравнения, которые не удалось выполнить.

Эти поля отвечают на разные вопросы. evaluated описывает состояние оценки сигналов, а не успешную регистрацию. Пустой signal_codes означает, что ни одна находка не повысила рекомендацию. Это не доказывает, что все сравнения запускались или визит безопасен.

Если вы используете POST /v1/signup-signals, в ответе нет части email. Его action — рекомендация только сигналов, как если бы email вернул allow. Она не заменяет ваше правило обработки email на другом шаге.

Доставляемый email тоже может потребовать подтверждения

В этом примере email разрешает регистрацию. Тот же токен предъявлен в новой операции, поэтому сигнал просит подтверждения:

{
  "action": "allow_with_email_confirmation",
  "signal_codes": ["fp_token_reused"],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_token_reused", "class": "token", "default_raises": true}
    ]
  }
}

Если читать только email.action, требование подтверждения будет пропущено. Внешнее action его включает. Находка фиксирует повторное использование токена, но не устанавливает, почему он использован снова и кто отправил запрос.

Ваше приложение реализует allow_with_email_confirmation: отправляет письмо и проверяет ссылку или код до выдачи доступа, зависящего от контроля ящика. Проверка email в Emvero не отправляет писем на проверяемый адрес. Здесь важно различать проверку и подтверждение email: подтверждение устанавливает доступ к ящику, а не уникальную личность.

Сигналы могут изменить решение email с allow на allow_with_email_confirmation. Они не могут вызвать reject, смягчить отказ по email или убрать уже требуемое подтверждение. Если внешнее действие — reject, его основание приходит от email.

Найдите свидетельства, изменившие действие

signals.findings содержит переданные находки. Поле default_raises каждой находки указывает, требует ли она подтверждения по политике Emvero по умолчанию. Верхнеуровневое signal_codes содержит коды находок с default_raises: true в порядке ответа и без повторов.

Поэтому находка может присутствовать, не меняя действие. Пример с VPN сохраняет решение email:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {
    "status": "evaluated",
    "findings": [
      {"code": "fp_network_vpn", "class": "identity", "default_raises": false}
    ]
  }
}

fp_network_vpn сообщает наблюдение сети. При default_raises: false эта находка сама не требует подтверждения. VPN, Tor, прокси и хостинг по умолчанию информационные; метка сети не доказывает злоупотребление. Читайте полученный флаг, а не угадывайте по имени кода. Словарь определен в справочнике сигналов.

Почтовые reason_codes остаются внутри email. Они объясняют свидетельства email и не становятся кодами сигналов. Подробности — в статье о результате проверки email. Разделяйте два списка при показе результата и разборе регистрации.

signal_codes может быть непустым, даже если email уже требует подтверждения или отказа. Список фиксирует сигналы, повысившие свою часть рекомендации; он не утверждает, что сигналы были единственной причиной итогового действия.

У браузерных находок и заметок разные роли

signals.probe сообщает, прочитана ли браузерная проба и какие проверки удалось выполнить. fp_probe_forged и fp_probe_automation имеют default_raises: true и могут потребовать подтверждения email. fp_probe_tampering информационная: расширения и код страницы тоже могут менять нативные свойства.

Отдельный массив signals.notes содержит rtt_extra_leg, webtransport, ua_brand, bot_claim и bot_operator. notes_version задает словарь заметок; текущая версия — 2. Заметки не входят в signal_codes и не меняют действие по умолчанию. Недоступная заметка или отсутствующая проба ограничивают свидетельства; это не ошибочный токен и не сбой всего сервиса сигналов. Каждая заметка содержит value, rules_version и group. Приложение может учитывать заметки вместе со своей историей. Наблюдения одной группы могут описывать одну причину, поэтому их нельзя считать независимыми доказательствами.

bot_claim сообщает о заявленном краулере из сети его оператора (crawler_verified), таком заявлении вне сети оператора (crawler_unverified), краулере без поддерживаемого способа проверки оператора (crawler_unchecked), заявленном инструменте (tool) либо отсутствии такого заявления (none). bot_operator называет оператора заявленного краулера. unavailable означает, что заметку не удалось оценить; none не доказывает, что посетитель — человек. Даже crawler_unverified остается информационной заметкой. Сейчас нет счетчиков повторных визитов, обнаружения ферм по кластерам или повышающего действие сигнала о заявленном инструменте.

Отсутствующая браузерная проба может дать fp_probe_not_evaluated, хотя токен действителен и signals.status равен evaluated. Операция все равно стоит пять кредитов сигналов. Значение заметки unavailable или unknown ограничивает ее вывод, а не означает недоступность всего сервиса сигналов. Новые находки и словарь заметок описаны в справочнике сигналов.

Сравните совмещенные исходы

Десять вымышленных случаев используют один контракт результата. В обычном случае находок нет. В случае VPN есть информационная находка без повышающего кода.

Случай	`email.status` / `email.action`	`signals.status`	`signal_codes`	Внешнее `action`
Обычная регистрация	`deliverable` / `allow`	`evaluated`	`[]`	`allow`
Токен в новой операции	`deliverable` / `allow`	`evaluated`	`["fp_token_reused"]`	`allow_with_email_confirmation`
Токен отсутствует	`deliverable` / `allow`	`token_unusable`	`["fp_token_absent"]`	`allow_with_email_confirmation`
Информационная находка VPN	`deliverable` / `allow`	`evaluated`	`[]`	`allow`
Сервис сигналов недоступен	`deliverable` / `allow`	`unavailable`	`[]`	`allow`
Email еще проверяется	`pending` / `allow_with_email_confirmation`	`evaluated`	`[]`	`allow_with_email_confirmation`
Email отклонен	`undeliverable` / `reject`	`evaluated`	`[]`	`reject`
Находка автоматизации браузера	`deliverable` / `allow`	`evaluated`	`["fp_probe_automation"]`	`allow_with_email_confirmation`
Информационные изменения свойств и заметки	`deliverable` / `allow`	`evaluated`	`[]`	`allow`
Браузерная проба не оценена; токен действителен	`deliverable` / `allow`	`evaluated`	`[]`	`allow`

Два исхода allow при оцененных и недоступных сигналах устанавливают разное. В обычном случае сигналы оценены и не повысили действие. В недоступном случае оценка не завершена, а рекомендацию определяет только email.

Отличайте непригодный токен от недоступных сигналов

Отсутствующий токен дает signals.status: token_unusable с fp_token_absent в signal_codes. Просроченный токен тоже дает token_unusable, но с fp_token_expired. Эти находки требуют подтверждения, когда email разрешил бы регистрацию. Они не обязывают считать посетителя нарушителем: заблокированный скрипт или долго открытая форма могут оставить обычного посетителя без пригодного токена.

Если сервис сигналов не может оценить запрос, совмещенный endpoint может вернуть HTTP 200 с signals.status: unavailable. Объект signals тогда содержит только статус:

{
  "action": "allow",
  "signal_codes": [],
  "email": {"status": "deliverable", "action": "allow"},
  "signals": {"status": "unavailable"}
}

Сервис не установил безопасность визита или отсутствие VPN. Внешнее действие следует только email. Приложение решает, какой доступ разрешен без свидетельств сигналов. Если email требовал подтверждения или отказа, требование сохранилось бы.

Даже в результате evaluated бывают пробелы. Отсутствующий IP, данные браузера или недоступное измерение могут препятствовать отдельным сравнениям. Возвращаемые not_evaluated и not_evaluated_classes описывают такие пробелы. Это не дополнительные статусы email, а отсутствие находки не доказывает успешное сравнение.

HTTP-ошибка, не позволившая получить результат регистрации, — отдельный исход интеграции. Не превращайте ее в вымышленный evaluated. Контракт ответа API разделяет исходы сигналов и ошибки запроса, подключения и учета.

Ожидаемый email не означает ожидаемые сигналы

При email.status: pending сигналы уже окончательны. Внешнее action остается allow_with_email_confirmation, пока завершается проверка email. Сохраните ID и запросите GET /v1/signup-checks/{id} через email.retry_after_ms.

Чтение возвращает текущий email с сохраненными сигналами и пересчитывает общее действие. Визит заново не оценивается. Если email позже вернет allow, сохраненный повышающий сигнал все еще потребует подтверждения. Если email вернет reject, общее действие станет reject.

pending означает незавершенную работу над email. Окончательный unknown означает, что свидетельств недостаточно для определенного ответа об адресе. Ни один статус не устанавливает некорректность адреса. Следуйте полученному действию и читайте свидетельства email, чтобы понять ограничение.

Повторите операцию без нового предъявления токена

Если ответ потерян, повторите ту же логическую операцию с сохраненным Idempotency-Key и тем же телом. В пределах 30 минут API возвращает сохраненную проверку. Повтор не оценивает сохраненные сигналы и не создает второе списание за запрос. В совмещенной проверке запись может содержать более новый результат email: повтор не обещает неизменные байты ответа, пока email завершается.

Новая операция с тем же токеном — второе предъявление. Оно может добавить fp_token_reused и потребовать подтверждения, как в первом примере. Новый ключ после потерянного ответа меняет смысл запроса. Используйте исходный ключ для транспортного повтора и новый токен для новой попытки регистрации.

Тот же ключ с другим телом дает 409 idempotency_conflict. Пока первый запрос выполняется, 409 request_in_progress указывает ждать по Retry-After. Граница операции описана в документации по идемпотентности. Чтение сохраненной проверки через GET тоже отличается от новой проверки с тем же токеном.

Связать решения с вашим процессом поможет руководство по защите от регистраций ботов. На странице Signup Protection описаны продукт и подключение формы и сервера.