Документация
Как зарегистрироваться и настроить Salesbeat,
виджет, API и выгрузку заказов в службы доставки
Начало
Как зарегистрироваться?
Зарегистрироваться в Salesbeat очень просто и занимает меньше одной минуты. А чтобы у вас точно не возникло вопросов, мы решили сделать видео по каждому аспекту использования Salesbeat.
Отлично. Теперь у нас есть аккаунт и самое время подключить используемые службы доставки и посмотреть, как виджет выглядит на нашем сайте!
Настройка
Как сделать скидку или наценку на доставку? Увеличить срок доставки?
Часто бывает, когда мы хотим сделать доставку дешевле — например, сделать бесплатную доставку для заказов от определённой суммы. Или мы проводим акцию с бесплатной доставкой по промокоду. А может быть мы хотим сделать наценку на отправки Почтой России или добавить 1 день в базовый срок доставки СДЭК?

Всё это реализуется в пару кликов в интерфейсе Salesbeat.
Интеграция Salesbeat в товарную карточку
У нас есть готовые решения для Битрикс, InSales, Тильда, CS-Cart, PrestaShop, OpenCart. Если у вас самописная CMS или вашей CMS нет в списке — наше решение можно проинтегрировать самостоятельно так, как описано ниже.

Для интеграции виджета Salesbeat (см. пример) в товарную карточку нужно подключить наш JavaScript код и вызвать один JavaScript метод SB.init, передав в него несколько параметров — API токен, вес товара, цену.
<script src="https://app.salesbeat.pro/static/widget/js/widget.js" charset="UTF-8"></script>
<div id="salesbeat-deliveries-1" class="salesbeat-deliveries"></div>
<script> 
    SB.init({
        token: 'your API token',
        price_to_pay: 5000,
        price_insurance: 5000,
        weight: 200,
        x: 20,
        y: 10,
        z: 3,
        quantity: 2,
        city_by: 'ip',
        params_by: 'params',
        main_div_id: 'salesbeat-deliveries-1',
        callback: function(){
            console.log('Salesbeat is ready!');
        }
    });
</script>
Обратите внимание, что в init функцию необходимо передать следующие параметры:

  • token — API токен магазина, доступен здесь
  • price_to_pay — сумма наложенного платежа в рублях
  • price_insurance — объявленная стоимость для страховки в рублях
  • weight — вес в г
  • x, y, z — опционально (но желательно) размеры в см. Если размеры не переданы, будет считаться, что размеры подходят для минимального тарифа
  • quantity — количество товара в шт, по умолчанию 1
  • city_by — строковое значение "ip", если город посетителя необходимо определить автоматически по его IP адресу, или "city_code", если идентификатор города передаётся вручную в виджет в отдельном параметре city_code
  • params_by — принимает строковое значение "params", если вес и размеры товара передаются в отдельных параметрах weight, x, y, z; или "product_id", если в систему загружены продукты с проставленными размерами и весами, тогда вместо явной передачи размеров и веса в виджет можно передать только идентификатор (артикул) продукта в отдельном параметре product_id.
  • callback — опциональная JavaScript функция, которая вызовется после добавления виджета на страницу. Может быть использован, если изначально виджет скрыт и по нажатию на какой-то элемент на странице (ссылка «доставка») нужно инициализировать виджет и отобразить div с ним
  • main_div_id — идентификатор div элемента, в который вставится виджет. Сам div элемент с данным идентификатором необходимо вставить в HTML код страницы в нужном месте, куда планируется добавление виджета.
  • extra_data — опциональное произвольное текстовое поле, на которое можно настроить правила («Дополнительное поле» в интерфейсе правил)
Вот и виджет готов! А если вы хотите изменить его внешний вид, настройте его с помощью конфигуратора здесь, там же в расширенных настройках можно ввести необходимые CSS параметры для изменения дизайна виджета.
Пересчет доставки при смене количества товара
Если на продуктовой странице есть смена количества товара, добавляемого в корзину, то для того, чтобы при смене количества пересчитывалась доставка в товарном виджете Salesbeat, надо добавить data-атрибуты для input элемента, хранящего количество товара, а также для его родительского класса. Например:
<ul class="quantity" data-sb-quantity data-sb-widget-id="salesbeat-deliveries-1">
    <li class="quantity__btn" data-sb-quantity-control>-</li>
    <li><input type="text" value="1" class="quantity__input" data-sb-quantity-input></li>
    <li class="quantity__btn" data-sb-quantity-control>+</li>
