Приём заявок по 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 раз с растущей паузой. Вебмастеру уходит постбэк. Дальнейшие статусы — на странице про статусы лида.