Перейти к содержанию

Интеграция Roistat со своей CRM

Обратите внимание:

Перед интеграцией необходимо установить счетчик Roistat.

Шаг 1. Создание дополнительного поля roistat

После установки счетчика необходимо создать дополнительное поле roistat.

Обратите внимание:

Дополнительное поле обязательно должно иметь название roistat, иначе интеграция работать не будет.

Через поле roistat промокод передается в CRM-систему из источника заявки, а затем выгружается вместе со сделкой в аналитику. Без корректного значения в поле roistat пользователи CRM не смогут отслеживать источники загруженных заявок и анализировать эффективность маркетинга. Поле roistat может быть создано в процессе настройки интеграции пользователем (вручную) или CRM-системой (автоматически). Основные требования к полю: 

  • Поле должно быть видимым для пользователя и редактируемым;  
  • Типом поля должна быть строка, а значения поля могут быть как буквенными, так и числовыми.

Если по каким-либо причинам вы создаете сделку вручную (например, для оффлайн-источников), вы можете заполнить поле roistat данными об источнике сделки. Тогда информация об источнике сделки будет отображена в Аналитике.

Чтобы отнести сделку к определенному рекламному каналу, вводите в поле roistat следующие маркеры:

  • yamarket{ID}, если хотите отнести сделку к каналу Яндекс.Маркет. Здесь и далее ID - идентификатор рекламного канала. Например, yamarket1.
  • direct{ID}, если хотите отнести сделку к каналу Яндекс.Директ. Например, direct2.
  • google{ID}, если хотите отнести сделку к каналу Google Adwords. Например, google3.
  • merchant{ID}, если хотите отнести сделку к каналу Google Merchant Center. Например, merchant4.
  • vk{ID}, если хотите отнести сделку к каналу ВКонтакте. Например, vk5.
  • facebook{ID}, если хотите отнести сделку к каналу Facebook*. Например, facebook6.
  • mytarget{ID}, если хотите отнести сделку к каналу myTarget.
  • seo_yandex, если хотите отнести сделку к каналу SEO - Яндекс.
  • seo_google, если хотите отнести сделку к каналу SEO - Google.

После установки счетчика на сайт и создания дополнительного поля roistat можно приступать к настройке интеграции.

Шаг 2. Настройка выгрузки данных из CRM-системы

Чтобы Roistat получал информацию по сделкам, необходимо настроить выгрузку информации о статусах, дополнительных полях, менеджерах и клиентах из CRM-системы.

Выгрузка информации о статусах, дополнительных полях и менеджерах CRM-системы

Этот запрос нужно настроить до этапа «Отправка данных в CRM-систему», так как он необходим для корректной работы всей интеграции. 

Пример GET-запроса: 

 http://mycrm.com/new/php?user=test_user&token=1234567890&action=import_scheme

где: 

  • action=import_scheme – выгрузка основных справочников из CRM;

  • user – имя пользователя в CRM;

  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password. 

В ответ на запрос Roistat должен получить следующий формат данных:

{
 "statuses": [
        {"id": "1", "name": "Новый"},
        {"id": "2", "name": "В работе"}
    ],
"fields": [
        {"id": "1", "name": "Способ доставки"},
        {"id": "2", "name": "Менеджер"}
    ],
 "managers": [
        {
            "id": "1",
            "name": "Менеджер 1",
            "phone":"79012223355",
            "email": "test1@mail.com"
            },
        {
            "id": "2",
            "name": "Менеджер 2",
            "phone":"79022223355",
            "email": "test2@mail.com"
            }
    ]
}

Описание массивов:

В массиве statuses отображаются статусы сделок. Массив состоит из следующих элементов:

Элемент Описание Обязательный
id Уникальный идентификатор статуса. Используется в массиве orders Да
name Название статуса. Используется в интерфейсе Roistat Да

В массиве fields отображаются дополнительные поля сделок.  Массив состоит из следующих элементов:

Элемент Описание  Обязательный 
id Уникальный идентификатор дополнительного поля. Используется в массиве orders  Да 
name  Название дополнительного поля. Используется в интерфейсе Roistat  Да 

В массиве managers отображаются ответственные за сделки менеджеры компании. Массив состоит из следующих элементов:

