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

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

Интеграция поддерживает форматы JSON и XML для входящих и исходящих массивов данных.

Перед началом настройки

Шаг 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}, если хотите отнести сделку к каналу Facebook1. Например, 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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)

В ответ на запрос 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-системы

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

Примечание

При выгрузке сделок из CRM с пустым полем roistat, номер визита подставляется из заявки при совпадение ID сделки в выгрузке с ID сделки из заявки. Сделки, созданные через Roistat, будут с визитом, даже если поле roistat в CRM не заполнено или нет технической возможности заполнять поля в 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 — зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)

  • 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
                }
            ]
        }
    ]
}
При выгрузке сделок можно в конкретной сделке переопределить цены товара, передав в поля price и cost свои значения.

Пример
"products": [
    {
        "id": "1",
        "count": 3,
        "price": 300,
        "cost": 100
    },
    {
        "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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)

  • 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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)
  • 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
    }
}

Для передачи категорий (categories) поддерживаются два формата: массим и объект.

Пример массива
"categories": [
               "Электросамокаты",
               "Городские самокаты",
               "Самокаты Xiaomi"
            ]
Пример оъекта
"categories": {
               "category1": "Электросамокаты",
               "category2": "Городские самокаты",
               "category3": "Самокаты Xiaomi"
            }

Описание элементов массива 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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)
  • 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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)
  • 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 – зашифрованная в формате md5 строка, состоящая из имени пользователя и пароля CRM. Например, md5(‘myusernamemypassword’)
  • 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 для авторизации запросов.

  • Ссылка на сделку в 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. Расширенные настройки

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

Отправка информации на URL вебхука

Вы можете настроить отправку информации об изменении сделок, чтобы данные в системе обновлялись в режиме реального времени. Если такая отправка настроена, данные в системе будут обновляться ~ раз в 10-15 минут, а не раз в несколько часов.

В каких еще случаях это может быть полезно:

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

  • В Аналитике всегда будет актуальная информация с точностью до последних 10-15 минут, такм образом можно быстрее принимать бизнес-решения.

  • Сценарии по сделкам в Автоматизации маркетинга будут срабатывать через 10-15 минут после появления сделки в CRM.

  • В ВАТС будут стабильнее работать сценарии с действием Соединить с ответственным, так как информация об ответственном будет обновляться быстрее.

Настройка

  1. На шаге Расширенные настройки нажмите Показать рядом с URL вебхука для получения информации об обновлении сделки.

  2. Настройте отправку обновленной информации о сделках на указанный URL. Информацию необходимо отправить в формате:

    {"orders":[{"id":"1","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}]}]}
    

Совет

После того, как интеграция завершена, рекомендуем настроить процесс передачи сделок в 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-системе.

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


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