</ul>
Обратите внимание — для элемента ul (родительского элемента, в котором находится input — на вашем сайте это может быть div или другой элемент) добавлен атрибут data-sb-quantity, а также атрибут data-sb-widget-id со значением salesbeat-deliveries-1, где salesbeat-deliveries-1 — идентификатор div элемента с виджетом (этот идентификатор передаётся при инициализации виджета в функцию SB.init в параметре main_div_id).

Для самого элемента input добавлен атрибут data-sb-quantity-input.

Для элементов +/-, которые увеличивают/уменьшают количество товара, добавлен атрибут data-sb-quantity-control.

Такая разметка позволит Salesbeat автоматически пересчитывать доставку в товарном виджете при смене количества товара на странице.
Интеграция Salesbeat в корзину
Для установки нужно подключить два скрипта и вставить в код страницы элемент div с id="sb-cart-widget". Для отображения виджета необходимо вызвать функцию SB.init_cart(params). После того, как пользователь выберет способ доставки или пункт самовывоза – вызовется JS функция callback, которая передаётся в params.

В данной callback функции должен быть код, который сохранит выбранный способ доставки, его срок и стоимость в CMS в заказе.
<!-- BEGIN SALESBEAT CART-WIDGET -->
<script src="https://app.salesbeat.pro/static/widget/js/widget.js"></script>
<script src="https://app.salesbeat.pro/static/widget/js/cart_widget.js"></script>
<div id="sb-cart-widget"></div>
<script>
   SB.init_cart({
           token: 'your API token',
           city_by: 'city_code',
           city_code: '8f9faad4-ff93-471d-b0c0-c8e5c0162dee',
           products: [{price_to_pay: 1400, price_insurance: 1400, weight: 200, quantity: 1},
                      {price_to_pay: 3440, price_insurance: 3440, weight: 500, quantity: 2}],
           callback: function(data) {
                   console.log('Клиент выбрал доставку:', data)
           }
   })
</script>
<!-- END SALESBEAT CART-WIDGET -->
Поля аргумента (Object):
  • token – String, токен магазина (доступен в ЛК)
  • city_by – String, возможные варианты – 'city_code', 'ip':
    • при 'city_code' необходимо передать ФИАС-код города полем city_code,
    • при 'ip' город определится по IP-адрес
  • extra_data — опциональное произвольное текстовое поле, на которое можно настроить правила («Дополнительное поле» в интерфейсе правил)
  • products – Array, элементами которого являются параметры товаров:
    элементы массива представляют собой Object с ключами:
    • price_to_pay: Number, стоимость к оплате за товар (наложенный платеж), в руб.
    • price_insurance: Number, стоимость страховки (оценочная стоимость), в руб.
    • weight: Number, вес, в граммах
    • quantity: Number, количество этого товара в корзине (опционально — по умолчанию 1)
    • x: Number, длина, в см
    • y: Number, высота, в см
    • z: Number, ширина, в см
      пример:
      [{price_to_pay: 1400, price_insurance: 2222, weight: 5000, x: 40, y: 20, z: 50}, ...]