Элемент Описание  Обязательный 
id Уникальный идентификатор менеджера. Используется в массиве orders  Да 
name  Имя менеджера. Используется в интерфейсе Roistat  Да 
phone  Телефон менеджера  Да 
email  Электронная почта менеджера  Да 

Выгрузка информации о сделках из CRM-системы

Информация о сделках загружается в систему аналитики и отображается в пользовательских отчетах. 

Пример GET-запроса: 

http://mycrm.com/new/php?date=1546300800&user=test_user&token=abc1234567890&action=export&offset=0&limit=1000

где:

  • action=export – выгрузка данных по сделкам;

  • date – дата в формате UNIX-time, после которой были изменения в сделках;

  • user – имя пользователя в CRM; 

  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password; 

  • limit – количество выгружаемых сделок, которое Roistat ожидает получить от CRM-системы; 

  • offset – количество заявок от начала выборки, которые нужно пропустить.

В ответ на запрос Roistat должен получить следующий формат данных:

{
    "fields": [
        {
            "id": "1",
            "name": "Способ доставки"
            },
        {
            "id": "2",
            "name": "Филиал"}
    ],
    "pagination": {
        "total_count": 1344,
        "limit": 200
    },
    "statuses": [
        {
            "id": "1",
            "name": "Новый"
            },
        {
            "id": "2",
            "name": "В работе"
            }
    ],
    "managers": [
        {
            "id": "1",
            "name": "Менеджер 1",
            "phone":"79012223355",
            "email": "test1@mail.com"
            },
        {
            "id": "2",
            "name": "Менеджер 2",
            "phone":"79022223355",
            "email": "test2@mail.com"
            }
    ],
    "orders": [
        {
            "id": "123",
            "name": "Новая сделка",
            "date_create": "1393673200",
            "status": "0",
            "price": "2331",
            "cost": {
                "value": 1220,
                "currency": "RUB"
            },
            "roistat": "3121512",
            "client_id": "1",
            "manager_id": "1",
            "fields": {
                "1": "Курьер",
                "2": "Филиал 1"
            },
            "products":[
            {
               "id":"1",
               "count":5,
            }
            ]
        },
        {
            "id": "124",
            "date_create": "1393673220",
            "status": "1",
            "price": "4123",
            "cost"": {
                "value": 2200,
                "currency": "RUB"
            },
            "roistat": "3121514",
            "client_id": "2",
            "manager_id": "2",
            "fields": {
                "1": "Самовывоз",
                "2": "Филиал 2"
            },
            "products":[
              {
               "id":"1",
               "count":3,
              },
              {
               "id":"2",
               "count":1,
              }
            ]
        }
    ]
}

Тип полей в массивах statuses и orders принципиально не важен, как правило, это string или int. Типом поля для суммы сделки или себестоимости может быть float.  

ID в массиве fields должны быть типом string. 

Подробное описание массивов страницы выгрузки:

В массиве fields отображаются дополнительные поля сделок. Элементы массива fields:

Элемент  Описание  Обязательный 
id  Уникальный идентификатор дополнительного поля. Используется в массиве orders Да 
name  Название дополнительного поля. Используется в интерфейсе Roistat  Да 

Массив fields является необязательным, если уже используется обработка запроса action=import_scheme.   Для корректной работы интеграции лучше вынести обработку массива fields в action=import_scheme

В массиве statuses отображаются статусы сделок. Массив состоит из следующих элементов:

Элемент  Описание  Обязательный 
id  Уникальный идентификатор статуса. Используется в массиве orders  Да 
name  Название статуса. Используется в интерфейсе Roistat Да 

Массив statuses является необязательным, если используется обработка запроса action=import_scheme.  Для корректной работы интеграции лучше вынести обработку массива statuses в action=import_scheme

Массив managers состоит из следующих элементов:

Элемент  Описание  Обязательный 
id  Уникальный идентификатор менеджера. Используется в массиве orders  Да 
name  Имя менеджера. Используется в интерфейсе Roistat  Да 
phone  Телефон менеджера Да
email  Электронная почта менеджера  Да

Массив managers является необязательным, если используется обработка запроса action=import_scheme.   Для корректной работы интеграции лучше вынести обработку массива managers в action=import_scheme

