Как выпустить ключ API и безопасно им пользоваться
Для отправки заявок по API нужны два ключа: публичный wmkey и секретный apikey. Пошагово разберём, где их взять, почему секретный ключ показывается один раз и как действовать при потере.
Два ключа и зачем они нужны
Отправка лидов в Лидпульт защищена парой ключей. Вместе они подтверждают, что запрос идёт именно от вас:
- wmkey — публичный ключ вебмастера. Он виден в кабинете в разделе «Интеграция» и в параметрах ссылок. Это идентификатор, а не секрет.
- apikey — секретный ключ API. Выпускается в кабинете и показывается один раз. Именно он защищает от отправки заявок от вашего имени посторонними.
Если трекер или сервер использует формат Lead[wmkey] и Lead[apikey], значения те же, меняется только запись параметров. Подробнее — в инструкции о формате Lead[…].
Описание всех параметров запроса и кодов ответа есть в документации API.
Шаги: выпуск секретного ключа
- Войдите в кабинет и откройте раздел «Интеграция». Если вы ещё не входили, сначала прочитайте инструкцию по входу.
- Найдите блок «Ключ API для отправки лидов». Там указан ваш wmkey и кнопка выпуска ключа.
- Нажмите кнопку выпуска. Система покажет новый ключ в поле «Ваш новый ключ API».
- Сразу скопируйте ключ и сохраните его в менеджере паролей или в защищённом хранилище секретов вашего трекера. Закрыв страницу, вы больше не увидите ключ целиком.
- Подставьте ключ в настройки трекера или сервера. Не вставляйте его в код лендингов и скрипты, которые загружаются в браузер посетителя: любой человек сможет открыть исходный код страницы.
- Отправьте тестовую заявку и проверьте ответ. Успешный ответ содержит
"status": "ok"и номер лида. Как собрать запрос, показано в инструкции по отправке лида.
Перевыпуск ключа
Перевыпуск нужен, если вы потеряли ключ, передали его человеку, который больше не работает с вами, или заподозрили утечку. При перевыпуске происходит следующее:
- создаётся новый ключ, который вы видите один раз;
- старый ключ сразу перестаёт работать — все запросы с ним получат ответ
bad_keyс HTTP-статусом 401.
Поэтому порядок действий должен быть таким:
- Выберите время с минимальным трафиком, чтобы остановка была незаметной.
- Выпустите новый ключ и сохраните его.
- Обновите ключ во всех местах: в трекере, в серверных скриптах, в формах и интеграциях.
- Проверьте отправку тестовой заявкой и убедитесь, что по основному потоку лиды снова принимаются.
- Просмотрите последние лиды в кабинете: нет ли заявок, которые не дошли за время замены.
Если трекер при ошибке 401 повторяет запрос, это бесполезно: на ошибки 4xx повтор вернёт тот же ответ. Повторять нужно только при сетевой ошибке или ответе 5xx.
Где хранить ключ и чего избегать
- Храните ключ в переменных окружения сервера или в секретах трекера, но не в репозитории с кодом.
- Не отправляйте ключ в мессенджерах и по электронной почте: переписка остаётся в истории.
- Не используйте ключ на стороне браузера. Отправляйте лиды сервером или трекером, а не JavaScript на странице.
- Давайте доступ к ключу только тем, кому он действительно нужен.
- Если ключ засветился на скриншоте, в записи экрана или в публичном репозитории, считайте его скомпрометированным и перевыпустите.
Публичный wmkey можно указывать в ссылках и постбэках, но помните: зная его, злоумышленник всё равно не отправит заявку без секретного ключа.
Типичные ошибки
- Ключ вставлен с пробелом или переносом строки. API вернёт
bad_key. Проверьте, что в значении нет невидимых символов. - Перепутаны wmkey и apikey. Публичный ключ в поле секретного не подойдёт.
- Старый ключ остался в части интеграций. После перевыпуска часть заявок молча отклоняется. Проверяйте все источники, включая запасные.
- Ключ не сохранён. Закрытая вкладка — потерянный ключ.
- Блокировка аккаунта. Ответ
blocked(403) означает, что дело не в ключе: аккаунт заблокирован, нужно написать менеджеру. - Ключ в клиентском коде. Он станет доступен всем посетителям страницы.
bad_key. Если код другой, ключи в порядке, ищите причину в параметрах заявки.Что проверить после выпуска
- Что в запросе есть
wmkey,apikey,offer_id,cityиphone. - Что
offer_idсоответствует офферу, который вам доступен, и город входит в открытое для вас гео. - Что трекер передаёт
apiid— тогда при повторе запроса дубль не создастся. - Что в кабинете появился тестовый лид и что постбэк, если он настроен, пришёл на ваш трекер.
Дальше настройте постбэк, чтобы статусы лидов возвращались в вашу систему автоматически.
Как проверить, что ключ действует
Самый простой способ — отправить тестовую заявку и посмотреть ответ. Если нужно проверить только ключи, не тратя лимит оффера, достаточно ответа на запрос: код bad_key означает проблему с ключами, любой другой код говорит о том, что ключи приняты, а вопрос в остальных параметрах.
- Соберите запрос с актуальным ключом и заведомо корректным телефоном.
- Отправьте его на адрес API и посмотрите HTTP-статус: 200 — заявка принята, 401 — ключ не подошёл.
- Если статус 403, проверьте: ответ
blockedозначает блокировку аккаунта, аgeo_closed— что город не открыт. - После успешной отправки найдите лид в кабинете и убедитесь, что он принадлежит вашему аккаунту.
Автоматизируйте проверку: в трекере или на сервере заведите уведомление на случай массовых ответов 401. Это почти всегда значит, что ключ перевыпущен или изменён в одном месте, а в другом остался прежним.
Ключ и безопасность персональных данных
Через API вы передаёте персональные данные людей: имя и телефон. Лидпульт хранит их только на серверах в России, как требует закон о персональных данных, но ответственность за законность сбора лежит на вас: пользователь должен знать, кому и зачем он оставляет заявку.
- Передавайте заявки только по защищённому соединению.
- Не копируйте телефоны в таблицы, доступные посторонним.
- Не храните лишние данные в логах трекера дольше, чем нужно.
- Работайте только с заявками реальных людей, оставивших их добровольно.
Вопросы и ответы
Можно ли посмотреть секретный ключ повторно?
Нет, ключ показывается один раз при выпуске. Если он потерян, выпустите новый.
Что будет со старым ключом после перевыпуска?
Он перестанет работать сразу. Запросы с ним получат ответ с кодом bad_key.
Нужен ли apikey для ссылок потоков?
Нет, ссылки потоков и короткие ссылки используют только публичные параметры. Секретный ключ нужен для отправки лидов по API.
Влияет ли перевыпуск на уже принятые лиды?
Нет, принятые лиды, их статусы и начисления остаются прежними.
Можно ли иметь несколько ключей одновременно?
В описанной схеме действует один актуальный секретный ключ: новый заменяет старый.
Нужно ли выпускать новый ключ при смене домена или трекера?
Не обязательно, ключ привязан к вашему аккаунту, а не к трекеру. Но при смене инструмента удобно перевыпустить ключ, чтобы старый перестал действовать.