Отправка лидов

Отправка лидов может использоваться в четырёх ситуациях:

  • Отправка новых лидов в CRM. Классическая передача лидов в стороннюю сеть. Каждую минуту все лиды в статусе "Новый" отправляются в целевую CRM. При удачной отправке, лид переводится в статус "Обработка". При проблемах - в статус "Отмена" с соответствующей причиной. При ошибках отправки остаётся в статусе "Новый" для отправки через минуту.
  • Отправка апсейлов и изменений. Иногда лид может быть изменён запросом с сайта, который отправлен со страницы "Спасибо". Изменения отправляются в целевую CRM каждую минуту.
  • Отправка принятых лидов в CRM. Отправляет в целевую сеть лиды после обработки колл-центром. Вы можете выбрать статус, из которого происходит отправка. Из "Упаковки" удобно отдавать лиды в службу фулфилмента, из "Отправки" - в службу доставки, из "Доставки" - в колл-центр мониторинга доставки.
  • Синхронная отправка лидов на регистрацию. Отправляет данные в целевую CRM в момент поступления лида. Требуется для реализации механизма автоматического входа (автологин).

Все интеграции имеют аналогичный подход к ссылкам, полям и коду обработки. Запрос выполняется отдельно для каждого лида. Ссылки и поля работают с одинаковыми набором макросов. Код обработки всегда должен заканчиваться возвратом результата.

URL добавления

Это адрес, на который будет выполняться запрос. Вы можете использовать эти макросы в адресе:

  • {id} - идентификатор заказа.
  • {ip} - IP-адрес покупателя.
  • {wm} - идентификатор вебмастера.
  • {wmi} - умный идентификатор вебмастера, который отправляет данные в виде агент-веб для агентского трафика.
  • {name} - имя покупателя.
  • {phone} - телефон покупателя.
  • {ofp:xxx} - значение параметра оффера с названием xxx.
  • {ofpg:xxx} - значение гео-зависимого параметра оффера с названием xxx.
  • {meta:xxx} - значение дополнительного поля заказа с названием xxx.
  • {goal:xxx} - значение параметра цели с названием xxx.
  • {site:xxx} - значение параметра сайта с названием xxx.

Вы также можете манипулировать адресом через переменную $url в коде предобработки.

Код предобработки

Основные методы использования кода предобработки описаны в соответствующем разделе документации. При отправке лидов вам доступны следующие переменные с данными:

  • $o - необработанные данные заказа, полученные напрямую из базы.
  • $o['order_country'] - ISO-код страны заказа.
  • $o['offer_id'] - идентификатор оффера.
  • $ofps - параметры оффера.
  • $ofpg - гео-зависимые параметры оффера.
  • $gpar - параметры цели.
  • $spar - параметры сайта.
  • $vars - вложенные товары.
  • $meta - дополнительные поля заказа.

При работе с товарными интеграциями, может потребоваться получение состава заказа. Он хранится в поле $o['order_items'], которое можно получить так:

$its = xxdec( $o['order_items'] );

Внутри $its хранится массив товаров в заказе. Ключ массива - идентификатор товара. Поля массива:

  • 0: количество товара в заказе.
  • 1: цена единицы товара в валюте заказа.
  • 2: себестоимость единицы товара в валюте заказа.

Пример подготовки массива товаров для отправки:

$post['items'] = [];
$its = xxdec( $o['order_items'] );
$itp = $core->cpa->get( 'vpar', $o['offer_id'], 'sku' );
foreach ( $its as $it => $iv ) {
  $post['items'][] = [
    'id' => $itp[$it],
    'price' => $iv[1],
    'amount' => $iv[0],
  ];
}

Поля данных

Состав заказа лучше всего формировать через поля. Список полей задаётся в формате "название значение" через пробел, каждое поле - в своей строке. В качестве значения может выступать либо какая-то строка, либо какой-то макрос. Можно также указать макросы внутри строки.

