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

Интеграция Roistat с 1C-Битрикс версии УТ11

Настройка интеграции

Интеграция между 1С и Roistat выполняется по API. Сервер Roistat самостоятельно не инициирует запросы, а только отвечает на обращения от сторонних ресурсов. То есть база 1С периодически обращается к серверу Roistat для синхронизации данных.

Для подключения интеграции в личном кабинете Roistat перейдите в раздел Каталог интеграций, в разделе CRM выберите Интеграция через API и нажмите Настроить интеграцию: 1.png

Для интеграции следует использовать API-ключ владельца проекта. Его можно найти в разделе Мой профиль → API: 2.png

Общие принципы работы интеграции

Работа интеграции состоит из нескольких процессов. Один из процессов выполняется разово: загрузка в систему Roistat предусмотренных статусов. Остальные (получение и отправка данных) выполняются регулярно, рекомендуемая периодичность для того или иного выполнения будет рассмотрена в разделе описания конкретного процесса. 

Схема работы интеграции

3.png

Внимание!

Рекомендуем ознакомиться с шаблоном модуля интеграции, написанным для 1С версии УТ11. Его можно скачать из этого архива

В приведенном архиве используется следующая цепочка документов: Сделка с клиентом - Заказ - Реализация.Сделка в данном случае выступает аналогом лида из других CRM, использующим модель лид-сделка. Изначальное обращение из того или иного источника (форма сайта, телефония, виджет и т.д.) создается в виде сделки с клиентом, а далее при необходимости на основании этого первичного документа создается заказ и его дальнейшая реализация. Схема документов из примера: 4.png Ниже описаны процессы интеграции Roistat с 1С:

Загрузка статусов в Roistat

Первоначально необходимо определить, какие этапы в вашем бизнес-процессе планируется отслеживать. Например, это могут быть статусы работы с документом "Заявка", или этапы создания таких связанных документов, как реализация. Далее выбранные статусы необходимо передать в Roistat.

Публичное описание API, с помощью которого передаются статусы, находится по этой ссылке.

Внимание!

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

Внимание!

Тип статуса в системе Roistat соответствует одной из трёх групп, по которым распределялись статусы, загрузившиеся из вашей CRM в Roistat:

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

Для выгрузки сделок из 1С в Roistat необходимо выполнить POST-запрос по адресу https://cloud.roistat.com/api/v1//project/set-statuses?project={project_id}&key={user_key}.

В теле запроса необходимо передать текст в формате JSON содержащий массив статусов.

Пример: 

[
  {
    "id": "0",
    "name": "Новая сделка",
    "type": "progress"
  },
  {
    "id": "1",
    "name": "Подготовка КП",
    "type": "progress"
  },
 {
    "id": "2",
    "name": "КП отправлено",
    "type": "progress"
  },
  {
    "id": "3",
    "name": "Выставлен счёт",
    "type": "progress"
  },
  {
    "id": "4",
    "name": "Оплачено",
    "type": "paid"
  },
  {
    "id": "5",
    "name": "Отменен",
    "type": "canceled"
  }
]

В результате, если модуль интеграции через API был подключен в личном кабинете, и JSON-массив статусов был подготовлен корректно, Roistat сообщает ответ:

{
  "status": "success"
}

После этого в настройках интеграции должны появиться статусы, которые вы передавали: 5.png

Получение данных по заявкам

В Roistat с сайта, виджетов, телефонии и т. д. поступают заявки, которые необходимо передать в 1С для последующей работы с ними. Публичное описание API, с помощью которого запрашиваются данные по заявкам, доступно по адресу: https://roistat.api-docs.io/v1/proksi-lidy/f2TFnCBdgnqCC9TBA.

Внимание!

