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

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

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

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

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

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

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

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

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

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

Ниже описаны процессы интеграции Roistat с 1С.

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

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

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

Статусы передаются по 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"
}

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

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

В 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"
}

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

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

ЧтениеJSON = Новый ЧтениеJSON; 
ЧтениеJSON.УстановитьСтроку(ОтветСервера); 
ДанныеJSON = ПрочитатьJSON(ЧтениеJSON); 

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

1. Справочник «Контрагент» с контактными данными, указанными в заявке Roistat.
2. Документ «Заявка» с соответствующим типом обращения.

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

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

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

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

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

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

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

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

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

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

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

Для выгрузки сделок из 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": "Валера"
   }
 }
]

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

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

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

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

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

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

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

Для выгрузки сделок из 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"
  }
]

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

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

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

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

1. Отправка заявок с сайта:

   1. Перейдите на сайт и отправьте заявку.

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

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

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

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

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

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

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

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