Лидпульт

Приём заявок по API: ответы на частые вопросы

Короткая выжимка из документации для тех, кто настраивает отправку лидов: адреса, параметры, ответы и разбор самых частых ошибок.

Как устроен запрос

Лид отправляется запросом GET или POST на адрес /api/lead или /site/apiaddlead/ домена сети. Параметры передаются в адресе, формой или JSON. Названия можно писать плоскими (wmkey=…) или в формате Lead[wmkey]=….

Обязательные: wmkey, apikey, offer_id, city, phone. Необязательные: name, apiid, sub1…sub5, info, landing_id. Полное описание — в документации API.

Что происходит при приёме

Система проверяет ключи, блокировку вебмастера, статус оффера, гео, телефон, дневной лимит, дубль за 30 дней и наличие свободных денег у клиники. Если проверки пройдены, заявка получает lead_id, уходит клинике и запускает постбэк.

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

На какие адреса отправлять заявки?

Подходит любой из двух: /api/lead или /site/apiaddlead/ на домене сети. Второй адрес и формат Lead[…] сделаны для совместимости: если трекер уже настроен под другую сеть, часто достаточно сменить домен.

Какие параметры обязательны?

wmkey, apikey, offer_id, city и phone. Если чего-то не хватает, API вернёт HTTP 400 с кодом bad_request. Остальные параметры помогают в аналитике и работе клиники: имя, метки, дополнительная информация, номер лендинга.

В каком виде передавать телефон?

В любом: с плюсом, скобками и дефисами или цифрами подряд. Принимаются записи вида +7 (927) 123-45-67, 89271234567 и 9271234567. Если номер не удаётся распознать, вернётся bad_phone с HTTP 422.

Как выглядит успешный ответ?

HTTP 200 и JSON со статусом ok и номером заявки lead_id. При повторе запроса с тем же apiid вы получите тот же lead_id и признак duplicate_of_request: true, а не новую заявку.

Какие бывают ошибки?

Основные коды: bad_request (400), bad_key (401), blocked (403), geo_closed (403), offer_not_found (404), offer_not_live (409), duplicate (409), city_not_found (422), bad_phone (422), limit_reached (429). К ним добавляется client_no_funds, когда у клиники не хватает свободных денег и приём остановлен.

Когда запрос стоит повторять?

Только при ошибке сети или ответе 5xx. На ответ 4xx повтор вернёт ту же ошибку и лишь создаст нагрузку. Если вы передаёте apiid, безопасно повторять запрос после сбоя: двойной заявки не будет.

Что такое sub1…sub5 и зачем их передавать?

Это метки утм: sub1 соответствует utm_source, sub5 — utm_term. Они возвращаются в постбэке и участвуют в статистике по меткам, так что вы можете сопоставить заявку с источником, креативом или кампанией.

Можно ли отправлять данные в формате JSON?

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

Безопасно ли вызывать API прямо с лендинга?

Нет. Код на странице доступен посетителю, и apikey окажется на виду. Используйте серверную отправку или форму лендинга сети. Если ключ всё же утёк, выпустите новый в кабинете: старый сразу перестанет работать.

Что происходит с заявкой после приёма?

Она получает статус «У клиента», клинике уходит сообщение в Telegram (если подключён бот), а в CRM клиники отправляется вебхук. Повторы доставки идут до 8 раз с растущей паузой. Вебмастеру уходит постбэк. Дальнейшие статусы — на странице про статусы лида.