Основные поля данных:

  • {id} - идентификатор заказа.
  • {eid} - зашифрованный идентификатор заказа.
  • {ext} - идентификатор заказа на стороне целевой CRM (для отправки изменений).
  • {name} - имя покупателя.
  • {last} - фамилия покупателя из произвольного поля last.
  • {fname} - полное имя покупателя.
  • {email} - адрес почты покупателя.
  • {pass} - пароль покупателя из произвольного поля pass.
  • {lang} - язык покупателя из поля lang или данных страны.
  • {langup} - язык покупателя заглавными буквами.
  • {iname} и {ilast} - умные имя и фамилия, полученные из дополнительных полей или методом разделения имени пополам (использовать только парой).
  • {ipass} - умный пароль, полученный из поля pass или сгенерированный на лету.
  • {imail} - умная почта, генерируется при пустом поле в виде hash@gmail.com.
  • {phone} - телефон покупателя.
  • {iphone} - телефон покупателя с символом + впереди.
  • {cphone} - телефон покупателя без кода страны.
  • {phonecc} - телефонный код страны из полей phonecc и phc.
  • {iphonecc} - телефонный код страны с символом + впереди.
  • {geo} и {country} - ISO-код страны маленькими буквами.
  • {geoup} - ISO-код страны заглавными буквами.
  • {geoname} - полное название страны на английском языке.
  • {comment} - комментарий к заказу.
  • {index} - почтовый индекс доставки.
  • {area} - регион страны доставки.
  • {city} - город доставки.
  • {street} - улица.
  • {house} - дом, корпус и квартира.
  • {addr} - адрес доставки без индекса.
  • {fulladdr} - адрес доставки с индеком.
  • {straddr} - адрес доставки из улицы и дома.
  • {delivery} - внутренний идентификатор типа доставки.
  • {discount} - процент скидки на товар.
  • {count} - количество товара.
  • {currency} - внутренний идентификатор валюты в системе.
  • {curr} - трёхбуквенный ISO-код валюты.
  • {price} - общая цена заказа.
  • {base} - цена единицы товара.
  • {delpr} - цена доставки.
  • {more} - дополнительная наценка или скидка на доставку в валюте заказа.
  • {offer} - идентификатор оффера в системе.
  • {siteurl} - умный адрес лендинга, который использует параметр url, реальный адрес сайта заказа или адрес сайта по умолчанию.
  • {sitename} - название лендинга.
  • {spaceurl} - адрес прелендинга.
  • {spacename} - название прелендинга.
  • {land} - адрес лендинга при наличии.
  • {preland} - адрес прелендинга при наличии.
  • {domain} - домен сайта при наличии.
  • {click} - внутренний идентификатор клика.
  • {wm} - идентификатор вебмастера.
  • {wmi} - умный идентификатор вебмастера, который отправляет данные в виде агент-веб для агентского трафика.
  • {wmname} - имя вебмастера.
  • {wmmail} - email вебмастера.
  • {exti} - идентификатор агентства.
  • {extu} - идентификатор заказа на стороне агентства.
  • {exts} - идентификатор источника на стороне агентства.
  • {subid} - значение метки subid или x32.
  • {uuid} - значение метки uuid или x64.
  • {sub1} - значение метки sub1.
  • {sub2} - значение метки sub2.
  • {sub3} - значение метки sub3.
  • {sub4} - значение метки sub4.
  • {sub5} - значение метки sub5.
  • {utms} - значение метки utm_source.
  • {utmc} - значение метки utm_campaign.
  • {utmn} - значение метки utm_content.
  • {utmt} - значение метки utm_term.
  • {utmm} - значение метки utm_medium.
  • {ip} - IP-адрес покупателя.
  • {ip4} - IPv4-адрес покупателя или пустота для IPv6.
  • {ip6} - IPv6-адрес покупателя или пустота для IPv4.
  • {ua} - User-Agent покупателя.
  • {mobile} - тип трафика: 0 - десктоп, 1 - мобильный.
  • {bad} - качество трафика: 0 - обычный, 1 - подозрительный.
  • {cwm} - сумма отчисления вебмастеру в системной валюте.
  • {cwmr} - сумма отчисления вебмастеру в реальной валюте.
  • {cwmc} - ISO-код реальной валюты отчисления вебмастеру.
  • {cpay} - сумма отчисления рекламодателю в системной валюте.
  • {cpayr} - сумма отчисления рекламодателю в реальной валюте.
  • {cpayc} - ISO-код реальной валюты отчисления рекламодателю.

Параметрические поля подставят значение соответствующего параметра с названием xxx:

  • {ofp:xxx} - параметр оффер.
  • {ofpg:xxx} - гео-зависимый параметр оффера.
  • {goal:xxx} - параметр цели.
  • {site:xxx} - параметр лендинга.
  • {space:xxx} - параметр прелендинга.
  • {offer:xxx} - основное поле оффера.
  • {meta:xxx} - произвольное поле заказа.
  • {file:xxx} - прикреплённый файл из произвольного поля.

В произвольных полях заказа могут использоваться файлы. Отправка файлов поддерживается только при использовании стандартного формата multipart/form-data, передача файлов в JSON-запросах не поддерживается.

Общие сведения о коде обработки

Код обработки получает на вход переменную $result. Она содержит сырые данные ответа сервера. Чаще всего ответ сервера приходит в формате JSON, поэтому результат лучше преобразовать к массиву вот так:

$r = xxdec( $result );

Код обработки должен возвращать результат в случае успеха. Если обработка вернёт false или не вернёт результата, считается, что запрос не удался. Такой запрос будет поставлен в очередь для повторной отправки.

Код обработки для новых лидов

При отправке новых лидов, система ожидает увидеть ID нового лида или код ошибки добавления. Если код обработки вернул отрицательное целое число - оно расценивается как ID причины отказа и лид отменяется. Любое другое значение считается идентификатором лида.

