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

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

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

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

URL проверки

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

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

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

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

  • {from} и {to} - дата начала и окончания периода в формате ГГГГ-ММ-ДД.
  • {ffrom} и {fto} - дата начала и окончания периода в формате ГГГГ-ДД-ММ ЧЧ:ММ:СС.
  • {ufrom} и {uto} - время начала и окончания периода в формате UNIX timestamp.

Поля данных

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

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

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

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

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

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

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

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

  • $from и $to - дата начала и окончания периода в формате ГГГГ-ММ-ДД.
  • $ffrom и $fto - дата начала и окончания периода в формате ГГГГ-ДД-ММ ЧЧ:ММ:СС.
  • $ufrom и $uto - время начала и окончания периода в формате UNIX timestamp.

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

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

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

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

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

foreach ( $data as $d ) {
  $oid = $e2i[$d['id']]; // Получаем наш ИД по их идентификатору
  switch ( $st ) {
    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 - цена за единицу товара.
  • count - количество товара в заказе.
  • 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'] ] ] );

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

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

  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. Оффер отключен