Лидпульт
Трекеры и постбэки

Серверная отправка форм: надёжная схема с очередью и повторами

Серверная отправка прячет ключи от посетителей и позволяет повторять запросы без потери заявок. Разбираем схему из четырёх шагов, которая выдерживает сбои сети и перегрузку.

· 5 мин чтения

Почему отправлять нужно с сервера

Из браузера пользователя в API отправлять нельзя по двум причинам. Первая: секретный ключ окажется в коде страницы. Вторая: вы не контролируете соединение пользователя. Он может закрыть вкладку, потерять сеть в метро, использовать блокировщик. Заявка исчезнет, а вы потратили на клик деньги.

Сервер находится под вашим контролем. Он принимает форму, сохраняет заявку и затем занимается доставкой в сеть, повторяя при необходимости. Для пользователя всё выглядит одинаково, а потерь заявок гораздо меньше.

Схема из четырёх шагов

  1. Приём. Сервер получает форму, проверяет поля, согласие и антиспам.
  2. Сохранение. Заявка пишется в базу со статусом «ожидает», создаётся apiid.
  3. Отправка. Обработчик отправляет запрос в API с таймаутом и обновляет статус по ответу.
  4. Подтверждение. Пользователю возвращается результат: принято или временно недоступно.

Шаги два и три можно разделить: сохранить заявку мгновенно и вернуть подтверждение, а отправку выполнять фоном. Тогда задержки сети не замедляют страницу.

Состояния заявки в вашей базе

СостояниеКогдаСледующее действие
ожидаетСохранена, ещё не отправляласьОтправить
отправленаОтвет 200, сохранён lead_idЖдать постбэков
отказОтвет 4xx, сохранён кодРазобрать причину
повторСеть или 5xxПовторить с паузой
проблемаИсчерпаны повторыРучная проверка

Храните для каждой заявки apiid, время попыток, последний код ответа и lead_id. Эти поля пригодятся при сверке.

Повторы и паузы

Повторяйте только при сетевых ошибках и ответах 5xx, всегда с тем же apiid. Паузу увеличивайте: например, через 10 секунд, минуту, пять минут, полчаса. Ограничьте число попыток, после чего переведите заявку в статус «проблема» и оповестите ответственного. Не повторяйте после 4xx: ответ не изменится. Исключение limit_reached и offer_not_live: заявку можно придержать и вернуться к ней, когда условия изменятся, но не заваливайте API запросами каждую секунду.

Параллельная отправка и атомарность

Сеть проверяет дневной лимит и дубль атомарно: при одновременных заявках лимит не превышается. Значит, несколько воркеров на вашей стороне могут отправлять заявки параллельно без риска нарушить правила. Но следите за тем, чтобы одну и ту же заявку не взяли два воркера: используйте блокировку записи или статус «в обработке». Даже если это произошло, apiid защитит от дубля лида.

Таймауты и ответ пользователю

Установите таймаут запроса к API в пределах нескольких секунд. Пользователю не нужно ждать результата сети: достаточно подтвердить, что заявка принята вами. Но если вы подтверждаете приём, обязаны довести заявку до сети. Если по итогам повторов заявка не ушла, свяжитесь с человеком другим путём или хотя бы зафиксируйте проблему и передайте её вручную: добавить заявку можно в кабинете, ручной способ в Лидпульте предусмотрен.

Журнал и мониторинг

  • Записывайте каждую попытку: время, apiid, код ответа, длительность.
  • Следите за числом заявок в статусе «ожидает» и «проблема»: рост означает сбой.
  • Сверяйте число отправленных заявок с лидами в кабинете раз в день.
  • Настройте оповещение на bad_key, blocked и длительную недоступность API.

Общие принципы и коды ответов описаны в документации API.

Пример минимальной реализации

Для небольшого проекта достаточно трёх таблиц или файлов: заявки, попытки отправки, журнал ошибок. При приёме формы сервер записывает заявку со статусом «ожидает» и сразу пытается отправить её в сеть. Если ответ 200, статус меняется на «отправлена». Если сетевая ошибка или 5xx, статус «повтор», и планировщик каждые несколько минут пробегает по заявкам в этом статусе и пробует снова, пока не исчерпает лимит попыток. Для заявок в статусе «проблема» отправляется уведомление ответственному.

Такая реализация укладывается в сотню строк кода, не требует специальной инфраструктуры и уже защищает от большинства потерь, связанных с кратковременными сбоями сети или перезапусками сервера.

Что хранить и сколько

Минимальный набор полей: внутренний номер заявки, apiid, город, оффер, метки, статус отправки, номер лида из ответа, время и результат каждой попытки. Телефон и имя храните только пока заявка не обработана и пока это необходимо для повтора, затем удаляйте или обезличивайте в соответствии с вашей политикой и законом о персональных данных. Не накапливайте персональные данные пациентов без необходимости: чем меньше вы храните, тем меньше риск и обязанностей.

Масштабирование

Когда заявок становится много, заменяйте самодельный планировщик на очередь сообщений или готовый механизм фоновых задач вашей платформы. Ограничьте параллелизм воркеров разумным числом: сеть корректно обрабатывает одновременные заявки, но бесконтрольная нагрузка на вашу базу и канал только создаёт проблемы. Следите за длиной очереди и временем от приёма заявки до отправки: рост этих показателей сигнализирует о проблемах раньше, чем жалобы пользователей.

Пример запроса из серверного кода

Независимо от языка программирования серверный запрос состоит из тех же элементов: адрес, метод POST, тело с параметрами, таймаут, обработка ответа. Условная последовательность выглядит так.

payload = { wmkey, apikey, offer_id, city, phone, name, apiid, sub1..sub5 }
res = http.post("https://<домен-сети>/api/lead", payload, timeout=5s)
if res.network_error or res.status >= 500 -> поставить на повтор
elif res.status == 200 and res.json.status == "ok" -> сохранить lead_id
else -> записать res.json.code, не повторять

Обратите внимание на третью строку: проверять нужно и HTTP-код, и поле status в теле ответа, а при ошибке сохранять поле code. Это позволит потом анализировать причины отказов по заявкам.

Безопасность обработчика формы

Обработчик, который принимает данные пациентов и отправляет их дальше, должен работать только по защищённому соединению, проверять входные данные и не раскрывать внутренних подробностей в ответах. Ограничьте размер тела запроса, чтобы никто не загрузил в форму тяжёлые данные, экранируйте всё, что выводите обратно на страницу, и не пишите ключи и персональные данные в журналы. Периодически обновляйте программное обеспечение сервера. Утечка данных пациентов через вашу форму серьёзная ответственность и для вас, и для клиники.

Вопросы и ответы

Нужна ли очередь для небольшого проекта?

Не обязательно. Для малого объёма хватит сохранения заявки в базу и повтора в одном процессе. Очередь нужна при росте нагрузки.

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

Разобрать вручную: передать менеджеру или добавить в кабинете вручную. Главное, не потерять человека, который ждёт звонка.

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

В документации пакетная отправка не описана: один запрос создаёт один лид.

Как защитить обработчик формы от спама?

Ограничение частоты по адресу, поле-ловушка, проверка времени заполнения и CAPTCHA при необходимости.