Как отправить лид по API: запрос, ответ, повтор и ошибки
Если вы работаете через трекер или собственный сервер, заявки удобнее передавать по API. Ниже — полный путь: от сбора запроса до разбора ответа и обработки ошибок.
Что нужно подготовить
Для отправки лида нужны:
- публичный ключ
wmkeyи секретныйapikey— см. выпуск ключа API; - номер оффера (
offer_id) — он есть в кабинете; - город, в котором вам открыто гео по офферу;
- телефон пользователя в любом привычном виде;
- идентификатор лида в вашей системе (
apiid) — не обязателен, но очень рекомендуется.
Домен сети вам сообщит менеджер, а в кабинете адрес подставляется автоматически в разделе «Интеграция». В примерах ниже вместо него указан <домен-сети>.
Адрес и способ отправки
Запрос отправляется методом GET или POST на любой из двух адресов:
https://<домен-сети>/api/lead
https://<домен-сети>/site/apiaddlead/Параметры можно передать в адресе, формой или JSON. Имена бывают плоскими (wmkey=…) или в формате Lead[wmkey]=…. Если ваш трекер уже настроен по другой сети на такой формат, достаточно сменить домен.
Практический совет: для надёжности используйте POST, чтобы секретный ключ не оседал в журналах прокси и в истории браузера, как это бывает с адресом GET-запроса.
Шаги: собираем и отправляем запрос
- Подготовьте значения. Телефон можно передать как
+7 (927) 123-45-67,89271234567или9271234567, система нормализует его сама. - Соберите адрес с параметрами. Пример GET-запроса:
https://<домен-сети>/api/lead?wmkey=1a2b3c4d&apikey=СЕКРЕТ&offer_id=1&city=Самара&phone=79271234567&name=Анна&apiid=trk-123&sub1=VK- Если в значениях есть кириллица, пробелы или спецсимволы, закодируйте их стандартным URL-кодированием: трекеры делают это сами, а при ручной сборке запроса об этом легко забыть.
- Отправьте запрос. Тайм-аут на вашей стороне задайте разумный: заявка не должна подвешивать форму надолго.
- Прочитайте ответ. Успешный ответ приходит с HTTP 200:
{ "status": "ok", "lead_id": 443110 }- Сохраните
lead_idрядом со своимapiid. По нему вы сверяете заявку в кабинете и в постбэке.
name, apiid, sub1…sub5, info (доп. сведения для клиники) и landing_id.Как работает повтор через apiid
Сети нестабильны: ответ бывает потерян, а трекер часто повторяет запрос. Чтобы второй раз не создавалась дублирующая заявка, передавайте apiid — идентификатор лида в вашей системе.
- если запрос с тем же
apiidуже принят, система вернёт тот жеlead_id, а в ответе будет"duplicate_of_request": true; - новый лид при этом не создаётся и не оплачивается повторно;
- идентификатор должен быть уникальным для заявки: не используйте одно и то же значение для разных лидов.
Это отличается от дубля по телефону: если тот же номер уже приходил по офферу за последние 30 дней, система ответит ошибкой duplicate с кодом 409.
Ошибки и что с ними делать
Не принятая заявка возвращает HTTP 4xx и код причины в теле ответа:
{ "status": "error", "code": "limit_reached", "message": "Лимит лидов на сегодня по этому офферу и городу исчерпан" }bad_request(400) — не хватает обязательных полей;bad_key(401) — проверьте wmkey и apikey;blocked(403) — аккаунт заблокирован, напишите менеджеру;geo_closed(403) — город по офферу вам не открыт;offer_not_found(404) — такого оффера нет;offer_not_live(409) — оффер на паузе или остановлен;duplicate(409) — телефон уже приходил по офферу за 30 дней;city_not_found(422) — город не распознан;bad_phone(422) — телефон некорректен;limit_reached(429) — дневной лимит исчерпан.
Повторять запрос имеет смысл только при сетевой ошибке или ответе 5xx. На 4xx повтор вернёт ту же ошибку. Расшифровка каждой причины — в инструкции почему лид отклонён.
Типичные ошибки
- Повтор при 4xx. Трекер бесконечно повторяет заявку, которую система уже отклонила.
- Отсутствует apiid. При сбое сети появляются дубли в вашей системе, а сверка с кабинетом усложняется.
- Ключ в браузере. Секретный ключ в коде страницы виден любому посетителю.
- Город не из списка. Название должно совпадать с городом оффера или передаваться его номером.
- Невалидный телефон. Номера из десяти цифр без кода допустимы, но случайный набор цифр отклоняется как
bad_phone. - Отправка без согласия пользователя. Персональные данные нельзя передавать без согласия человека на обработку: это требование закона о персональных данных.
Как проверить результат
- Отправьте тестовый запрос и убедитесь, что получили
status: ok. - Найдите лид в разделе «Лиды» кабинета по номеру или по
apiid. - Проверьте, что метки sub1–sub5 попали в лид, а в статистике они сгруппированы так, как вы ожидали.
- Если настроен постбэк, дождитесь его на трекере и сверьте статус. Как его настроить, написано в инструкции по постбэку.
Пример отправки из серверного кода
Ниже — схема на псевдокоде: порядок действий важнее языка. Реальную интеграцию вы пишете на том языке, который использует ваш сервер.
отправить POST на https://<домен-сети>/api/lead
тело (форма): wmkey, apikey, offer_id, city, phone, name, apiid, sub1..sub5
если ответ 200 и status = ok: сохранить lead_id
если 4xx: записать code и message, не повторять
если сетевая ошибка или 5xx: повторить с тем же apiid через паузуПовтор с тем же apiid безопасен: вы получите тот же lead_id, а не второй лид. Паузу между попытками увеличивайте, а число попыток ограничьте, чтобы очередь не росла при длительной недоступности.
Логируйте код ответа вместе с идентификатором заявки: так вы быстро найдёте, почему часть заявок не дошла. Отдельно считайте долю заявок с кодами duplicate и bad_phone: рост этих долей сигнализирует о проблемах с источником трафика.
Нагрузка, тайм-ауты и очередь
Если трафик большой, отправляйте заявки через очередь, а не прямо из обработчика формы. Тогда временная недоступность сети не заставит пользователя ждать, а заявка не потеряется. Хранить в очереди нужно всё, что требуется для повтора: параметры запроса и тот же apiid.
- Тайм-аут запроса задайте в пределах нескольких секунд, чтобы не копить зависшие соединения.
- Повторы делайте с растущей паузой, как это делает сама сеть при постбэке.
- Не отправляйте один и тот же телефон параллельно из нескольких потоков: проверка дубля сработает, но вы получите лишние ошибки
duplicate. - Раз в день сверяйте число отправленных заявок со статистикой в кабинете: расхождение укажет на потерянные запросы.
Вопросы и ответы
Какой метод лучше: GET или POST?
Оба работают. POST предпочтительнее, потому что секретный ключ не попадает в адресную строку и журналы доступа.
В каком формате передавать телефон?
В любом: с плюсом и скобками, с восьмёркой или без кода страны. Система нормализует номер.
Что вернётся при повторе запроса с тем же apiid?
Тот же lead_id и флаг duplicate_of_request: true. Новый лид не создаётся.
Можно ли отправлять лиды из браузера пользователя?
Не стоит: ключ станет видимым. Отправляйте заявки с сервера или из трекера.
Через какое время приходит постбэк после приёма?
Постбэк вызывается при приёме лида и при каждой смене статуса. При сбое повтор идёт до восьми раз с растущей паузой.