Приём в формате LeadVertex

Приём в формате LeadVertex повторяет чужой протокол буква в букву: параметры формы, коды ответов, вид ошибок. Он существует ровно затем, чтобы переезд не превратился в переговоры с двумя десятками вебмастеров о переписывании их интеграций.

Зачем второй формат

У партнёра, который льёт трафик несколько лет, интеграция написана однажды и больше не открывалась. Просьба «поменяйте формат запроса» означает для него работу программиста, тесты и риск — то есть повод приостановить ваш оффер и заняться другим. Совместимый адрес снимает разговор целиком: партнёр меняет один домен в настройках и продолжает работать.

Формат отличается только упаковкой. За обоими адресами один конвейер: те же проверки антифрода, тот же поиск дублей, та же запись в журнал приёма, те же постбэки. Заказы, пришедшие двумя способами, в системе ничем не различаются, кроме канала в журнале — API или LV API.

Запрос

Приём только POST. GET-приёма нет — и не будет.

curl -X POST 'https://ваш-проект.xe.kg/api/webmaster/v2/addOrder.html?token=ВАШ_ТОКЕН' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'fio=Асанов Азамат' \
  --data-urlencode 'phone=0555123456' \
  --data-urlencode 'city=Бишкек' \
  --data-urlencode 'address=ул. Киевская, 95' \
  --data-urlencode 'externalID=12345' \
  --data-urlencode 'externalWebmaster=kg_fb_01' \
  --data-urlencode 'goods[0][goodID]=950' \
  --data-urlencode 'goods[0][quantity]=2'

Обязателен только phone. Дальше принимаются phone2, fio, email, country, region, city, address, house, flat, postIndex, comment, total, externalID, externalWebmaster, domain, referer, ip, timeSpent, timezone, метки utm_source, utm_medium, utm_campaign, utm_term, utm_content и поля additional1…additional25.

Товары и дополнительные поля

Позиции принимаются двумя записями, потому что в жизни встречаются обе:

• По одной — goods[0][goodID], goods[0][quantity], goods[0][price]; так шлют PHP-клиенты.
• Строкой — goods=[950|1|1500][951|3|4500]: идентификатор, количество, сумма. Так устроены ячейки в выгрузках и часть старых интеграций.

goodID — идентификатор товара в вашем каталоге. Партнёр берёт его из документации по ссылке, которая копируется из списка ключей приёма. Цену можно не передавать: посчитаем по ценовой сетке проекта, и при смене цен не придётся обходить всех вебмастеров.

Поля additional1..25 складываются в дополнительные данные заказа под своими именами. Осмысленные подписи подставляет реестр полей проекта: у каждого поля хранится, какому additional оно соответствует, поэтому переименование поля у вас не ломает интеграцию партнёра. Настраивается это в НастройкиПоля.

Ответы

Успех — 200 и объект, где ключ является номером созданного заказа. Именно это разбирают готовые скрипты, поэтому формат воспроизведён точно:

{"100000042": "OK"}

Отказ — 406 и объект «поле: сообщения». Отклонение от этого формата партнёрские скрипты трактуют как «сервер лежит», поэтому причина привязывается к тому полю, на которое партнёр может посмотреть:

{"phone": ["Не удалось разобрать телефон: 0555"]}
{"ip": ["С адреса 91.108.4.12 за сутки уже 40 заказов"]}
{"externalWebmaster": ["Поток «kg_old_07» отключён"]}
{"order": ["Проект закрыт и не принимает заказы"]}

Недействительный или отозванный ключ даёт 403 и объект с полем error.

{
  "fio": "Асанов Азамат",
  "phone": "0555123456",
  "city": "Бишкек",
  "address": "ул. Киевская, 95",
  "externalID": "12345",
  "externalWebmaster": "kg_fb_01",
  "goods[0][goodID]": "950",
  "goods[0][quantity]": "2",
  "additional7": "домофон 95"
}

Как переключить партнёра

Порядок такой, чтобы в любой момент можно было вернуться назад без потерь трафика:

• Завести вебмастера и потоки с прежними кодами, выпустить ему ключ приёма.
• Отдать партнёру новый домен и новый токен. Путь /api/webmaster/v2/addOrder.html он не меняет — он уже зашит в его коде.
• Попросить прислать один тестовый заказ и найти его в Партнёрская сетьЖурнал приёма. В развёрнутой строке видно, что именно пришло: этого достаточно, чтобы закрыть вопросы «а я отправил».
• Открыть трафик и первые часы смотреть на колонку Результат: массовые отказы обычно означают, что партнёр присылает адрес своего сервера вместо адреса клиента или не передаёт время на странице.

Новым партнёрам этот формат предлагать не стоит: в нативном приёме больше полей, внятные коды ошибок и заголовок идемпотентности. Сравнение — в статье Приём по API.