Техническое задание для интеграции с CRM системами

Последние изменения: 10.10.2023

Предполагаемые данные для интеграции в CRM систему:

1. Интеграция списка клиентов из UDS в CRM систему и тегов клиента

2. Интеграция заказов из UDS в CRM систему

3. Интеграция списка операций из UDS в CRM систему

4. Интеграция товаров

Интеграция построена на обработке входящих вебхуков от UDS CRM системой.

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

Важно! Для отправки вебхуков необходимо сгенерировать API Key, если он отсутствует

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

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

UDS отправляет вебхук методом POST с JSON-объектом в теле запроса. Для безопасности вебхуки хешируются с помощью md5, что позволяет Вашему серверу убедиться, что данные отправляются именно от UDS.

1. Интеграция клиентов

У каждого клиента в компании есть свой уникальный идентификатор - его можно посмотреть в личном кабинете UDS Бизнес, в выгрузке Excel по клиентам, в запросе по API метод find customer или получить в вебхуке при присоединении нового клиента.

Интеграционный модуль должен обрабатывать входящий вебхук о присоединении нового клиента.
При наличии номера телефона, имени клиента интеграционный модуль должен сопоставить клиента из UDS с клиентом из CRM и указать клиенту из CRM идентификатор из UDS participant -> id
При отсутствии клиента в CRM системе интеграционный модуль должен создать клиента в CRM и заполнить необходимые поля из вебхука от UDS. С описанием полей можно ознакомится тут

Пример вебхука:

{
  "phone": +78007754524,
  "gender": "NOT_SPECIFIED",
  "uid": "18c354ec-278b-41cd-a003-0214f448f299",
  "birthDate": "1999-06-21",
  "avatar": null,
  "participant": {
    "cashbackRate": 11,
    "dateCreated": "2021-06-21T09:46:28.054Z",
    "discountRate": 0,
    "id": 1099123456789,
    "inviterId": 1090123456789,
    "lastTransactionTime": null,
    "membershipTier": {
      "conditions": {
        "effectiveInvitedCount": null,
        "totalCashSpent": null
      },
      "name": "Базовый",
      "rate": 11,
      "uid": "base"
    },
    "points": 100
  },
  "displayName": "Иван Иванов"
}

Интеграционный модуль должен уметь актуализировать список клиентов с идентификатором UDS из CRM системы. Список можно обновлять GET запросами в Partner API UDS:

- по каждому отдельному клиенту по его идентификатору
https://api.uds.app/partner/v2/customers/{идентификатор клиента}
- из списка клиентов по идентификатору клиента из ответа
https://api.uds.app/partner/v2/customers?max=10&offset=0Примечание:

Если оплата проводится по номеру телефона клиента, незарегистрированного в UDS,то во входящем вебхуке для такого клиента в displayName будет указан номер телефона, в поле uid будет null - таким образом можно определить зарегистрирован ли клиент в UDS.

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

2. Интеграция операций

У каждой операции в UDS есть свой уникальный идентификатор - его можно посмотреть в личном кабинете UDS Бизнес, в выгрузке Excel по операциям, в запросе по API метод get transaction или получить в вебхуке при проведении новой операции.