Массив pagination устанавливает лимит выгрузки заявок за один запрос.

Элемент  Описание  Обязательный 
total_count  Количество заявок, которые были изменены после заданной даты   Да 
limit  Количество заявок, которое будет выгружаться за один запрос Да 

В зависимости от параметров total_count и limit, Roistat будет совершать дополнительные запросы к странице выгрузки. Затем, при обновлении запросов limit и offset, Roistat выгрузит все измененные сделки за выбранный запросом offset период. Параметр total_count должен быть неизменным для всех страниц.

Пример:

Страница выгрузки отдает следующий ответ: 

 "pagination": {
     "total_count": 2590,
     "limit": 1000
 }

Передаваемый тип данных в массивах pagination, total_count и limit - цело число (int). 

Roistat отправит 3 последовательных запроса на выгрузку данных с  

  • limit=1000&offset=0 

  • limit=1000&offset=1000 

  • limit=1000&offset=2000 

По данному запросу выгружается 2590 сделок, измененных с момента указанной в ссылке даты. Лимит выгрузки – 1000 сделок, соответственно, после первого дополнительного запроса выгружаются сделки с 1 по 1000, после второго запроса – сделки с 1000 по 2000, а после третьего – сделки с 2000 по 2590. 

Описание элементов массива orders

Элемент Описание Обязательный
id Уникальный идентификатор сделки Да
name Название сделки. Используется в интерфейсе Roistat Нет
date_create Дата создания сделки в формате UNIX-time или YYYY-MM-DD HH:MM. Данные необходимо передавать в часовом поясе UTC+0 Да
status Уникальный идентификатор статуса из массива statuses Да
price Сумма сделки. Можно передавать в формате "price": "123". Также можно передать валюту – в этом случае нужно использовать "price" как объект с параметрами:
  • value – сумма сделки; дробное значение нужно передавать как float (123.123). Значение value используется в показателе «Выручка» в Roistat.
  • currency – валюта сделки или конкретного поля в формате RUB.
Нет
cost Себестоимость сделки. Можно передавать в формате "cost": "123". Также можно передать валюту – в этом случае нужно использовать "cost" как объект с параметрами:
  • value – значение себестоимости; дробное значение нужно передавать как float (123.123). Значение value используется в показателе «Себестоимость» в Roistat.
  • currency – валюта сделки или конкретного поля в формате RUB.
Нет
roistat Номер визита, сохраненный у сделки. Значение cookie roistat_visit. Используется для определения источника сделки Нет
client_id Идентификатор клиента Нет
manager_id Идентификатор менеджера массива managers Нет
fields Массив дополнительных полей сделки. Элементы массива имеют следующую структуру: "field_id": "field_value". Уникальный идентификатор должен совпадать со значением массива fields. Также для каждого поля можно передавать валюту – в этом случае нужно использовать "field_id" как объект с параметрами:
  • value – значение поля
  • currency – валюта сделки или конкретного поля в формате RUB
Нет
products Массив с данными о товаре, где id – id товара, count – его количество. Нет

Если значение элемента client_id отсутствует, для корректной работы интеграции вместо него можно указать значения client_phone и/или client_email внутри массива fields. Например:

