Проверка статусов по 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 — трек-код для отслеживания доставки по заказу.
  • custom — статус CRM рекламодателя. Не забудьте addslashes!

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

$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'] ] ] );

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

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

  1. Новый — лид ожидает обработки или отправки в CRM
  2. Обработка — лид отправлен в CRM и обрабатывается
  3. Перезвонить — лид находится в обработке у колл-центра
  4. Холд — лид ожидает автоматического подтверждения
  5. Отмена — лид отклонён, требуется причина отказа
  6. Упаковка — лид подтверждён и ожидает упаковки
  7. Отправка — заказ упакован и ожидает отправки
  8. В пути — заказ отправлен и доставляется
  9. Доставлен — заказ доставлен в пункт выдачи
  10. Оплачен — заказ выкуплен и закрыт
  11. Возврат — заказ возвращён отправителю
  12. Удалён — лид удалён и не участвует в статистике

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

  1. Некорректный номер (треш)
  2. Передумал
  3. Не заказывал (треш)
  4. Требует сертификат
  5. Неверное ГЕО (треш)
  6. Треш или тест (треш)
  7. Дублированный заказ (треш)
  8. Заказал в другом месте (треш)
  9. Дорого
  10. Не устраивает доставка (треш)
  11. Не удалось дозвониться (треш)
  12. Подозрения на фрод (треш)
  13. Не говорит на языке колл-центра
  14. Товар не подошёл (треш)
  15. Оффер отключён
  16. Консультация
  17. Отклонён по таймеру