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

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

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

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

Для подключения интеграции в личном кабинете Roistat перейдите в раздел Интеграции и нажмите Добавить интеграцию. В появившемся окне в поисковой строке введите API, кликните по карточке и нажмите Добавить:

1.png

Затем нажмите Настроить интеграцию (иконка шестеренки):

1-2.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://help.roistat.com/API/methods/proxy-leads/#proxy-leads.

Для получения заявок необходимо отправить из 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": "[email protected]",
      "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": "[email protected]",
      "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С (в том числе создаваемых в будущем).

  4. В созданном документе «Заявка» присвоить полю «Roistat_НомерВизита» значение из поля roistat.

  5. Присвоить «Статус» = В работе.

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

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

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

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

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

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

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

Публичное описание API, с помощью которого передаются актуальные данные по заявкам, доступно по адресу: https://help.roistat.com/API/methods/orders

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

Выгрузка сделок производится по расписанию регламентным заданием. Периодичность: "Каждый день, каждые 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 также необходимо передавать связанных с ними контрагентов.

Публичное описание API, с помощью которого передаются актуальные данные по контрагентам, доступно по адресу: https://help.roistat.com/API/methods/clients/.

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

Выгрузка сделок производится по расписанию регламентным заданием. Периодичность: "Каждый день, каждые 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": "[email protected]",
    "company": "company1",
    "fields": {},
    "birth_date": "1980-01-01"
  },
  {
    "id": "222",
    "name": "Ваcилий",
    "phone": "79999999999",
    "email": "[email protected]",
    "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. Перейдите на сайт и отправьте заявку.

    2. Заявка должна появиться в личном кабинете Roistat в разделе Состояние проектаСписок отправленных заявок.

    3. В течение минуты (или иного промежутка времени, который указан в модуле интеграции 1С и Roistat) создается документ в 1С со всеми необходимыми доп. полями.

  2. Загрузка статусов: в личном кабинете Roistat в разделе ИнтеграцииAPIНастроить интеграцию отображаются все статусы, которые предусмотрены бизнес-процессом, и все они распределены по одной из трех групп.

  3. Загрузка заявок: для тестирования корректности загрузки заявок рекомендуется создать заявки в количестве, равном количеству статусов. Далее необходимо перевести одну заявку в один конкретный статус. Таким образом, за одну выгрузку получится проанализировать всю цепочку статусов.

    1. Созданные и необработанные заявки загружаются в Roistat в первичном статусе с номером визита.

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

    3. По реализованным заявкам в Roistat отображаются выручка, себестоимость и прибыль.

  4. Загрузка контрагентов: контрагенты из 1С загружаются в Roistat и автоматически привязываются к сделкам (Roistat сопоставляет данные по переданному id контрагента).