Лидпульт

Как отправить лид по API: запрос, ответ, повтор и ошибки

Если вы работаете через трекер или собственный сервер, заявки удобнее передавать по API. Ниже — полный путь: от сбора запроса до разбора ответа и обработки ошибок.

· 6 мин чтения

Что нужно подготовить

Для отправки лида нужны:

  • публичный ключ wmkey и секретный apikey — см. выпуск ключа API;
  • номер оффера (offer_id) — он есть в кабинете;
  • город, в котором вам открыто гео по офферу;
  • телефон пользователя в любом привычном виде;
  • идентификатор лида в вашей системе (apiid) — не обязателен, но очень рекомендуется.

Домен сети вам сообщит менеджер, а в кабинете адрес подставляется автоматически в разделе «Интеграция». В примерах ниже вместо него указан <домен-сети>.

Адрес и способ отправки

Запрос отправляется методом GET или POST на любой из двух адресов:

https://<домен-сети>/api/lead
https://<домен-сети>/site/apiaddlead/

Параметры можно передать в адресе, формой или JSON. Имена бывают плоскими (wmkey=…) или в формате Lead[wmkey]=…. Если ваш трекер уже настроен по другой сети на такой формат, достаточно сменить домен.

Практический совет: для надёжности используйте POST, чтобы секретный ключ не оседал в журналах прокси и в истории браузера, как это бывает с адресом GET-запроса.

Шаги: собираем и отправляем запрос

  1. Подготовьте значения. Телефон можно передать как +7 (927) 123-45-67, 89271234567 или 9271234567, система нормализует его сама.
  2. Соберите адрес с параметрами. Пример GET-запроса:
  3. https://<домен-сети>/api/lead?wmkey=1a2b3c4d&apikey=СЕКРЕТ&offer_id=1&city=Самара&phone=79271234567&name=Анна&apiid=trk-123&sub1=VK
  4. Если в значениях есть кириллица, пробелы или спецсимволы, закодируйте их стандартным URL-кодированием: трекеры делают это сами, а при ручной сборке запроса об этом легко забыть.
  5. Отправьте запрос. Тайм-аут на вашей стороне задайте разумный: заявка не должна подвешивать форму надолго.
  6. Прочитайте ответ. Успешный ответ приходит с HTTP 200:
  7. { "status": "ok", "lead_id": 443110 }
  8. Сохраните lead_id рядом со своим apiid. По нему вы сверяете заявку в кабинете и в постбэке.
Необязательные параметры: name, apiid, sub1…sub5, info (доп. сведения для клиники) и landing_id.

Как работает повтор через apiid

Сети нестабильны: ответ бывает потерян, а трекер часто повторяет запрос. Чтобы второй раз не создавалась дублирующая заявка, передавайте apiid — идентификатор лида в вашей системе.

  • если запрос с тем же apiid уже принят, система вернёт тот же lead_id, а в ответе будет "duplicate_of_request": true;
  • новый лид при этом не создаётся и не оплачивается повторно;
  • идентификатор должен быть уникальным для заявки: не используйте одно и то же значение для разных лидов.

Это отличается от дубля по телефону: если тот же номер уже приходил по офферу за последние 30 дней, система ответит ошибкой duplicate с кодом 409.

Ошибки и что с ними делать

Не принятая заявка возвращает HTTP 4xx и код причины в теле ответа:

{ "status": "error", "code": "limit_reached", "message": "Лимит лидов на сегодня по этому офферу и городу исчерпан" }
  • bad_request (400) — не хватает обязательных полей;
  • bad_key (401) — проверьте wmkey и apikey;
  • blocked (403) — аккаунт заблокирован, напишите менеджеру;
  • geo_closed (403) — город по офферу вам не открыт;
  • offer_not_found (404) — такого оффера нет;
  • offer_not_live (409) — оффер на паузе или остановлен;
  • duplicate (409) — телефон уже приходил по офферу за 30 дней;
  • city_not_found (422) — город не распознан;
  • bad_phone (422) — телефон некорректен;
  • limit_reached (429) — дневной лимит исчерпан.

Повторять запрос имеет смысл только при сетевой ошибке или ответе 5xx. На 4xx повтор вернёт ту же ошибку. Расшифровка каждой причины — в инструкции почему лид отклонён.

Типичные ошибки

  • Повтор при 4xx. Трекер бесконечно повторяет заявку, которую система уже отклонила.
  • Отсутствует apiid. При сбое сети появляются дубли в вашей системе, а сверка с кабинетом усложняется.
  • Ключ в браузере. Секретный ключ в коде страницы виден любому посетителю.
  • Город не из списка. Название должно совпадать с городом оффера или передаваться его номером.
  • Невалидный телефон. Номера из десяти цифр без кода допустимы, но случайный набор цифр отклоняется как bad_phone.
  • Отправка без согласия пользователя. Персональные данные нельзя передавать без согласия человека на обработку: это требование закона о персональных данных.
Не отправляйте заявки, которых не оставляли реальные люди. Фейковые и мотивированные заявки недопустимы и приводят к блокировке.

Как проверить результат

  1. Отправьте тестовый запрос и убедитесь, что получили status: ok.
  2. Найдите лид в разделе «Лиды» кабинета по номеру или по apiid.
  3. Проверьте, что метки sub1–sub5 попали в лид, а в статистике они сгруппированы так, как вы ожидали.
  4. Если настроен постбэк, дождитесь его на трекере и сверьте статус. Как его настроить, написано в инструкции по постбэку.

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

Ниже — схема на псевдокоде: порядок действий важнее языка. Реальную интеграцию вы пишете на том языке, который использует ваш сервер.

отправить POST на https://<домен-сети>/api/lead
тело (форма): wmkey, apikey, offer_id, city, phone, name, apiid, sub1..sub5
если ответ 200 и status = ok: сохранить lead_id
если 4xx: записать code и message, не повторять
если сетевая ошибка или 5xx: повторить с тем же apiid через паузу

Повтор с тем же apiid безопасен: вы получите тот же lead_id, а не второй лид. Паузу между попытками увеличивайте, а число попыток ограничьте, чтобы очередь не росла при длительной недоступности.

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

Нагрузка, тайм-ауты и очередь

Если трафик большой, отправляйте заявки через очередь, а не прямо из обработчика формы. Тогда временная недоступность сети не заставит пользователя ждать, а заявка не потеряется. Хранить в очереди нужно всё, что требуется для повтора: параметры запроса и тот же apiid.

  • Тайм-аут запроса задайте в пределах нескольких секунд, чтобы не копить зависшие соединения.
  • Повторы делайте с растущей паузой, как это делает сама сеть при постбэке.
  • Не отправляйте один и тот же телефон параллельно из нескольких потоков: проверка дубля сработает, но вы получите лишние ошибки duplicate.
  • Раз в день сверяйте число отправленных заявок со статистикой в кабинете: расхождение укажет на потерянные запросы.

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

Какой метод лучше: GET или POST?

Оба работают. POST предпочтительнее, потому что секретный ключ не попадает в адресную строку и журналы доступа.

В каком формате передавать телефон?

В любом: с плюсом и скобками, с восьмёркой или без кода страны. Система нормализует номер.

Что вернётся при повторе запроса с тем же apiid?

Тот же lead_id и флаг duplicate_of_request: true. Новый лид не создаётся.

Можно ли отправлять лиды из браузера пользователя?

Не стоит: ключ станет видимым. Отправляйте заявки с сервера или из трекера.

Через какое время приходит постбэк после приёма?

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