Проверка статусов по API

Выгрузка статусов может работать в трёх вариациях:

Проверка статусов лидов в обработке. Проверяются заказы в статусах "Обработка", "Перезвонить" и "Холд". Проверка выполняется раз в 10 минут. Лиды проверяются по списку идентификаторов. В результате проверки лид меняет статус обзвона, переходит в терминальные статусы "Аппрув" или "Отмена".
Проверка статусов принятых лидов. Проверяются заказы в статусах "Упаковка", "Отправка", "В пути" и "Доставлен". Проверка выполняется раз в несколько часов. Лиды проверяются по списку идентификаторов. В результате проверки лид меняет статус доставки, переходит в "Оплачен" или "Возврат".
Проверка статусов по диапазону дат. Проверяются заказы во всех не терминальных статусах. Проверка выполняется каждый час. Выгрузка осуществляется по диапазонам дат, в которых есть заказы. Лид может переводиться в любой статус.

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

URL проверки

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

Проверка лидов в обработке и принятых лидов:

{idsl} - список внутренних ID лидов через запятую.
{idel} - список внешних ID лидов через запятую.

Проверка лидов по диапазону дат:

{from} и {to} - дата начала и окончания периода в формате ГГГГ-ММ-ДД.
{ffrom} и {fto} - дата начала и окончания периода в формате ГГГГ-ДД-ММ ЧЧ:ММ:СС.
{ufrom} и {uto} - время начала и окончания периода в формате UNIX timestamp.
{tom}, {ftom}, {utom} - время окончания периода плюс один день, для CRM, которые не дружат с датами.

Поля данных

Поля данных поддерживают тот же список макросов, что и URL проверки. Для проверки лидов в обработке и принятых лидов доступны два дополнительных макроса:

{ids} - массив внутренних идентификаторов заказа
{ide} - массив внешних идентификаторов заказа

При отправке массивов рекомендуется преобразовать запрос к формату form-urlencoded или JSON с помощью кода предобработки.

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

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

Проверка лидов в обработке и принятых лидов:

$idl - массив внутренних идентификаторов заказа.
$ide - ассоциативный массив внешних идентификаторов заказа, ключом которого являются внутренние идентификаторы заказов.
$idsl - список внутренних ID лидов через запятую.
$idel - список внешних ID лидов через запятую.

Проверка лидов по диапазону дат:

$from и $to - дата начала и окончания периода в формате ГГГГ-ММ-ДД.
$ffrom и $fto - дата начала и окончания периода в формате ГГГГ-ДД-ММ ЧЧ:ММ:СС.
$ufrom и $uto - время начала и окончания периода в формате UNIX timestamp.
$tom, $ftom, $utom - время окончания периода плюс один день, для сетей, которые не дружат с датами.

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

На вход кода обработки подаётся переменная $data, содержащая в себе раскодированный ответ от сервера. Чаще всего это ассоциативный массив, полученный методом расшифровки JSON.

Дополнительные переменные, которые можно использовать в коде обработки:

$e2i - массив соответствия внешних ID внутренним ID. В целях безопасности рекомендуется использовать именно внешние ID через этот массив в виде: $e2i[$d['id']].
$ids - массив статусов заказов по внутреннему идентификатору заказа.
$i2t - массив времени создания заказов по внутреннему идентификатору.
$inid - внутренний ID заказа, если на проверке была всего одна штука. Используйте только в сочетании с указанием 1 в количестве лидов на проверке!

Задача кода обработки - пройтись по массиву ответа и раздать лидам статусы в соответствии со статусами в целевой CRM. Общий вид кода обработки можно представить так:

foreach ( $data as $d ) {
  $oid = $e2i[$d['id']]; // Получаем наш ИД по их идентификатору
  switch ( $d['status'] ) {
    case 'accept': $core->lead->edit( $oid, [ 'accept' => 1 ] ); break;
    case 'cancel': $core->lead->edit( $oid, [ 'status' => 5 ] ); break;
    case 'trash':  $core->lead->edit( $oid, [ 'status' => 5, 'reason' => 6 ] ); break;
  }
}

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

foreach ( $data as $d ) $core->lead->setstc( $e2i[$d['id']], $d['status'] );