callback – функция, принимающая выбранный способ доставки:
принимает один аргумент – data:
  • при выборе доставки самовывозом имеет вид:
    {
    ⠀⠀delivery_days: "4", // Срок доставки (дней)
    ⠀⠀delivery_price: "446", // Стоимость доставки (рублей)
    ⠀⠀delivery_method_id: "pickpoint_pvz", // Код способа доставки
    ⠀⠀delivery_method_name: "Постоматы Pickpoint", // Название способа доставки
    ⠀⠀payments: массив с идентификаторами доступных способов оплаты
    ⠀⠀pvz_address: "Билимбаевская ул., д. 28", // Адрес пункта выдачи заказов
    ⠀⠀pvz_id: "6605-008", // Идентификатор пункта выдачи заказов (в рамках службы доставки)
    ⠀⠀city_code: "2763c110-cb8b-416a-9dac-ad28a55b4402", // ФИАС код выбранного города
    ⠀⠀short_name: "г", // Сокращенный тип населённого пункта – город, деревня и т.п.
    ⠀⠀ city_name: "Владимир", // Город
    ⠀⠀ region_name: "Владимирская обл" // Область и район
}
  • при курьерской или почтовой доставке:
    {
    ⠀⠀comment: "", // комментарий к адресу
    ⠀⠀delivery_days: "3",
    ⠀⠀delivery_price: "635",
    ⠀⠀delivery_method_id: "sdek_courier",
    ⠀⠀delivery_method_name: "СДЭК курьерская доставка",
    ⠀⠀payments: массив с идентификаторами доступных способов оплаты
    ⠀⠀flat: "111", // номер квартиры
    ⠀⠀house_block: "2", // корпус
    ⠀⠀house: "14", // номер дома
    ⠀⠀index: "114771 ", // почтовый индекс
    ⠀⠀city_code: "2763c110-cb8b-416a-9dac-ad28a55b4402" // ФИАС код выбранного города
}

Если виджет необходимо инициализировать, сразу выбрав в нём способ доставки и нужный пункт самовывоза или адрес (это бывает удобно при повторном оформлении заказа, чтобы форма выбора способа доставки была уже предзаполнена данными старого заказа), в init_cart можно передать второй параметр. Для доставки в пункт самовывоза указывается идентификатор нужного пункта самовывоза и идентификатор способа доставки:
<!-- BEGIN SALESBEAT CART-WIDGET -->
<script src="https://app.salesbeat.pro/static/widget/js/widget.js"></script>
<script src="https://app.salesbeat.pro/static/widget/js/cart_widget.js"></script>
<div id="sb-cart-widget"></div>
<script>
   SB.init_cart({
           token: 'your API token',
           city_by: 'city_code',
           city_code: '8f9faad4-ff93-471d-b0c0-c8e5c0162dee',
           products: [{price_to_pay: 1400, price_insurance: 1400, weight: 200, quantity: 1},
                      {price_to_pay: 3440, price_insurance: 3440, weight: 500, quantity: 2}],
           callback: function(data) {
                   console.log('Клиент выбрал доставку:', data)
           }
   },{
      pvz_id: '76111',  // идентификатор ПВЗ
      delivery_method_id: 'boxberry_pvz' // идентификатор способа доставки
   })
</script>
<!-- END SALESBEAT CART-WIDGET -->
Для курьерской доставки также указывается идентификатор способа доставки, но вместо идентификатора ПВЗ передаётся адрес:
<!-- BEGIN SALESBEAT CART-WIDGET -->
<script src="https://app.salesbeat.pro/static/widget/js/widget.js"></script>
<script src="https://app.salesbeat.pro/static/widget/js/cart_widget.js"></script>
<div id="sb-cart-widget"></div>
<script>
   SB.init_cart({
           token: 'your API token',
           city_by: 'city_code',
           city_code: '8f9faad4-ff93-471d-b0c0-c8e5c0162dee',
           products: [{price_to_pay: 1400, price_insurance: 1400, weight: 200, quantity: 1},
                      {price_to_pay: 3440, price_insurance: 3440, weight: 500, quantity: 2}],
           callback: function(data) {
                   console.log('Клиент выбрал доставку:', data)
           }
   },{
      delivery_method_id: 'boxberry_pvz', // идентификатор способа доставки
      street: "проспект Строителей", // улица
      house: "182",  // дом
      house_block: "",  // корпус
      flat: "",  // квартира
      index: "", // почтовый индекс
      comment: 'Привезите побыстрей!' // комментарий
   })
</script>
<!-- END SALESBEAT CART-WIDGET -->
Также в корзине можно организовать выбор курьерской доставки средствами CMS, а карту с выбором ПВЗ отобразить с помощью нашего виджета. Для этого нужно создать div с id="sb-cart-pvz-map" и вызвать функцию SB.show_pvz_map(params). После выбора пользователем способа доставки или пункта самовывоза – вызовется JS функция callback, которая передаётся в params.

