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

Как отправлять лиды в Лидпульт по API: схема и примеры запросов

Если вы собираете заявки на своём лендинге или в трекере, лид нужно передать в сеть запросом на /api/lead. Покажем набор параметров, примеры и порядок обработки ответа.

· 5 мин чтения

Когда нужна отправка по API

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

Принимающий адрес один из двух: /api/lead или /site/apiaddlead/. Оба работают одинаково, поддерживают GET и POST.

Что понадобится для отправки

  • wmkey — публичный ключ вебмастера, виден в разделе «Интеграция».
  • apikey — секретный ключ, показывается при выпуске один раз.
  • offer_id — номер оффера из кабинета.
  • city — город названием («Самара») или номером.
  • phone — телефон в любом виде.

Остальные параметры необязательны: имя, apiid, метки sub1…sub5, информация для клиники и номер лендинга. Рекомендуем всегда передавать apiid, чтобы повторный запрос не создавал второй лид.

Пример запроса GET

Самый простой способ проверить связь:

https://<домен-сети>/api/lead?wmkey=1a2b3c4d&apikey=…&offer_id=1&city=Самара&phone=79271234567&name=Анна&apiid=trk-123&sub1=VK

GET удобен для проверок в браузере, но не стоит использовать его на боевом трафике: секретный ключ окажется в адресе, а адреса попадают в журналы серверов и истории.

Пример запроса POST

Для рабочей отправки используйте POST с формой или JSON:

curl -X POST "https://<домен-сети>/api/lead" \
  -H "Content-Type: application/json" \
  -d '{"wmkey":"1a2b3c4d","apikey":"…","offer_id":1,"city":"Самара",
       "phone":"+7 (927) 123-45-67","name":"Анна","apiid":"trk-123",
       "sub1":"cl8f2a91","sub2":"vk"}'

Тело запроса можно слать и как обычную форму (application/x-www-form-urlencoded). Названия параметров плоские или в формате Lead[…], подробнее о нём в отдельной статье.

Как обработать ответ

Успешный ответ приходит с кодом 200 и содержит статус и номер лида:

{ "status": "ok", "lead_id": 443110 }

Сохраните lead_id рядом с вашей заявкой: он пригодится при сверке и обращении к менеджеру. Ошибка приходит с кодом 4xx и полем code. Например, limit_reached означает, что лимит на сегодня по этому офферу и городу исчерпан. Повторять запрос на 4xx бессмысленно: ответ будет тем же.

Повтор имеет смысл только при ошибке сети или ответе 5xx. И именно тут спасает apiid: второй запрос не создаст второго лида.

Что делает сеть после приёма

Лид проходит проверки: ключи, блокировка аккаунта, статус оффера, гео, корректность телефона, дневной лимит по городу и дубль за 30 дней. Также проверяется, хватает ли у клиники свободных денег. После приёма лид получает статус «У клиента», клинике уходит сообщение в Telegram (если подключён бот) и вебхук в CRM. Вам, в свою очередь, приходит постбэк при приёме и при каждой смене статуса.

Отправка из трекера и с сервера

Часть трекеров умеет отправлять запросы на внешние адреса после получения лида (так называемые вебхуки или серверные действия). Если ваш трекер так умеет, настройте запрос на /api/lead с макросами трекера в параметрах. Если нет, отправляйте лиды с вашего сервера: форма лендинга отправляет данные на ваш обработчик, обработчик делает запрос в сеть и возвращает пользователю результат. Названия функций у разных трекеров различаются, поэтому смотрите справку своего.

Контрольный список запуска

  1. Ключи сохранены в безопасном месте, apikey не попал в код страницы.
  2. Запрос отправляется методом POST с сервера, а не из браузера.
  3. В запросе есть apiid.
  4. Ответ проверяется по полю status и по HTTP-коду.
  5. Ошибки 5xx и сетевые сбои повторяются, ошибки 4xx нет.
  6. Адрес постбэка проверен кнопкой.

Полный перечень кодов ответов и параметров смотрите в документации.

Таймауты и сетевые настройки

Запрос к API должен укладываться в разумный таймаут: короткого (около пяти секунд) обычно достаточно для соединения и ответа. Слишком маленький таймаут приводит к тому, что вы считаете запрос неудавшимся, хотя сеть уже создала лид. Именно поэтому apiid обязателен: он гарантирует, что повтор после таймаута не создаст второй лид.

Если вы отправляете много заявок подряд, не открывайте новое соединение на каждую: используйте повторное соединение клиента. И не ждите ответа в потоке, который обслуживает пользователя: ответ человеку возвращайте сразу после сохранения заявки у вас, а отправку в сеть делайте асинхронно.

Что передавать в информации для клиники

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

Безопасность отправки

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

Итог

Достаточно запомнить порядок: ключи на сервере, POST-запрос, apiid в каждом запросе, обработка кодов ответа, повтор только при сбоях сети и 5xx. Эти пять правил закрывают большую часть проблем интеграции.

Если отправка идёт из нескольких источников

Иногда лиды приходят в вашу систему с нескольких лендингов и форм. Используйте единый модуль отправки, чтобы правила (apiid, обработка ошибок, повторы) работали одинаково. Не копируйте код отправки на каждую страницу: исправление ошибки потом придётся делать в нескольких местах. Разные офферы и города передавайте параметрами модуля, а ключи храните в одной конфигурации.

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

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

Не стоит. Секретный apikey окажется виден любому, кто откроет код страницы, и им смогут воспользоваться посторонние. Отправляйте запросы с сервера.

Телефон нужно приводить к единому формату?

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

Чем отличаются /api/lead и /site/apiaddlead/?

Ничем по функциям: оба адреса принимают одинаковые параметры. Второй оставлен для совместимости с настройками, привычными по другим сетям.

Что вернёт запрос при приёме остановленного оффера?

Ответ с кодом offer_not_live и HTTP 409. Не лейте трафик на оффер, пока он на паузе.

Можно ли передать несколько телефонов одного человека?

Нет, один лид содержит один телефон. Если у пациента два номера, выберите тот, который он указал для связи.