Финансовые интеграции могут использовать вариант кода обработки, учитывающий наличие первого депозита у клиента:

foreach ( $data as $d ) {
  $oid = $e2i[$d['id']];
  if ( ! $oid ) continue;
  if ( $d['ftd'] ) {
    $core->lead->approve( $oid, $d['status'] );
  } else $core->lead->setstc( $oid, $d['status'] );
}

Функции редактирования заказа

Редактирование заказа осуществляется с помощью функции $core->lead->edit. Она имеет несколько надстроек для сокращения и упрощения кода.

$core->lead->approve( $id, $comment )

Функция подтверждает лид с номером $id. Если задан необязательный параметр $comment, лиду устанавливается соответствующий комментарий.

$core->lead->setstatus( $id, $status )

Функция пытается автоматически распознать статус в параметре $status и установить его для лида с номером $id.

$core->lead->setstc( $id, $status )

Функция пытается автоматически распознать статус в параметре $status и установить его для лида с номером $id. Также она записывает исходное значение $status в комментарий лида для удобства анализа.

$core->lead->edit( $id, $data )

Функция изменяет лид с номером $id по указанным данным в массиве $data. Массив $data может содержать следующие поля:

accept = 1 - подтвердить лид. Используйте именно этот вариант подтверждения, а не установку лиду статуса "Упаковка" или "Оплачен" для корректного срабатывания всех механизмов.
status - числовой идентификатор статуса от 1 до 12, список указан ниже.
reason - числовой идентификатор причины отказа, может меняться в зависимости от настроек вашей сети.
hold - если передано true, лид отправляется в холд на количество дней, указанных в настройке оффера. Если передано целое число, лид отправляется в холд на это количество дней.
comment - текстовый комментарий к заказу. Не забудьте addslashes!
base - цена за единицу товара.
counts - количество товара в заказе.
curr - внутренний идентификатор валюты заказа, определяется функцией $core->currency->id( $iso ) по ISO-коду валюты.
goal - внутренний идентификатор цели оффера, определяется функцией $core->goal->bycode( $off, $code ) по символьному коду цели в $code.
track - трек-код для отслеживания доставки по заказу

Пример подтверждения заказа:

$core->lead->edit( $oid, [ 'accept' => 1 ] );

Пример смены статуса заказа и комментария:

$core->lead->edit( $oid, [ 'status' => 3, 'comment' => addslashes(stripslashes( $d['comment'] )) ] );

Пример отклонения заказа с указанием причины:

$core->lead->edit( $oid, [ 'status' => 5, 'reason' => 6 ] );

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

wm - отчисление для вебмастера.
pay - отчисление для рекламодателя.
ref - реферальное отчисление.
cc - валюта отчисления.

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

'cash' => [ 'pay' => $d['payout'], 'cc' => $d['currency'] ]

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

$core->lead->edit( $oid, [ 'accept' => 1, 'cash' => [ 'pay' => $d['payout'], 'cc' => $d['currency'] ] ] );

Статусы лидов и причины отказа

Лид может находиться в одном из этих статусов:

Новый - лид ожидает обработки или отправки в CRM
Обработка - лид отправлен в CRM и обрабатывается
Перезвонить - лид находится в обработке у колл-центра
Холд - лид ожидает автоматического подтверждения
Отмена - лид отклонён, требуется причина отказа
Упаковка - лид подтверждён и ожидает упаковки
Отправка - заказ упакован и ожидает отправки
В пути - заказ отправлен и доставляется
Доставлен - заказ доставлен в пункт выдачи
Оплачен - заказ выкуплен и закрыт
Возврат - заказ возвращён отправителю
Удалён - лид удалён и не участвует в статистике

Стандартные причины отказа:

Некорректный номер (треш)
Передумал
Не заказывал (треш)
Требует сертификат
Неверное ГЕО (треш)
Треш или тест (треш)
Дублированный заказ (треш)
Заказал в другом месте (треш)
Дорого
Не устраивает доставка (треш)
Не удалось дозвониться (треш)
Подозрения на фрод (треш)
Не говорит на языке колл-центра
Товар не подошел (треш)
Оффер отключен
Консультация
Отклонён по таймеру