Формат Lead[…] и плоские параметры: как отправлять лид без переделки трекера
Лидпульт принимает параметры лида в двух видах: плоские (wmkey) и вложенные (Lead[wmkey]). Объясняем, зачем нужен второй формат и как перейти с другой сети, поменяв только домен.
Два способа записать одни и те же параметры
В запросе на приём лида имена параметров можно писать двумя способами. Плоский формат: wmkey=1a2b3c4d&phone=79271234567. Вложенный формат: Lead[wmkey]=1a2b3c4d&Lead[phone]=79271234567. Они равнозначны, система воспринимает их одинаково и сохраняет лид без разницы.
Вложенный формат привычен по другим сетям, где данные лида собираются в массив с названием Lead. Если ваш трекер или обработчик уже настроен на такой запрос, достаточно сменить домен.
Соответствие имён
| Плоский вид | Вложенный вид |
|---|---|
wmkey | Lead[wmkey] |
apikey | Lead[apikey] |
offer_id | Lead[offer_id] |
city | Lead[city] |
phone | Lead[phone] |
name | Lead[name] |
apiid | Lead[apiid] |
sub1…sub5 | Lead[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: он самый читаемый.
Когда какой формат выбрать
- Новая интеграция. Плоский формат проще и короче.
- Переезд из другой сети. Оставьте вложенный формат и поменяйте только домен.
- Трекер генерирует запрос по шаблону. Ориентируйтесь на то, что шаблон уже содержит.
- Своя форма на лендинге. Поля удобнее называть плоско, а на сервере собрать запрос в нужный вид.
Что менять при переезде с другой сети
- Замените домен на домен Лидпульта.
- Выпустите в кабинете apikey и сохраните его: он показывается один раз.
- Замените значения wmkey, apikey и offer_id на ваши.
- Проверьте названия городов и номера офферов: у разных сетей они разные.
- Заново укажите адрес постбэка в кабинете и сопоставьте статусы.
Старый трекер продолжит отправлять лиды по прежней схеме, а ответы сети можно читать по полям status и code. Обязательно проверьте разбор ответа: коды ошибок отличаются от тех, к которым вы привыкли.
Частые ошибки при вложенном формате
- Забытая закрывающая скобка, например
Lead[phone=…. - Смешение форматов в одном запросе: часть имён плоские, часть вложенные. Лучше держаться одного.
- Не закодированные скобки в адресе. Многие клиенты кодируют их автоматически, но при ручной сборке запроса следите за этим.
- Пробелы в значениях (например, в имени города) без кодирования.
Как проверить интеграцию после перехода на новый домен
После смены домена не спешите переключать весь трафик. Сначала отправьте один контрольный запрос и посмотрите на ответ: если приходит 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 в зависимости от того, пропущен ли параметр целиком или значение неверно. Лид при этом не создаётся.