Например, API-функция добавления заказов у поставщика выдаёт нам { status: "ok", id: 123 } в случае успеха, и { status: "error", error: "double" } в случае ошибки добавления заказа с указанием кода ошибки. Код, который реализует это, будет выглядеть вот так:

$r = xxdec( $result );
if ( $r['status'] == 'ok' ) return $r['id'];
if ( $r['error'] == 'double' ) return -7;
if ( $r['error'] == 'geo' ) return -5;
if ( $r['error'] == 'phone' ) return -1;
return false;

Заглушка для отправки новых лидов

Иногда новые лиды отправлять не нужно, достаточно перенести заказ в статус обработки. Такое случается при добавлении лидов по API с указанием внешнего ID заказа или при синхронной отправке лида на регистрацию.

Для включения заглушки, оставьте все поля блока "Отправка новых лидов" пустыми и поставьте галочку "Включить интеграцию передачи заказов". Заказы будут переводиться в статус "Обработка" раз в минуту. Если у заказов нет внешнего ID, вместо него будет вписан внутренний ID заказа.

Код обработки для изменений лида

Обработка изменений ожидает от кода только два значения - успех или неудачу. Любое не пустое значение будет расцениваться как успех. Пример реализации:

$r = xxdec( $result );
return ( $r['status'] == 'ok' ) ? true : false;

Код обработки для принятых заказов

При обработке принятых заказов, система ожидает от кода идентификатор заказа на стороне CRM. Любое не пустое значение расценивается как идентификатор. Пример реализации:

$r = xxdec( $result );
if ( $r['status'] == 'ok' ) {
  return $r['id'];
} else return false;

Код обработки для синхронной отправки

При синхронной отправке, система ожидает от кода ссылку входа в личный кабинет для заказчика. Но получает её крайне редко, поэтому готова смириться с некоторыми вариантами.

  • Полноценный URL будет расцениваться как удачная отправка лида. Пользователь будет перенаправлен по указанному адресу в личный кабинет. Заказ остаётся в статусе "Новый" и ожидает последующей классической отправки.
  • Строка текста будет расценена как сообщение об ошибке, оно будет показано пользователю на сайте. Сама отправка будет считаться неудачной - такой лид автоматически переводится в статус "Удалён".
  • Отрицательное число будет считаться кодом причины отказа, как при отправке новых лидов. Лид будет отменён с указанной причиной. Пользователь при этом увидит страницу "Спасибо".
  • Положительное целое число будет расцениваться как идентификатор лида. Отправка считается успешной, лид переводится в статус "Обработка" с указанным ID. Пользователь видит страницу "Спасибо".
  • Строка вида id:xxx (символы id, двоеточие и произвольное значение) также будет расцениваться как идентификатор лида, аналогично предыдущему пункту.
  • Пустой ответ расценивается как ошибка отправки. Лид остаётся в статусе "Новый" и отправляется на классическую отправку.

Классическая обработка синхронной отправки выглядит вот так:

$r = xxdec( $result );
if ( $r['autologin_url'] ) return $r['autologin_url'];
if ( $r['error_message'] ) return $r['error_message'];
return 'Registration failed, try again later';

Классическая обработка никогда не применяется. Реальный код обработки гораздо сложнее и учитывает множество вариаций. В обработчике рекомендуется сразу же устанавливать внешний ID лида, если он был получен.

$core->lead->edit( $o['order_id'], [ 'exto' => $result['id'] ] );

Пример полного кода обработки:

$result = json_decode( $result, true );
if ( $result['status'] == 'ok' ) {
  $core->lead->edit( $o['order_id'], [ 'exto' => $result['id'] ] );
  return $result['url'] ? $result['url'] : false;
}
if ( $result['message'] ) return $result['message'];
if ( $result['error'] == 'duplicate' ) return -7;
if ( $result['error'] == 'ban' ) return -12;
if ( $result['error'] == 'traffic' ) return -15;
return 'Registration failed, try again later';

Использование только синхронной отправки является небезопасным с точки зрения потери трафика. Если целевая CRM не смогла ответить, лид так и не будет в неё передан. Поэтому рекомендуется совмещать синхронную и классическую отправки. При этом, чтобы лид не был отправлен дважды, необходимо выполнить ряд действий.

При успешном выполнении синхронной отправки в обязательном порядке укажите внешний идентификатор лида, как описано выше. Если целевая CRM не использует свои индентификаторы, воспользуйтесь внутренним:

$core->lead->edit( $o['order_id'], [ 'exto' => $o['order_id'] ] );

В конец кода предобработки для отправки новых лидов добавьте следующие строчки:

if ( $o['ext_oid'] ) {
  $url = $post = false;
  $result = true;
}

В начало кода обработки добавьте строчку:

if ( $o['ext_oid'] ) return $o['ext_oid'];

Эти манипуляции отключат реальный повторный запрос к целевой CRM и просто пометят лид статусом "В обработке".