Документация API

Noisecut API — антиспам и оценка качества заявок

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

Что делает Отсекает спам, выделяет другой регион и помогает менеджерам не тратить время на мусорные лиды.
Как работает POST-запрос + HMAC-подпись + проверка подписки + анализ содержимого заявки.
Что возвращает Score, итоговую категорию, список причин и нормализованные данные для интерфейса и CRM.

1. Endpoint

Все заявки отправляются на один endpoint методом POST.

POST https://noisecut.ru/netcat/modules/noisecut/ingest.php

2. Формат запроса

Сервис принимает JSON и обычный form-data / x-www-form-urlencoded. Рекомендуемый формат — JSON.

Параметр Тип Обязательный Описание
sitestringДаДомен сайта клиента. Должен совпадать с данными, для которых выдан ключ.
namestringНетИмя клиента или ФИО.
phonestringНетТелефон клиента в любом удобном формате.
textstringНетКомментарий, текст заявки, данные квиза или анкеты.
timestampintДаUnix timestamp. Входит в подпись запроса.
signaturestringДаHMAC SHA256 подпись.
IDintДаID пользователя в системе Noisecut. По нему проверяется подписка.
penaltyintНетДополнительный штраф, если нужен внешний автоматический флаг.
Минимально для работы обязательны site, timestamp, signature и ID. Но для качественной оценки желательно всегда передавать name, phone и text.

3. Подпись запроса

Подпись защищает заявку от подмены. Сервер и клиент должны формировать строку для подписи абсолютно одинаково.

Нормализация

$name_norm  = trim(mb_strtolower($name, 'UTF-8'));
$phone_norm = preg_replace('/\D+/', '', $phone);
$text_norm  = trim(mb_strtolower($text, 'UTF-8'));

Строка для подписи

$data_string = $site . '|' . $timestamp . '|' . $name_norm . '|' . $phone_norm . '|' . $text_norm;

Генерация подписи

$signature = hash_hmac('sha256', $data_string, $secret);
Любое отличие в нормализации — например лишний пробел, другой timestamp, пропущенный text или другой домен в поле site — приведёт к ошибке Invalid signature.

4. Пример на PHP

Ниже — готовый тестовый пример, который отправляет заявку на endpoint и выводит ответ сервера.

<?php
$endpoint = 'https://noisecut.ru/netcat/modules/noisecut/ingest.php';

// данные сайта клиента
$site = 'noisecut.ru';
$secret = 'YOUR_SECRET_KEY';

// данные заявки
$name = 'Дмитрий';
$phone = '+7 (999) 123-45-67';
$timestamp = time();
$text = 'Хочу купить генератор';

// нормализация — должна совпадать с сервером
$name_norm  = trim(mb_strtolower($name, 'UTF-8'));
$phone_norm = preg_replace('/\D+/', '', $phone);
$text_norm  = trim(mb_strtolower($text, 'UTF-8'));

// строка для подписи
$data_string = $site . '|' . $timestamp . '|' . $name_norm . '|' . $phone_norm . '|' . $text_norm;

// подпись
$signature = hash_hmac('sha256', $data_string, $secret);

$post_data = [
    'site' => $site,
    'name' => $name,
    'phone' => $phone,
    'text' => $text,
    'timestamp' => $timestamp,
    'signature' => $signature,
    'ID' => 1
];

$json = json_encode($post_data, JSON_UNESCAPED_UNICODE);

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $json,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($json)
    ],
    CURLOPT_TIMEOUT => 10,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curl_error = curl_error($ch);
curl_close($ch);

echo '<pre>';
echo "HTTP CODE: " . $http_code . "\n";
echo "CURL ERROR: " . $curl_error . "\n";
echo "RESPONSE: " . $response . "\n";
echo '</pre>';

5. Ответ API

Если заявка обработана, API возвращает статус ok, исходные данные запроса и блок анализа.

{
  "status": "ok",
  "site": "noisecut.ru",
  "user_id": 1,
  "paid_till": "2026-04-26 00:00:00",
  "request": {
    "name": "Дмитрий",
    "phone": "+7 (999) 123-45-67",
    "text": "Хочу купить генератор",
    "timestamp": "1710000000"
  },
  "analysis": {
    "score": 6,
    "result_code": "other_region",
    "result_label": "Другой регион",
    "css_class": "good-other",
    "reasons": [
      {
        "code": "phone_other_region",
        "text": "Номер относится к другому региону"
      }
    ],
    "normalized": {
      "phone": "79991234567",
      "name": "Дмитрий",
      "text": "хочу купить генератор",
      "phone_info": "tele2 москва"
    }
  }
}

