Как отправлять лиды в Лидпульт по API: схема и примеры запросов
Если вы собираете заявки на своём лендинге или в трекере, лид нужно передать в сеть запросом на /api/lead. Покажем набор параметров, примеры и порядок обработки ответа.
Когда нужна отправка по 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=VKGET удобен для проверок в браузере, но не стоит использовать его на боевом трафике: секретный ключ окажется в адресе, а адреса попадают в журналы серверов и истории.
Пример запроса 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 бессмысленно: ответ будет тем же.
Что делает сеть после приёма
Лид проходит проверки: ключи, блокировка аккаунта, статус оффера, гео, корректность телефона, дневной лимит по городу и дубль за 30 дней. Также проверяется, хватает ли у клиники свободных денег. После приёма лид получает статус «У клиента», клинике уходит сообщение в Telegram (если подключён бот) и вебхук в CRM. Вам, в свою очередь, приходит постбэк при приёме и при каждой смене статуса.
Отправка из трекера и с сервера
Часть трекеров умеет отправлять запросы на внешние адреса после получения лида (так называемые вебхуки или серверные действия). Если ваш трекер так умеет, настройте запрос на /api/lead с макросами трекера в параметрах. Если нет, отправляйте лиды с вашего сервера: форма лендинга отправляет данные на ваш обработчик, обработчик делает запрос в сеть и возвращает пользователю результат. Названия функций у разных трекеров различаются, поэтому смотрите справку своего.
Контрольный список запуска
- Ключи сохранены в безопасном месте, apikey не попал в код страницы.
- Запрос отправляется методом POST с сервера, а не из браузера.
- В запросе есть apiid.
- Ответ проверяется по полю status и по HTTP-коду.
- Ошибки 5xx и сетевые сбои повторяются, ошибки 4xx нет.
- Адрес постбэка проверен кнопкой.
Полный перечень кодов ответов и параметров смотрите в документации.
Таймауты и сетевые настройки
Запрос к API должен укладываться в разумный таймаут: короткого (около пяти секунд) обычно достаточно для соединения и ответа. Слишком маленький таймаут приводит к тому, что вы считаете запрос неудавшимся, хотя сеть уже создала лид. Именно поэтому apiid обязателен: он гарантирует, что повтор после таймаута не создаст второй лид.
Если вы отправляете много заявок подряд, не открывайте новое соединение на каждую: используйте повторное соединение клиента. И не ждите ответа в потоке, который обслуживает пользователя: ответ человеку возвращайте сразу после сохранения заявки у вас, а отправку в сеть делайте асинхронно.
Что передавать в информации для клиники
Поле info передаёт клинике дополнительные сведения: например, интересующую услугу или удобное время звонка. Пишите только то, что человек сам указал в форме. Не добавляйте медицинские подробности, которых не просили, и не обещайте от имени клиники цены или результаты лечения: это относится к рекламе медицинских услуг и регулируется законом о рекламе. Корректнее ограничиваться нейтральными данными: услуга, город, пожелание по времени.
Безопасность отправки
Секретный apikey должен храниться только на сервере: в переменных окружения или в защищённом хранилище, но не в коде страницы и не в публичном репозитории. Если ключ всё же попал туда, где его могут увидеть посторонние, немедленно перевыпустите его в кабинете: старый перестанет работать сразу. Подробнее об этом в отдельной статье документации.
Итог
Достаточно запомнить порядок: ключи на сервере, POST-запрос, apiid в каждом запросе, обработка кодов ответа, повтор только при сбоях сети и 5xx. Эти пять правил закрывают большую часть проблем интеграции.
Если отправка идёт из нескольких источников
Иногда лиды приходят в вашу систему с нескольких лендингов и форм. Используйте единый модуль отправки, чтобы правила (apiid, обработка ошибок, повторы) работали одинаково. Не копируйте код отправки на каждую страницу: исправление ошибки потом придётся делать в нескольких местах. Разные офферы и города передавайте параметрами модуля, а ключи храните в одной конфигурации.
Вопросы и ответы
Можно ли отправлять запрос прямо из браузера пользователя?
Не стоит. Секретный apikey окажется виден любому, кто откроет код страницы, и им смогут воспользоваться посторонние. Отправляйте запросы с сервера.
Телефон нужно приводить к единому формату?
Нет, система понимает телефон в любом виде: с плюсом, скобками, восьмёркой или без кода. Некорректный номер вернёт ошибку bad_phone.
Чем отличаются /api/lead и /site/apiaddlead/?
Ничем по функциям: оба адреса принимают одинаковые параметры. Второй оставлен для совместимости с настройками, привычными по другим сетям.
Что вернёт запрос при приёме остановленного оффера?
Ответ с кодом offer_not_live и HTTP 409. Не лейте трафик на оффер, пока он на паузе.
Можно ли передать несколько телефонов одного человека?
Нет, один лид содержит один телефон. Если у пациента два номера, выберите тот, который он указал для связи.