Интеграционный модуль должен обрабатывать входящий вебхук о проведении новой операции.
Интеграционный модуль должен сопоставить новую операцию с клиентом в CRM по идентификатору клиента UDS из поля customer -> id (соответствует идентификатору клиента из пункта 1) и записать новую операцию клиенту в CRM (то есть у клиента в CRM должна эта операции записать в историю сделок, оплат и т.п.)
При отсутствии клиента с идентификатором customer -> id в CRM интеграционный модуль должен создать клиента в CRM, отправив GET запрос в Partner API UDS (https://api.uds.app/partner/v2/customers/{идентификатор клиента}) и из ответа заполнить требуемые поля. С описанием полей можно ознакомится тут

Пример вебхука:

{
  "id": 296982952,
  "dateCreated": "2021-06-21T09:43:40.605Z",
  "action": "PURCHASE",
  "state": "NORMAL",
  "customer": {
    "id": 1099123456789,
    "uid": "aa11d203-d643-4cce-bb2b-e70efcab74a5",
    "displayName": "Иван Иванов",
    "membershipTier": {
      "uid": "f91234fc-3f24-45ea-8eb1-16d00a7370d2",
      "name": "PLATINUM",
      "conditions": {
        "totalCashSpent": {
          "target": 10000
        }
      },
      "rate": 21
    }
  },
  "cashier": {
    "id": 2712234337919,
    "displayName": "UDS Admin"
  },
  "points": -10,
  "cash": 990,
  "total": 1000,
  "receiptNumber": null
}

Интеграционный модуль должен уметь актуализировать список операций, ее статус из UDS в CRM. Список можно обновлять GET запросами в Partner API UDS:

- по каждой отдельной операции по ее идентификатору
https://api.uds.app/partner/v2/operations/{идентификатор операции}
- из списка операций по идентификатору операции из ответа
https://api.uds.app/partner/v2/operations?max=10&cursor=cursor

Возможные статусы операции: NORMAL - стандартная операция, REVERSAL - операция возврата, CANCELED - операция, по которой сделан возврат.

Если в CRM системе статус NORMAL, а из ответа Partner API UDS статус операции CANCELED - это означает, что по операции в UDS совершен возврат и ее статус в CRM также надо сменить на соответствующий.

Для операции со статусом REVERSAL в запросе передается также идентификатор операции, по которой сделан возврат, в объекте origin -> id.

Если операция по идентификатору не найдена, то означает, что она удалена в UDS и ее в CRM также надо удалить или указать на соответствующий статус.

3. Интеграция заказов

У каждого заказа в UDS есть свой уникальный идентификатор - его можно посмотреть в личном кабинете UDS Бизнес или получить в вебхуке при получении нового заказа.

Интеграционный модуль должен обрабатывать входящий вебхук о получении нового заказа.
Интеграционный модуль должен сопоставить новый заказ с клиентом в CRM по идентификатору клиента UDS из поля customer -> id (соответствует идентификатору клиента из пункта 1) и записать новый заказ клиенту в CRM (то есть у клиента в CRM должна этот заказ записать в историю сделок, оплат и т.п.)
При отсутствии клиента с идентификатором customer -> id в CRM интеграционный модуль должен создать клиента в CRM, отправив GET запрос в Partner API UDS (https://api.uds.app/partner/v2/customers/{идентификатор клиента}) и из ответа заполнить требуемые поля. С описанием полей можно ознакомится тут
Интеграционный модуль должен создавать открытую сделку в CRM системе, указать данные по заказу (список товаров, адрес доставки, самовывоза, способ оплаты и т.п.). С описанием полей можно ознакомится тут
Если в составе заказа меняется список товаров через CRM, то интеграционный модуль должен отправить методом PUT измененный заказ в Partner API UDS для актуализации состава заказа в UDS.
Если заказ из UDS переходит в CRM в статус завершенных, то его также нужно завершить в UDS, отправив POST запрос с идентификатором заказа

https://api.uds.app/partner/v2/goods-orders/{идентификатор заказа}/complete

Пример вебхука:

{
  "cash": 270,
  "onlinePayment": null,
  "purchase": {
    "cash": 270,
    "discountAmount": 0,
    "certificatePoints": 0,
    "maxPoints": 10,
    "extras": {},
    "netDiscount": 10,
    "points": 10,
    "netDiscountPercent": 3.57,
    "cashBack": 9.9,
    "total": 280,
    "cashTotal": 270,
    "skipLoyaltyTotal": 180,
    "pointsPercent": 3.57,
    "discountPercent": 0
  },
  "delivery": {
    "address": null,
    "branch": {
      "displayName": "ул. Мира, 1, Москва, Россия, 123456",
      "id": 2199023540548
    },
    "deliveryCase": null,
    "receiverName": "Иван Иванов",
    "receiverPhone": "+78007754524",
    "type": "PICKUP",
    "userComment": "Комментарий от клиента"
  },
  "certificatePoints": 0,
  "customer": {
    "displayName": "Иван Иванов",
    "id": 1099123456789,
    "membershipTier": {
      "conditions": {
        "effectiveInvitedCount": null,
        "totalCashSpent": null
      },
      "name": "Базовый",
      "rate": 11,
      "uid": "base"
    },
    "uid": "18c123ec-278b-41cd-a003-0214f448f299"
  },
  "comment": null,
  "dateCreated": "2021-06-21T09:47:29.372Z",
  "points": 10,
  "id": 876619,
  "total": 280,
  "items": [
    {
      "externalId": "coffee_cappuccino1",
      "id": 1594565,
      "name": "Капучино",
      "price": 90,
      "qty": 2,
      "sku": "1,
      "type": "VARYING_ITEM",
      "variantName": "Маленький 100 мл"
    },
    {
      "externalId": null,
      "id": 1463419,
      "name": "Шарф",
      "price": 100,
      "qty": 1,
      "sku": "",
      "type": "VARYING_ITEM",
      "variantName": "черный"
    }
  ],
  "paymentMethod": {
    "name": null,
    "type": "CASH"
  },
  "state": "NEW"
}

Интеграционный модуль должен уметь актуализировать статус заказа из UDS в CRM. Заказ можно обновлять GET запросом в Partner API UDS:

- по каждому отдельному заказу по его идентификатору
https://api.uds.app/partner/v2/goods-order/{идентификатор заказа}

Возможные статусы операции: NEW - новый заказ, COMPLETED - заказ завершен, DELETED - заказ отменен.

Если в CRM системе статус NEW, а из ответа Partner API UDS статус заказа COMPLETED или DELETED - это означает, что заказ завершен или отменен в UDS и его статус в CRM также надо сменить на соответствующий.

Примечание:

Если у заказа статус COMPLETED или DELETED, то статус в UDS больше смениться не может и запросов по этому заказу в Partner API UDS не нужно отправлять.

4. Интеграция товаров

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

Помогла ли вам статья?