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

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

  • Отправка новых лидов в 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.
  • {customer} — значение метки customer.
  • {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 $core->lead->reason( $result );

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

Иногда новые лиды отправлять не нужно, достаточно перенести заказ в статус обработки. Такое случается при добавлении лидов по 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 и просто пометят лид статусом «В обработке».