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

Формат Lead[…] и плоские параметры: как отправлять лид без переделки трекера

Лидпульт принимает параметры лида в двух видах: плоские (wmkey) и вложенные (Lead[wmkey]). Объясняем, зачем нужен второй формат и как перейти с другой сети, поменяв только домен.

· 5 мин чтения

Два способа записать одни и те же параметры

В запросе на приём лида имена параметров можно писать двумя способами. Плоский формат: wmkey=1a2b3c4d&phone=79271234567. Вложенный формат: Lead[wmkey]=1a2b3c4d&Lead[phone]=79271234567. Они равнозначны, система воспринимает их одинаково и сохраняет лид без разницы.

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

Соответствие имён

Плоский видВложенный вид
wmkeyLead[wmkey]
apikeyLead[apikey]
offer_idLead[offer_id]
cityLead[city]
phoneLead[phone]
nameLead[name]
apiidLead[apiid]
sub1…sub5Lead[sub1]…Lead[sub5]

Остальные поля (информация для клиники, номер лендинга) записываются по тому же принципу.

Пример запроса во вложенном формате

curl -X POST "https://<домен-сети>/site/apiaddlead/" \
  -d "Lead[wmkey]=1a2b3c4d" \
  -d "Lead[apikey]=…" \
  -d "Lead[offer_id]=1" \
  -d "Lead[city]=Самара" \
  -d "Lead[phone]=89271234567" \
  -d "Lead[apiid]=trk-123" \
  -d "Lead[sub1]=cl8f2a91"

Обратите внимание, что здесь использован адрес /site/apiaddlead/, но это не обязательно. Любой формат работает с любым из двух адресов.

JSON и форма

Помимо вида имён важно ещё и то, как запрос упакован. Лидпульт принимает параметры:

  • в адресе (GET);
  • в теле формы (application/x-www-form-urlencoded);
  • в теле JSON.

В JSON плоский формат выглядит как обычный объект. Вложенный формат можно передать вложенным объектом {"Lead":{"phone":"…"}} или ключами со скобками. Если сомневаетесь, начните с плоского JSON: он самый читаемый.

Когда какой формат выбрать

  • Новая интеграция. Плоский формат проще и короче.
  • Переезд из другой сети. Оставьте вложенный формат и поменяйте только домен.
  • Трекер генерирует запрос по шаблону. Ориентируйтесь на то, что шаблон уже содержит.
  • Своя форма на лендинге. Поля удобнее называть плоско, а на сервере собрать запрос в нужный вид.

Что менять при переезде с другой сети

  1. Замените домен на домен Лидпульта.
  2. Выпустите в кабинете apikey и сохраните его: он показывается один раз.
  3. Замените значения wmkey, apikey и offer_id на ваши.
  4. Проверьте названия городов и номера офферов: у разных сетей они разные.
  5. Заново укажите адрес постбэка в кабинете и сопоставьте статусы.

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

Частые ошибки при вложенном формате

  • Забытая закрывающая скобка, например Lead[phone=….
  • Смешение форматов в одном запросе: часть имён плоские, часть вложенные. Лучше держаться одного.
  • Не закодированные скобки в адресе. Многие клиенты кодируют их автоматически, но при ручной сборке запроса следите за этим.
  • Пробелы в значениях (например, в имени города) без кодирования.
Если запрос вернул ошибку bad_request, не хватает обязательных полей. Проверьте, что все пять обязательных параметров присутствуют, независимо от формата.

Как проверить интеграцию после перехода на новый домен

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

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

Города и офферы при переезде

У разных сетей разные справочники офферов и городов. Номер оффера в Лидпульте не совпадает с номером в другой сети, даже если услуга та же. Город можно передавать названием («Самара») или номером. Название удобнее, потому что не требует справочника, но оно должно быть написано привычно, без сокращений и опечаток. Нераспознанный город вернёт ошибку city_not_found, а город, закрытый вам по офферу, geo_closed.

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

Практический шаблон для трекера

Если ваш трекер умеет отправлять запрос по шаблону, соберите шаблон один раз и подставляйте в него макросы самого трекера. Ниже условный пример: слева параметр сети, справа макрос трекера (названия макросов зависят от конкретного трекера, сверьтесь со справкой).

Lead[wmkey]=1a2b3c4d
Lead[apikey]=…
Lead[offer_id]=1
Lead[city]={city}
Lead[phone]={phone}
Lead[apiid]={click_id}
Lead[sub1]={click_id}
Lead[sub2]={source}

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

Совместимость и ограничения

Вложенный формат нужен для удобства переезда и не даёт дополнительных возможностей. Набор параметров, обязательность полей и коды ответов не зависят от того, как вы записали имена. Если вы заметили, что запрос в одном формате работает, а в другом нет, проверьте кодирование скобок и заголовок Content-Type: он должен соответствовать способу передачи тела. Для формы это application/x-www-form-urlencoded, для JSON application/json. Часть библиотек ставит заголовок автоматически, другие требуют указать его явно.

Памятка

Запомните три вещи: имена можно писать плоско или во вложенном виде, обязательных параметров пять, повтор с тем же apiid безопасен. Всё остальное вопрос удобства вашего трекера.

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

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

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

Формат влияет на ответ сети?

Нет. Ответ всегда один: JSON с полем status и номером лида или кодом ошибки.

Нужно ли кодировать скобки в адресе?

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

Работает ли вложенный формат в JSON?

Да, можно передать объект с ключом Lead или ключи со скобками. Плоский JSON при этом проще.

Что произойдёт, если не передать apikey?

Запрос вернёт ошибку bad_request или bad_key в зависимости от того, пропущен ли параметр целиком или значение неверно. Лид при этом не создаётся.