6. Шкала оценок

Итоговая категория зависит от суммарного score.

Диапазон Категория Код CSS-класс
0–4 Хорошая заявка good good-order
5–6 Другой регион other_region good-other
7–8 Подозрительная suspicious suspicious-order
9+ Спам spam spam-order
Практический смысл шкалы: good — нормальный лид, other_region — нецелевой лид, suspicious — требует внимания, spam — можно скрывать, фильтровать или отправлять отдельно.

7. Причины и коды

Блок reasons объясняет, какие признаки сработали при анализе.

Телефон

phone_invalidТелефон не похож на корректный российский номер.
phone_low_entropyСлишком простой или искусственный номер.
phone_not_russiaТелефон определён как не российский.
phone_unknown_regionНе удалось определить регион или оператора.
phone_other_regionНомер относится к другому региону.

Текст и имя

text_profanity / name_profanityНецензурная лексика.
text_gibberish / name_gibberishПохоже на бессмысленный набор символов.
text_link / name_linkСсылка, домен или HTML-ссылка.
text_special_chars / name_special_charsПодозрительные спецсимволы.
text_soft_spam / name_soft_spamПодозрительный шаблон текста.
text_vinНайден VIN или техкод.
text_contains_emailВ тексте указан email. Это служебная метка, без штрафа.
text_structured_formТекст похож на анкету или квиз. Это служебная метка, без штрафа.
automation_penaltyВнешний штраф, переданный параметром penalty.

8. Нормализованные данные

В блоке normalized API возвращает очищенные и приведённые к стабильному формату данные.

Что входит

{
  "phone": "79991234567",
  "name": "Дмитрий",
  "text": "хочу купить генератор",
  "phone_info": "tele2 москва"
}

Зачем это нужно

phoneНормализованный номер для хранения, поиска и аналитики.
nameОчищенное имя без мусора.
textТекст в стабильном виде после базовой нормализации.
phone_infoОператор и регион, определённые по номеру телефона.

9. Ошибки

Если что-то не так с запросом, API вернёт ошибку и соответствующий HTTP-код.

HTTP Ошибка Когда возникает
400Missing required fieldsНе переданы обязательные поля.
400Missing user IDНе передан ID.
403Invalid signatureПодпись не совпала.
403Subscription expiredПодписка пользователя истекла.
403Invalid source domainOrigin/Referer не совпадает с доменом сайта.
404User not foundПользователь с таким ID не найден.
404Site not foundДля указанного сайта не найден ключ.
405Method not allowedИспользован не POST-запрос.

10. Безопасность

В API уже встроены базовые проверки, которые защищают endpoint от случайных и злонамеренных вызовов.

HMAC-подпись

Исключает подмену данных, если секретный ключ хранится только на стороне клиента и сервера.

Проверка домена

Сверяется домен источника запроса через Origin или Referer.

Проверка подписки

Запрос обрабатывается только для активного пользователя с действующей подпиской.

11. Рекомендации по интеграции

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

Передавайте text всегда.Даже короткий комментарий улучшает качество анализа и подписи.
Считайте подпись один раз.Тот же timestamp, который вошёл в подпись, должен уйти и в запрос.
Используйте JSON.Так проще отлаживать и логировать запросы целиком.
Не меняйте site на лету.Домен в подписи должен совпадать с реальным сайтом клиента.
Сохраняйте весь ответ API.Особенно score, result_code и reasons. Это пригодится для аналитики и CRM.
Структурированные заявки не нужно штрафовать.Если текст похож на анкету и содержит email, API пометит это отдельными reason-кодами без лишнего штрафа.
Типовой сценарий: хорошие заявки показывать менеджеру сразу, другой регион — помечать как нецелевой, подозрительные — отправлять на ручную проверку, спам — скрывать или складывать отдельно.

12. Частые вопросы

Нужно ли передавать email отдельно?

Нет. Если email есть внутри текста заявки, API это увидит и пометит reason-кодом text_contains_email.

Что делать с заявками из другого региона?

Обычно это не спам, а нецелевой лид. Их можно не удалять, а просто снижать в приоритете.

Можно ли передавать квиз или анкету целиком?

Да. Структурированный текст вида «Поле: значение» поддерживается и не должен считаться спамом сам по себе.

Что, если подпись не совпадает?

Проверьте, что клиент и сервер одинаково нормализуют name, phone и text, и используют один и тот же timestamp.