Для получения заявок необходимо отправить из 1С запрос на адрес https://cloud.roistat.com/api/v1/project/proxy-leads?project={project_id}&key={user_key}&period={period}, где:

  1. {project_id} - номер проекта в Roistat
  2. {user_key} - секретный ключ безопасности получаемый в профиле пользователя на вкладке API (https://cloud.roistat.com/user/profile/api)
  3. {period} - период "Дата начала"-"Дата окончания", за который необходимо получить заявки из Roistat в формате YYYY-MM-DD-YYYY-MM-DD (Пример: 2018-01-08-2018-01-11)

В результате сервер Roistat возвращает ответ в формате JSON, который представляет собой массив структур с информацией по заявкам.

Пример:

{
  "ProxyLeads": [
    {
      "id": "2",
      "title": "Лид с формы заказать звонок",
      "text": "Прошу перезвонить",
      "name": "Питер Пен",
      "phone": "71234567890",
      "email": "peter@yandex.ru",
      "roistat": "1000",
      "creation_date": "2016-07-12 14:51:39",
      "order_id": "12346",
      "order_fields": {
        "cost_field_id": "200"
      }
    },
    {
      "id": "1",
      "title": "Лид с формы заказать звонок",
      "text": "",
      "name": "Алиса",
      "phone": "79998887766",
      "email": "alice@yandex.ru",
      "roistat": "1001",
      "creation_date": "2016-07-12 14:10:20",
      "order_id": "12345",
      "order_fields": {
        "cost_field_id": "100"
      }
    }
  ],
  "status": "success"
}

Внимание!

Загрузка заявок производится по расписанию регламентным заданием. Периодичность: "Каждый день, каждые 60 сек". Период для загрузки  с "Текущая дата - 3 дня" по "Текущая дата". Также следует предусмотреть ограничение по времени выполнения задания в 50 секунд.

Описание полей заявки (описаны основные поля, так же в ответе сервера могут быть дополнительные поля, которые в данном руководстве не рассматриваются):

Параметр Пример Описание
id 1234 Номер сделки в Roistat. Уникален в рамках проекта. Обязательное.
title Лид с формы заказать звонок Название сделки.
text Дополнительная информация Комментарий к сделке, значение полей формы, ссылка на чат с консультантом и т.д.
name Иван Имя посетителя.
phone 79999998555 Телефон посетителя. Может быть пустым. Формат зависит от АТС, обычно 7XXXXXXXXXX
email test10@test.ru Адрес электронной почты посетителя.
roistat 31042 Номер визита посетителя (цифровое)/маркер рекламного канала (текстовое). 
creation_date 2018-02-20 13:14:46 Дата и время создания сделки в Roistat. Для call-трекинга дата и время регистрации звонка.
order_fields "form": "Расчёт стоимости","site": "site.com" Дополнительные поля сделок.

После получения ответа от сервера его необходимо преобразовать во внутренние структуры 1С для дальнейшей работы. Пример функции преобразования: ЧтениеJSON = Новый ЧтениеJSON; ЧтениеJSON.УстановитьСтроку(ОтветСервера); ДанныеJSON = ПрочитатьJSON(ЧтениеJSON);

При поступлении первичной заявки с типом обращения = «Заявка с сайта» создать:

  1. Справочник "Контрагент" с контактными данными, указанными в заявке Roistat.
  2. Документ "Заявка" с соответствующим типом обращения.
  3. В созданном документе "Заявка" присвоить полю "Roistat_НомерСделки" значение из поля "id".

Внимание!

Roistat_НомерСделки используется для передачи уникального идентификатора заявки. Если необходимо выгружать в Roistat документы "Заявка", созданные вручную, в поле Roistat_НомерСделки необходимо передавать уникальный в 1С идентификатор, который не будет повторяться у других документов внутри 1С (в том числе создаваемых в будущем).

  1. В созданном документе "Заявка" присвоить полю «Roistat_НомерВизита» значение из поля "roistat".
  2. Присвоить «Статус» = "В работе".

Внимание!

Так как данные по заявкам забираются по API (без отправки данных со стороны Roistat на обработчик) - в личном кабинете Roistat будет наблюдаться уведомление: "Ошибка отправленных заявок".

Отправка актуальных данных по заявкам в Roistat

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

Внимание!

Например, заявка, созданная некоторое время назад, была реализована: по ней в 1С появились значения выручки и себестоимости. В Roistat необходимо помимо этих двух значений также передать всю остальную информацию по доп.полям.

Внимание!

Если необходимо анализировать также заказы, созданные в базе вручную, то следует выгружать их с уникальным ID, который никогда в базе повторяться не будет, а также в поле Roistat_НомерВизита писать тот или иной источник привлечения клиентов, например, "Сарафанное радио".

Публичное описание API, с помощью которого передаются актуальные данные по заявкам, доступно по адресу: https://roistat.api-docs.io/v1/zakazy/bqwkcEujoE3GYhcEb

Внимание!

Выгрузка сделок производится по расписанию регламентным заданием. Периодичность: "Каждый день, каждые 600 сек". Выгружать необходимо только измененные за последние 48 часов сделки.

Причины изменения сделок:

  1. Изменение документа "Заявка" (или аналогичного)
  2. Изменение связанных бизнес-процессов, например переход на следующий этап бизнес-процесса
  3. Изменение связанных документов, например создание/проведение документа "Заказ покупателя", "Реализация товаров" или поступление оплаты от клиента.

Цепочка взаимосвязанных документов и бизнес-процессов определяется через структуру подчиненности документов в 1С.

Внимание!

При выгрузке сделки в Roistat, если сделка отсутствует, то она будет создана, если сделка существует, то она будет перезаписана, соответственно в выгрузку необходимо передавать все актуальные данные, а не только измененные.

Для выгрузки сделок из 1С в Roistat необходимо выполнить POST запрос по адресу https://cloud.roistat.com/api/v1/project/add-orders?project={project_id}&key={user_key}.

В теле запроса необходимо передать текст в формате JSON содержащий массив сделок из 1С.

Пример:

[
 {
   "id": "1",
   "name": "Событие 000000001",
   "date_create": "1393673200",
   "status": "0",
   "roistat": "12345",
   "price": "222",
   "cost": "111",
   "client_id": "123",
   "fields": {
     "Manager": "Валера"
   }
 },
 {
   "id": "2",
   "name": "Событие 000000002",
   "date_create": "1393673200",
   "status": "0",
   "roistat": "67890",
   "price": "333",
   "cost": "222",
   "client_id": "124",
   "fields": {
     "Manager": "Валера"
   }
 }
]

Описание полей сделки:

Параметр Пример Описание
id 1234 Номер сделки в Roistat. Уникален в рамках проекта. Берется из документа "Событие" поле «Roistat_НомерСделки». Обязательное.
name Событие 00000034 от 22.02.2018 11:53:08 Название сделки в Roistat. Не обязательное.
date_create 2016-12-12 11:30:10 Дата создания сделки в формате: 1. UNIX-time 2. YYYY-MM-DD HH:MM:SS по московскому времени 3. YYYY-MM-DD HH:MM:SS с указанием смещения относительно UTC (например, 2016-12-12 11:30:10+0000). Если дата передается как 2016-12-12 11:30:10, она воспринимается как 2016-12-12 11:30:10+0300. Обязательное.
status 0 Id статуса сделки (См. раздел передача статусов в Roistat). Обязательное.
price 1000.50 Сумма сделки (Выручка). Не обязательное.
cost 890 Себестоимость сделки. Не обязательное.
roistat 31042 Номер визита посетителя. Берется из документа "Событие" поле «Roistat_НомерВизита». Не обязательное.
client_id 1234 ID контрагента в системе Roistat. Используется если делается выгрузка клиентов в систему. Не обязательное.
fields "Manager": "Валера". Массив дополнительных полей сделок в формате Ключ-Значение. Не обязательное.

Если JSON-массив корректен - Roistat сообщит об успешном приеме.

Внимание!

Также, перейдя в личном кабинете Roistat в раздел "Состояние проекта", после выполнения процесса "Обновить все данные" вы должны увидеть в аналитике переданные заявки.

Отправка актуальных данных по по контрагентам в Roistat

Помимо измененных в заявок в Roistat также необходимо передавать связанных с ними контрагентов.

Публичное описание API, с помощью которого передаются актуальные данные по контрагентам, доступно по адресу:  https://roistat.api-docs.io/v1/klienty/GZ7aiGo7vPTNMbqCF.

Внимание!

Выгрузка сделок производится по расписанию регламентным заданием. Периодичность: "Каждый день, каждые 600 сек". Выгружать необходимо только контрагентов, у которых изменялись сделки за последние 48 часов.

Причины изменения сделок:

  1. Изменение документа "Заявка" (или аналогичного)
  2. Изменение связанных бизнес-процессов, например переход на следующий этап бизнес-процесса
  3. Изменение связанных документов, например создание/проведение документа "Заказ покупателя", "Реализация товаров" или поступление оплаты от клиента.

Внимание!

При выгрузке контрагента в Roistat, если записи о клиенте с таким id нет в базе, то запись будет создана. Если запись с таким id существует, то она будет перезаписана, соответственно в выгрузку необходимо передавать все актуальные данные, а не только измененные.

Для выгрузки сделок из 1С в Roistat необходимо выполнить POST запрос по адресу https://cloud.roistat.com/api/v1/project/clients/import?project={project_id}&key={user_key}.

В теле запроса необходимо передать текст в формате JSON содержащий массив контрагентов из 1С.

Пример: 

[
  {
    "id": "111",
    "name": "Валера",
    "phone": "78888888888",
    "email": "email1@mail.com",
    "company": "company1",
    "fields": {},
    "birth_date": "1980-01-01"
  },
  {
    "id": "222",
    "name": "Ваcилий",
    "phone": "79999999999",
    "email": "email2@mail.com",
    "company": "company2",
    "fields": {},
    "birth_date": "1990-01-01"
  }
]

Описание полей сделки:

Параметр Пример Описание
id 1234 Номер контрагента в Roistat. Уникален в рамках проекта. Берется из документа "Контрагент". Обязательное.
name Иван Имя контрагента в Roistat. Обязательное.
phone 79771234567 Номер телефона клиента (должен быть указан или телефонный номер клиента, или email). Обязательное.
email example@mail.ru Адрес электронной почты клиента (должен быть указан или телефонный номер клиента, или email). Обязательное.
company Компания Товарыторг Название компании клиента. Не обязательное.
fields "Пол": "Мужской" Массив доп.полей контрагента. Не обязательное.
birth_date 31042 Дата рождения контрагента. Не обязательное.

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

6.png

Чек-лист проверки настроек интеграции

Ниже представлен порядок шагов для самостоятельной проверки интеграции.

  1. Отправка заявок с сайта 1.1. Перейдите на сайт и отправьте заявку; 1.2. Заявка должна появиться в личном кабинете Roistat в разделе "Состояние проекта" - "Список отправленных заявок"; 1.3. В течение минуты (или иного промежутка времени, который указан в модуле интеграции 1С и  Roistat) создается в виде документа в 1С со всеми необходимыми доп.полями
  2. Загрузка статусов: в личном кабинете Roistat в разделе "Каталог интеграций" - "Интеграция по API" отображаются все статусы, которые предусмотрены бизнес-процессом, и все они распределены по одной из трех групп.
  3. Загрузка заявок: для тестирования корректности загрузки заявок рекомендуется создать заявки в количестве равном количеству статусов. Далее необходимо перевести одну заявку в один конкретный статус. Таким образом, за одну выгрузку получится проанализировать всю цепочку статусов. 3.1. Созданные и необработанные заявки загружаются в Roistat в первичном статусе с номером визита. 3.2. Заявки, взятые в работу, попадают в выгрузку на каждом из этапов предусмотренного бизнес-процесса вплоть до их окончательной реализации. 3.3. По реализованным заявкам в Roistat отображается выручка, себестоимость и прибыль.
  4. Загрузка контрагентов: в Roistat загружаются контрагенты из 1С и привязываются автоматически к сделкам (сопоставление Rostat производит по переданному id контрагента)