Параметры params аналогичны параметрам функции SB.init_cart.
<!-- BEGIN SALESBEAT CART-PVZ-MAP -->
<script src="https://app.salesbeat.pro/static/widget/js/widget.js"></script>
<script src="https://app.salesbeat.pro/static/widget/js/cart_widget.js"></script>
<div id="sb-cart-pvz-map" class="sb-fullscreen-map"></div>
<script>
   SB.show_pvz_map({
           token: 'your API token',
           city_by: 'city_code',
           city_code: '8f9faad4-ff93-471d-b0c0-c8e5c0162dee',
           pvz_map_id: 'sb-cart-pvz-map',
           products: [{price_to_pay: 1400, price_insurance: 1400, weight: 200, quantity: 1},
                      {price_to_pay: 3440, price_insurance: 3440, weight: 500, quantity: 2}],
           callback: function(data) {
                   console.log('Клиент выбрал доставку:', data)
           }
   })
</script>
<!-- END SALESBEAT CART-PVZ-MAP -->
Интеграция отдельного виджета выбора города
В шапке сайта можно вставить отдельный виджет отображения текущего города с возможностью его смены.

Для этого нужно создать div с определённым id и вызвать функцию SB.init_city_choice(params).

Пример:
<!-- BEGIN SALESBEAT CITY-CHOICE-WIDGET -->
<div id="sb-header-city-choice-widget"></div>
<script>
   SB.init_city_choice({
           token: 'your API token',
           city_choice_element_id: 'sb-header-city-choice-widget',
           short_name_showed: true
   })
</script>
<!-- END SALESBEAT CITY-CHOICE-WIDGET-->
Поля объекта, передаваемого в метод:
  • token – String, токен магазина (доступен в ЛК)
  • city_choice_element_id – String, идентификатор id элемента, в который будет вставлен виджет
  • short_name_showed — Boolean, если true, то название населённого пункта отобразится с его типом (г. Москва), если false, то без (Москва)
JavaScript-события
Для облегчения интеграции можно воспользоваться событиями в JavaScript. На данный момент у нас генерятся следующие события:

  • sbWidgetRendered — генерируется в момент, когда виджет карточки товара отрисовался на странице
  • sbCartWidgetRendered — корзинный виджет отрисовался, в событие параметром event.detail передаётся выбранный по умолчанию способ доставки с полями как и в callback-е выбора способа доставки
  • sbCityChanged — пользователь изменил город, в событие параметром event.detail передаётся выбранный город – Object с ключами:
    • city_code — код города в ФИАС
    • short_name — сокращённое название населённого пункта (например, г, д и т.д.)
    • city_name — название населённого пункта
    • region_name — регион
  • sbDeliveryChanged — пользователь переключил службу доставки (ещё не нажав кнопки "Готово"), в событие параметром event.detail передаётся выбранный по умолчанию способ доставки с полями как и в callback-е выбора способа доставки
// Пример использования:
document.addEventListener('sbCartWidgetRendered', function(event) {
    console.log('Данные о доставке по умолчанию тут:', event.detail)
})

// С jQuery:
$(document).on('sbCityChanged', function(event) {
    console.log('Данные о новом городе тут:', event.originalEvent.detail)
})
Выгрузка заказов в службы доставки
У нас есть API, позволяющее выгружать заказы в информационные системы служб доставки. Вот его описание.
Воу-воу, сложно!
Есть вопросы? Напишите нам — hi@salesbeat.pro, мы оперативно поможем или, если необходимо, сами всё настроим на Вашем сайте.
API
Максимум гибкости и свободы
Конечно же, у нас есть простой REST API, позволяющий получать на сервере или напрямую на веб-странице всю информацию о службах доставки, сроках и стоимости доставки, пунктах самовывоза, созданных в Salesbeat правилах расчёта сроков и стоимости доставки.

Мы постарались сделать наше API максимально простым и удобным. Вся документация по API с примерами использования находится здесь:

PDF документация к Salesbeat API