"orders": [
    {
        "id": "123",
        "name": "Новая сделка",
        "date_create": "1393673200",
        "status": "0",
        "price": {
           "value": "2331",
           "currency": "RUB"
        },
        "cost": {
           "value": "1220",
           "currency": "RUB"
        },
        "roistat": "3121512",
        "client_id": null,
        "manager_id": "1",
        "fields": {
            "client_phone": "74959999999",
            "client_email": "client@email.com",
            "special_price": {
               "value": "123",
               "currency": "RUB"
            },
        },
        "products":[
        {
           "id":"1",
           "count":5,
        }
        ]
    },

Если CRM-система поддерживает несколько конвертирующихся друг в друга сущностей в рамках одной заявки, например, Лиды+Сделки, необходимо одновременно выгружать либо Лид, либо сконвертированную из него Сделку. Причем дата создания такой Сделки должна соответствовать дате создания Лида, из которого она была сконвертирована.  Это вызвано тем, что с точки зрения Roistat нет деления на Лиды и Сделки, и всё объединяется в единую Заявку клиента, которая может быть представлена в СRM-системе в различных сущностях. 

Пример PHP-кода для страницы выгрузки:

<?php

// Если вы хотите закрыть доступ к этой странице по прямой ссылке, то можно указать логин и пароль
$user     = 'login';
$password = 'password';
$token = isset($_GET['token']) ? $_GET['token'] : null;
if ($token !== md5($user.$password)) {
    exit('Invalid token');
}

//Параметр date передает сервер Roistat, чтобы отфильтровать заказы по дате обновления
$editDate = isset($_GET['date']) ? (int)$_GET['date'] : time() - 31*24*60*60;

// Параметр offset указывает, сколько заказов от начала выборки нужно пропустить
$offset = isset($_GET['offset']) ? (int)$_GET['offset'] : 0;

// Количество записей, выгружаемых за один запрос
$limit = 1000;

$query = "SELECT COUNT(`id`) FROM `orders` WHERE `edit_date` > {$editDate};";
$dbResult = $db->query($query);
$totalCount = $dbResult['0'];

$response = array(
    'orders' => array(),
    'statuses' => array(),
    'fields' => array(),
    'managers' => array(),
    'pagination' => array(
        'limit' => $limit,
        'total_count' => $totalCount,
    ),
);

$query = "SELECT * FROM `orders` WHERE `edit_date` > {$editDate} LIMIT {$offset}, {$limit};";
$dbResult = $db->query($query);
foreach ($dbResult as $row) {
    $response['orders'][] = array(
        'id'            => $row['id'],      //уникальный идентификатор сделки
        'name'          => $row['order_name'], // Человекочитаемое название сделки. Используется в интерфейсе Roistat
        'date_create'   => $row['date_create'], //дата создания сделки
        'status'        => $row['status'],  //ID статуса заказа
        'price'         => $row['price'],   //стоимость заказа
        'cost'          => $row['cost'],    //необязательное поле, себестоимость заказа, для точного расчета ROI
        'roistat'       => $row['roistat'], //ID пользователя на сервере roistat, этот параметр дописывается к сделке при создании, из cookie roistat_visit
        'client_id'     => $row['client_id'], // идентификатор пользователя, сделавшего заказ (Контакта)
        'manager_id'    => $row['manager_id'], // идентификатор менеджера, ответственного за заказ
    );
}

//добавляем описание статусов для выгрузки заказов
$query = "SELECT * FROM `statuses`";
$dbResult = $db->query($query);
foreach ($dbResult as $row) {
    $response['statuses'][] = array(
        'id'    => $row['id'],
        'name'  => $row['name'],
    );
}

echo json_encode($response);

Выгрузка информации о клиентах из CRM-системы

Чтобы пользователи могли отслеживать аналитические данные по клиентам (контактные данные, LTV, касания клиента и т.д.), необходимо обеспечить выгрузку информации по клиентам из СRM-системы. 

Для выгрузки клиентов Roistat отправляет следующий запрос: 

 http://mycrm.com/new/php?date=1546300800&user=test_user&token=abc1234567890&action=export_clients&offset=0&limit=1000

где:  

  • action=export_clients – выгрузка клиентов;

  • date – дата в формате UNIX-time, после которой были изменения в клиентах;

  • user – пользователь CRM;

  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password;

  • limit – количество выгружаемых клиентов, которое Roistat ожидает получить от CRM-системы; 

  • offset – количество клиентов от начала выборки, которые нужно пропустить.

В ответ Roistat ожидает следующий JSON-формат данных:

{
    "clients": [
        {
            "id": "1",
            "name": "Иван Иванович",
            "phone": "71111111111",
            "email": "ivan@client.com",
            "company": "ООО Компания",
            "birth_date": "1990-04-15",
        },
        {
            "id": "2",
            "name": "Жюль Верн",
            "phone": "3311111111, 3311111222",
            "email": "jv@books.com, inbox@books.com",
            "company": "",
            "birth_date": "1828-02-08",
        }
    ],
    "pagination": {
        "total_count": 2590,
        "limit": 1000
    }
}

Подробное описание элементов страницы выгрузки:

Описание элементов массива clients:

Элемент Описание Обязательный
id Уникальный идентификатор клиента. Используется в массиве orders Да
name Название клиента. Используется в интерфейсе Roistat Да
phone Телефон клиента Да
email Электронный адрес клиента Да
company Название компании Нет
birth_date День рождения (В формате Y-m-d) Нет

Описание элементов массива pagination:

Элемент Описание Обязательный
total_count Количество заявок, которые были изменены после заданной даты Да
limit Количество заявок, которое будет выгружаться за один запрос Да

В зависимости от параметров total_count и limit, Roistat будет совершать дополнительные запросы к странице выгрузки. Затем, при обновлении запросов limit и offset, Roistat выгрузит все измененные сделки за выбранный запросом offset период. Параметр total_count должен быть неизменным для всех страниц.

Страница выгрузки отдает следующий ответ: 

    "pagination": {
        "total_count": 2590,
        "limit": 1000
    }

Roistat отправит 3 последовательных запроса на выгрузку данных с 

  • limit=1000&offset=0
  • limit=1000&offset=1000
  • limit=1000&offset=2000

По данному запросу выгружается 2590 сделок, измененных с момента указанной в ссылке даты. Лимит выгрузки – 1000 сделок, соответственно, после первого дополнительного запроса выгружаются сделки с 1 по 1000, после второго запроса – сделки с 1000 по 2000, а после третьего – сделки с 2000 по 2590. 

Выгрузка информации о товарах из CRM-системы

Выгрузка информации о товарах из CRM позволяет анализировать эффективность продаж отдельных товаров и групп товаров (брендов, категорий).

Пример GET-запроса:

http://mycrm.com/new/php?date=1546300800&user=test_user&token=abc1234567890&action=export_products&offset=0&limit=1000
  • date – дата в формате UNIX-time, после которой были изменения в клиентах;
  • user – пользователь CRM;
  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password;
  • action=export_products – выгрузка данных по товарам;
  • offset – количество заявок от начала выборки, которые нужно пропустить;
  • limit – количество выгружаемых сделок, которое Roistat ожидает получить от CRM-системы.

В ответ на запрос Roistat должен получить следующий формат данных:

{
    "products": [
        {
            "id": "1",
            "name": "Велосипед",
            "brand": "Ford",
            "categories": "Велосипеды",
            "variant": "Горный велосипед",
            "price": "30000",
            "cost": "20000",
            "creation_date": "2018-02-08",
            "update_date": "2019-01-24",
            "currency": "RUB"
        },
        {
            "id": "2",
            "name": "Самокат",
            "brand": "Xiaomi",
            "categories": {
               "category1": "Электросамокаты",
               "category2": "Городские самокаты",
               "category3": "Самокаты Xiaomi"
            },
            "variant": "Городской самокат",
            "price": "24000",
            "cost": "16000",
            "creation_date": "2019-09-12",
            "update_date": "2020-03-09",
            "currency": "RUB"
        }
    ],
    "pagination": {
        "total_count": 2,
        "limit": 1000
    }
}

Описание элементов массива products:

Элемент Описание Обязательный
id Уникальный идентификатор товара. Используется в массиве orders Да
name Наименование товара Да
brand Бренд товара Нет
categories Категории товара (может быть несколько). Указываются в массиве. Нет
variant Вариант товара Нет
price Стоимость товара Нет
cost Себестоимость товара Нет
creation_date Дата создания товара Да
update_date Дата изменения/обновления товара, принимает те же значения, что и creation_date Нет
currency Валюта сделки или конкретного поля Нет

Описание элементов массива pagination:

Элемент Описание Обязательный
total_count Количество заявок, которые были изменены после заданной даты Да
limit Количество заявок, которое будет выгружаться за один запрос Да

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

Проверка работы выгрузки

Для проверки работы вашей интеграции воспользуйтесь сервисом проверки выгрузки своей CRM.

Для этого нужно:

  1. Перейти по адресу https://roistat.com/ru/connection/check.
  2. Ввести адрес выгрузки, откуда Roistat будет брать данные.
  3. Ввести логин и пароль из настройки интеграции.
  4. Нажать кнопку Проверить.

Шаг 3. Отправка данных в CRM-систему

В случае выбора GET-запроса будет отправлен следующий запрос:

http://mycrm.com/new/php?action=lead&created_date=YYYY-MM-DD HH:MM:SS&data={"roistat":"12345","custom_field":"value"}&email=new@mail.com&name=Name&phone=79056660012&text=Новый заказ с сайта&title=Заказ с сайта&token=abc1234567890&user=test_user&visit=12345&manager_id=12345

В случае выбора POST-запроса будет отправлен следующий запрос:

Header:

http://mycrm.com/new/php?action=lead&token=abc1234567890&user=test_user

Body:

created_date=YYYY-MM-DD HH:MM:SS&data={"roistat":"12345","custom_field":"value"}&email=new@mail.com&name=Name&phone=79056660012&text=Новый заказ с сайта&title=Заказ с сайта&visit=12345

Подробное описание параметров запроса:

  • action=lead – параметр action отвечает за определения типа запроса, отправляемого Roistat. action=lead означает создание новой заявки.
  • user – пользователь, который был введен на шаге авторизации.
  • token – формируется из имени пользователя и пароля, которые были настроены на шаге Авторизация.
  • title – заголовок новой заявки.
  • data – в данном параметре передается JSON дополнительных полей заявки. В том числе, поля roistat, где содержится номер визита. Данные содержатся в формате: "custom_field":"value".
  • manager_id – ответственный менеджер, который указан на этапе «отправка данных в CRM».
  • email – email-адрес клиента, оставившего заявку.
  • name – имя клиента, оставившего заявку
  • phone – номер телефона клиента, оставившего заявку
  • text – комментарий заявки, содержащий дополнительную информацию.

В ответ на запрос о создании новой сделки ожидается ответ следующего вида:

{
"status" : "ok",
"order_id" : "{ID_сделки}"
}

order_id – ID сделки, которая была создана в CRM-системе. ID должен соответствовать идентификатору сделки в массиве orders.

Если не будет получен данный ответ, будет произведена повторная попытка отправить заявку (таким же запросом).

Обработка информации о новой заявке

В зависимости от того, какие сущности поддерживаются CRM-системой, необходимо создать сущность, которая позволит пользователям CRM-системы обработать новую заявку (заказ, сделка, лид и т.д.). Если система поддерживает сущность Контакт (клиент), то контактные данные заявки необходимо записать туда.

  • title. Из этого параметра необходимо сформировать заголовок новой заявки. Если заголовок заявки не поддерживается, то желательно зафиксировать данные из Title в комментариях.
  • data. Необходимо записать данные из JSON в дополнительные поля заявки по ID полей, которые указаны в массиве. Значение из параметра "roistat" необходимо записать в соответствующее поле CRM.
  • text. Необходимо записать значение этого параметра в комментарий заявки.
  • manager_id. Необходимо установить ответственным за заявку менеджера, который указан в этом параметре.
  • name, email, phone. Необходимо проверить наличие текущего контакта с указанными контактными данными. Если был найден существующий контакт, то к нему необходимо привязать новую заявку. Если нет – создать новый и записать контактные данные в него.
  • Если система не поддерживает создание контактов (например, все новые заявки приходят как лид), то необходимо записать контактные данные в сущность Лид.

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

{
"status" : "ok",
"order_id" : "{ID_сделки}"
}
Если не передать этот ответ, информация о заявке будет отправляться на эту страницу раз в несколько часов.

Проверка передачи заявок

Для проверки работы вашей интеграции воспользуйтесь сервисом проверки выгрузки своей CRM.

Для этого нужно:

  1. Перейти по адресу https://roistat.com/ru/connection/check.
  2. Заполнить адрес выгрузки.
  3. Ввести адрес обработчика заявок.
  4. Выбрать способ отправки запроса.
  5. Нажать кнопку Проверить.

Шаг 4. Обновление данных в CRM-системе

В настройках интеграции на вкладке Отправка данных в СRM необходимо указать Адрес для получения доп. информации по сделке. На этот адрес будет отправляться дополнительная информация по текущим сделкам в зависимости от работы различных механизмов внутри Roistat.

Если вы не используете дополнительный обработчик, добавьте в поле Адрес для получения доп. информации по сделке тот же адрес, который указан в поле Адрес обработчика заявок.

Обратите внимание:

Если домен защищен SSL сертификатом, необходимо указать ссылку с протоколом: https://domain.com

Добавление комментария к текущей сделке

Комментарий к уже созданной сделке может быть добавлен в следующих случаях:

  • Передача текста чата в случае, когда чат был завершен после создания сделки. Например, интеграция с Jivosite.
  • Передача информации о дублирующей заявке (если пользователь включил настройку).

В случае выбора в настройках GET-запроса Roistat отправляет:

http://mycrm.com/new/php?action=message&leadId=12345&title=Заголовок сообщения&message=Текст сообщения&token=abc1234567890&user=test_user

В случае выбора POST-запроса Roistat отправляет:

Header:

http://mycrm.com/new/php?action=message&token=abc1234567890&user=test_user

Body:

leadId=12345&title=Заголовок сообщения&message=Текст сообщения

Подробные параметры запроса:

  • action=message – добавление сообщения к сделке;
  • user – пользователь CRM;
  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password; 
  • leadId – ID сделки или иной сущности, в которую необходимо добавить сообщение;
  • title – заголовок сообщения;
  • message – текст сообщения.

Обработка запроса на добавление комментария

Необходимо осуществить поиск и добавить комментарий в сделку (по параметру leadId).

Добавление задачи к текущей сделке

Задача к уже созданной сделке может быть добавлена в следующих случаях:

  • Часть функциональности инструмента Автоматизация маркетинга.
  • Передача информации о дублирующей заявке (если пользователь включил настройку).

В случае выбора GET-запроса в настройках Roistat отправляет:

http://mycrm.com/new/php?action=task&element_id=12345&deadline=2019-01-01T11:11:11&text=Текст задачи&token=abc1234567890&user=test_user

В случае выбора POST-запроса Roistat отправляет:

Header:
http://mycrm.com/new/php?action=task&token=abc1234567890&user=test_user

Body:
element_id=12345&deadline=2019-01-01T11:11:11&text=Текст задачи

Разберем параметры запроса подробнее:

  • action=task – добавление задачи к текущей сделке;
  • user – пользователь CRM;
  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password; 
  • element_id – ID сделки или иной сущности, в которую необходимо добавить задачу;
  • deadline – крайний срок задачи (UTC+0);
  • text – текст задачи.

Обработка запроса на добавление задачи

Необходимо осуществить поиск и добавить задачу в сделку (по параметру element_id) на ответственного за неё менеджера. Как ответ на запрос Roistat ожидает:

{"status":"ok","task_id":"{task_id}"}

Добавление звонка к текущей сделке

Звонки необходимо добавить к текущей сделке, если пользователю необходимо прослушивать запись звонка из CRM-системы по сделкам, созданным по звонкам, которые прошли через Roistat.

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

В случае выбора GET-запроса в настройках Roistat отправляет:

http://mycrm.com/new/php?action=call&id=12&callee=79012223344&caller=78002225566&visit=12345&marker=vk_new_post&status=answered&duration=50&file_url=&order_id=12345&date=2019-01-01T11:11:11&user=test_user&token=abc1234567890

В случае выбора POST-запроса Roistat отправляет:

Header:
http://mycrm.com/new/php?action=call&token=abc1234567890&user=test_user

Body:
id=12&callee=79012223344&caller=78002225566&visit=12345&marker=vk_new_post&status=answered&duration=50&file_url=&order_id=12345&date=2019-01-01T11:11:11

Разберем параметры запроса подробнее:

  • action=call – добавление звонка;
  • user – пользователь CRM;
  • token – имя пользователя и пароль в CRM, сгенерированные в md5 в формате $username . $password;
  • id – ID звонка в системе Roistat;
  • callee – кому был совершен вызов;
  • caller – кто совершил вызов;
  • date – дата звонка (UTC+0); 
  • visit – номер визита (подробнее про номер визита можно прочитать в начале статьи);
  • marker – маркер, рекламный источник визита;
  • status – статус звонка. Возможные статусы звонка:

    • ACTIVE – звонок в процессе; 
    • ANSWER – звонок был принят и обработан сотрудником; 
    • BUSY – входящий звонок был, но линия была занята; 
    • NOANSWER – входящий вызов состоялся, но в течение времени ожидания ответа не был принят сотрудником; 
    • CANCEL – входящий вызов состоялся, но был завершен до того, как сотрудник ответил; 
    • CONGESTION – вызов не состоялся из-за технических проблем; 
    • CHANUNAVAIL – вызываемый номер был недоступен; 
    • DONTCALL – входящий вызов был отменен; 
    • TORTURE – входящий вызов был перенаправлен на автоответчик
  • order_id – номер сделки, которая была создана по звонку;

  • duration – длительность вызова;
  • file_url – запись разговора.

Обработка запроса на добавление звонка

Необходимо осуществить поиск и добавить звонок в сделку (по параметру order_id). Добавленная сущность звонка должна решить задачу клиента – дать возможность прослушать звонок непосредственно в CRM. Также можно осуществить дополнительные действия со сделкой в результате статуса звонка. Добавить статус как комментарий, тег и т.д. Как ответ на запрос Roistat ожидает:

{"status":"ok","call_id":"{call_id}"}

Шаг 5. Авторизация

После создания дополнительного поля Roistat в модуле интеграции Своя CRM необходимо ввести авторизационные данные, которые будут использоваться в запросах к CRM: 

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

    Обратите внимание:

    Если домен защищен SSL сертификатом, необходимо указать ссылку с протоколом: https://domain.com

  • Имя пользователя и пароль, из которых формируется md5 token для авторизации запросов. Имя пользователя и пароль нужно вводить в формате $username . $password. 

  • Ссылка на сделку в CRM. Чтобы пользователи могли быстро переходить из Roistat в конкретную сделку в CRM, необходимо добавить маску ссылки на сделку. Обратите внимание, что это поле заполнять не обязательно.

    Пример: http://mycrm.com/orders/{order_id}/view, где {order_id} будет заменен на ID сделки. 

  • Ссылка на контакт в CRM. Чтобы пользователи могли быстро переходить из Roistat в конкретный контакт в CRM, необходимо добавить маску ссылки на контакт. Пример: http://mycrm.com/orders/{contact_id}/view, где {contact_id} будет заменен на ID контакта. 

Шаг 6. Назначение ответственных за заявки

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

Отправку менеджеров вместе с заявкой описана в пункте Отправка данных в CRM-систему.

Шаг 7. Распределение статусов

Для учета сделок пользователь распределяет их по группам:

  • В работе
  • Оплаченные
  • Отмененные

Подробнее: Распределение статусов сделок

Статусы загружаются со страницы выгрузки в результате ответов на запросы action=import_scheme или action=export.

Шаг 8. Расширенные настройки

В расширенных настройках пользователь указывает:

После того, как интеграция завершена, рекомендуем настроить процесс передачи сделок в CRM через Roistat. В ходе этого процесса сделки сначала передаются в Roistat, затем отправляются в CRM. Подробнее о преимуществах этого процесса читайте в статье Передача заявок в CRM через Roistat.

Если отправка сделок с сайта в CRM уже настроена с помощью вашего кода, для обмена данными с Roistat вам необходимо заполнить дополнительное поле roistat сделки значением куки браузера roistat_visit.

Пример кода, с помощью которого можно получить значение этой куки:

$roistatVisitId = array_key_exists('roistat_visit', $_COOKIE) ? $_COOKIE['roistat_visit'] : "неизвестно";

Переход со старой интеграции «Своя CRM» на новую версию

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

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

  1. Доработать страницу выгрузки (action=export или action=import_scheme) на передачу массива managers (описано в пункте выгрузка сделок из CRM-системы). Данные из этого массива будут использоваться в отчете по менеджерам и в дальнейшем для расширенной настройки ответственных в CRM-системе. Например, назначение ответственного за сделку менеджера, который завершил телефонный разговор с клиентом.

  2. Доработать Адрес для получения доп. информации по сделке на добавление в CRM задач, комментариев, звонков (action=task, action=message, action=call). Примеры использования дополнительной информации описаны в пункте Обновление данных в CRM-системе.

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

*Правообладателем Facebook является запрещенная на территории РФ компания Meta Platforms, признанная судом экстремистской.