Shiptor надёжная доставка посылок
Отследить посылку
Помощь
8 800 100-72-69

Интеграция

Центр помощи

Полный справочник доступных методов API Shiptor.

Ключевые замечания

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

Под габаритами товара в данном документе подразумеваются габариты коробки с товаром в разобранном виде.

Типы доставки

От склада Shiptor (стандартная) — доставка от склада Shiptor.

Типы отгрузки: самостоятельный привоз на склад Shiptor, курьеру Shiptor.
Фулфилмент: доступен.
География доставки: РФ, Беларусь, Казахстан.
Способы доставки: до двери, пункты самовывоза, постаматы, отделения почты.
Транспортные компании: максимально возможный выбор (полный перечень на сайте Shiptor) в зависимости от выбранного склада.

Сквозная — прямой тип доставки, минуя склад Shiptor.

Типы отгрузки: самостоятельный привоз на принимающий пункт самовывоза транспортной компании, курьеру транспортной компании.
Фулфилмент: недоступен.
География доставки: из регионов по РФ.
Способы доставки: до двери, пункты самовывоза.
Транспортные компании: ограниченный выбор (полный перечень на сайте Shiptor).

Экспорт — доставка от сортировочного склада Shiptor в Москве.

Типы отгрузки: самостоятельный привоз на склад Shiptor в Москве, курьеру Shiptor.
Фулфилмент: доступен.
География доставки: от Москвы в страны, не входящие в ТС.
Способы доставки: до двери.
Транспортные компании: ограниченный выбор (информация на сайте Shiptor).

Особенности политики страхования

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

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

Визуализация интерфейсов админпанели интернет-магазина, которые связаны с модулем/интеграцией с Shiptor, а также клиентских интерфейсов (того, что видят покупатели магазина). Скачать файл с прототипами и комментариями к ним.

Изменяемость методов доставки

По сути, методы доставки — тарифы, доступные для конкретного клиента в конкретный момент. Они могут быть изменены, поэтому постоянно использовать один раз сохраненную таблицу тарифов (методов) нельзя.
О том, как с ними работать, читайте в пункте «Получение доступных тарифов (методов) доставки для клиента».

Публичные и непубличные методы API

Методы API, описанные в документации, делятся на публичные (Public) и закрытые (Shipping и Private).

Для получения данных с открытой части сервиса Shiptor используются публичные методы API. К ним можно обращаться напрямую с front-end сайта (запросы из JS, AJAX и т.п.). Основное предназначение этих функций — справочный расчет стоимости доставки в интерфейсе сайта клиента по общим тарифам, представленным на сайте Shiptor, в т.ч. с учетом актуальных маркетинговых акций. Для них не требуется API-ключа и для запроса используется адрес https://api.shiptor.ru/public/v1.

Для обмена данными с Личным Кабинетом пользователя в Shiptor используются закрытые методы API, доступные только при отправлении запроса со стороны сервера клиента (server-side). Эти методы позволяют не только получать информацию по индивидуально настроенным методам и тарифам клиента, но и формировать запросы на действия в ЛК пользователя. В качестве адреса таких запросов к API используйте https://api.shiptor.ru/shipping/v1 и секретный API-ключ клиента («API токен для интеграции https://api.shiptor.ru/shipping/v1» в личном кабинете пользователя в Shiptor).

Если нужно получить данные из ЛК Shiptor с front-end, можно использовать публичные методы АPI, но также с использованием соответствующего API-ключа («API токен для https://api.shiptor.ru/public/v1» в личном кабинете пользователя в Shiptor).

Ниже идет описание, полностью посвященное работе модуля или интеграции на стороне сервера (server-side) через закрытые методы API. Помимо этого, оно поможет лучше понять принцип действия открытых методов API при реализации или доработке виджетов или другого функционала на front-end клиента.

1. Оформление заказа — расчет доставки. (Публичная сторона сайта)

1.1 Выбор населённого пункта

Вариант 1: Получение населенного пункта в отдельном поле по части названия: suggestSettlement

Пользователь сайта начинает вводить название своего населенного пункта (далее НП), и система показывает ему предложения названий, указывая области и регионы, к которым относятся выводимые НП.

Свойство country_code в запросе к API позволяет получать подсказки НП по одной из трех стран: Россия, Беларусь и Казахстан. Если она не указана, в запросе вернутся подсказки по трем странам с приоритетом выдачи на Россию. Ограничение в выдаче — 100 подсказок.

Для последующих расчетов доставки и передачи совершенных заказов используется КЛАДР-код населенного пункта, возвращаемый этим методом. Он чаще используется, когда на стороне CMS уже есть определенный набор населенных пунктов со своими внутренними кодами. Чтобы получить правильный КЛАДР-код, необходимо установить взаимосвязи между выбранным покупателем населённым пунктом и его аналогом в API Shiptor.
Если используется система кэширования или любой другой способ хранения КЛАДР-кодов на стороне CMS, необходимо предусмотреть возможность периодического сброса сохраненных КЛАДР-кодов, поскольку они регулярно обновляются на стороне API Shiptor. Допускается использование внешнего сервиса (например, самого КЛАДР) для получения кодов от него, минуя этот метод. При этом важно не забывать о том, что с некоторыми системами у API Shiptor есть расхождения в части соответствия кодов для ряда населённых пунктов.

Количество символов передаваемого в Shiptor КЛАДР-кода должно быть равно 11. Если КЛАДР-код, хранимый на сайте, состоит более чем из 11 символов, то при передаче значения в Shiptor необходимо обрезать лишние символы, начиная с конца.

КЛАДР-код представляет из себя число с некоторым количеством значащих цифр иногда с ведущим нулем, поэтому необходимо исключать его преобразования к целому типу и использовать для хранения и манипуляций тип строковое.

Вариант 2. Ограничение выбора НП по областям, выбор НП из списка: getSettlements

Другой вариант выбора, когда получается справочник для страны, из которого можно последовательно выбрать регион, область и нужный НП. Этот способ подойдет для CMS без встроенных населенных пунктов или же для новых проектов, на которых можно полностью заменить встроенные населенные пункты на получаемые от API Shiptor. В API хранятся все типы местоположений, начиная от страны и заканчивая поселками. Общее количество единиц исчисляется десятками тысяч, поэтому для последовательной выборки используется постраничная навигация. Возможна фильтрация выборки по типу и КЛАДР-коду прямого родителя.

1.2 Расчет / выбор доставки для корзины товаров

Получение данных:

Для расчета доставки по России, Казахстану и Беларуси используется метод calculateShipping. Оперируя параметром stock, Вы запрашиваете методы доставки от склада Shiptor или сквозные.

Для расчета доставки на экспорт используется метод calculateShippingInternational.

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

Доставка рассчитывается в соответствии со значениями следующих параметров в запросе к API:

оценочная стоимость отправления (declared_cost);
сумма наложенного платежа (cod);
габариты отправления (height, length, width);
вес отправления (weight);
населенный пункт получателя (kladr_id);
населенный пункт отправителя/склада Shiptor (kladr_id_from).

Подробнее о взаимодействии наложенного платежа и оценочной стоимости, а также их допустимых значениях см. «Наложенный платеж и объявленная ценность (страховка)».

1.3 Выбор ПВЗ для точек самовывоза

Получение данных

Доступные точки самовывоза рассчитываются на основании следующих параметров:

конкретный метод доставки или служба доставки;
вес отправления;
габариты отправления;
факт наложенного платежа;
факт оплаты наложенного платежа картой;
населенный пункт получателя.

Чтобы получить ПВЗ, доступные в указанном населенном пункте, запросите метод getDeliveryPoints. Полученные точки отобразите на карте, чтобы пользователь мог выбрать необходимый вариант. Лучше всего карту ПВЗ демонстрировать сразу при выборе пункта доставки со свойством «category»: «delivery-point». При запросе укажите тип оплаты, выбранной пользователем, габариты и вес заказа, чтобы получить список ПВЗ, которые соответствуют заявленным требованиям.

Если получить на данном этапе информацию по выбранному типу оплаты невозможно, то при обработке ответа следует выводить информацию по принимаемым платежам в списке (сбоку от карты) и во всплывающем окне (при наведении или щелчке по маркеру ПВЗ на карте).

Обработка данных

Карта обычно реализуется при помощи Яндекс.Карт с типичными маркерами точек. Основные поля, которые необходимо отображать для ПВЗ:

cod: true - разрешена оплата наличными;
card: true - разрешена оплата картой или иным безналичным способом;
work_schedule - время работы;
trip_description - подробная информация, как найти ПВЗ.

На карте желательны фильтры (чекбоксы), меняющие список отображаемых ПВЗ:

«Принимает наличные»,
«Принимает карты».

Если доставка подразумевает самовывоз, нельзя разрешать пользователю переходить к следующим этапам оформления заказа без выбора ПВЗ!

Необходимо предупреждать возникновение конфликтных ситуаций, когда платежная система не поддерживается в ПВЗ. Для этого воспользуйтесь следующими способами для схемы:

Выбор ПВЗ => Оплата — периодическое отключение способов оплаты, недоступных для актуального ПВЗ.
Выбор Оплата => ПВЗ — отключение на карте и в списке точек с ПВЗ, которые не принимают способ оплаты, выбранный ранее.

1.4 Особенности работы со способами оплаты наложенным платежом

Наложенный платеж может быть принят в двух вариантах:

наличными,
картой.

При формировании запросов и обработке данных стоит учитывать, что:

Почта не принимает наложенный платеж картой («category»: «post-office»);
не все курьеры и самовывоз могут принять наложенный платеж картой и/или наличными. Необходимо оперировать свойствами cod (сумма наложенного платежа) при запросе CalculateShipping или свойствами cod (наличные) и card (терминал для карт) при запросе getDeliveryPoints. В противном случае фильтровать ответ.

1.5 Указание времени доставки для курьерской доставки Shiptor

Для курьера Shiptor (name: Shiptor курьер, category: to-door) возможен выбор даты и времени доставки (в выходные и праздничные дни желаемое время игнорируется).
Для курьера Shiptor (name: Shiptor курьер за МКАД, category: to-door) возможен выбор только даты доставки.
По умолчанию доставляется на следующий день после фактического получения отправления в интервале с 10:00 до 18:00.

Получение данных

Список доступных интервалов запрашивается методом getDeliveryTime.
Список выходных и праздничных дней запрашивается через публичный метод Public-getDaysOff.

Обработка данных

«Предлагать клиенту выбрать дату доставки курьером Shiptor»;
«Предлагать клиенту выбрать диапазон времени доставки курьером Shiptor».

Данный функционал желательно оформлять как чекбоксы в админ-панели модуля/интеграции. Так у пользователя будет возможность настраивать их по своему усмотрению.

На публичной части при выводе формы для выбора временного интервала следует предусмотреть ее скрытие в случае доставки на выходных или в праздничный день. После выбора клиентом временного диапазона надо будет сохранить его ID или строковое значение для последующей передачи данных вместе с заказом.

1.6 Отображение и коррекция ожидаемых сроков доставки

В ответе метода calculateShipping возвращается не только стоимость каждого способа доставки, но и ожидаемые сроки в рабочих днях.

Эти сроки необходимо выводить покупателю либо в варианте «рабочих дней», либо с преобразованием в календарные дни с учетом праздников и выходных. В админ-панели необходимо предусмотреть настройки по отображению и скрытию сроков доставки, а также возможность их увеличения.

1.7 Требование заполнения полей, необходимых для курьерской доставки

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

Карточка товара — виджет вывода стоимости доставки

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

Для старта виджета используются данные по НП получателя и отправителя, если речь идёт о сквозной доставке. Они берутся из настроек административной панели. Опционально предусмотреть возможности:

определения населенного пункта получателя по IP;
ручного указания населенного пункта получателя.

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

Если виджет реализуется в виде всплывающего окна или большого фрейма, необходимо предусмотреть возможность его открытия (старта) по кнопке и последующего закрытия. Это позволит избежать перекрытия основной информации по товару.

2. Общие настройки модуля/интеграции (админ-панель сайта)

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

Отображение данных о ДxШxВ упаковочной тары товара в системе клиента. Рекомендуем ориентироваться на габариты товара в разобранном/упакованном виде, т.к. ДxШxВ уже собранных товаров может в определенных случаях сильно исказить результат расчета стоимости доставки.
Отображение срока доставки, возвращаемого при запросе расчета доступных методов [вкл по умолчанию].
Добавление указанного в поле количество дней к срокам доставки, отображаемым на сайте [не прибавлять по умолчанию].
Автоматическая передача в Shiptor заказов, создаваемых клиентами без участия оператора, и условия для ее выполнения [выкл по умолчанию]. Подробнее в 3.1 Передача заказа в Shiptor. Рекомендуем реализовать очередь передачи для снижения нагрузки на сервера.
Склад Shiptor для стандартного типа заказо.
В качестве общей настройки или отдельно в каждом профиле предусмотреть установку для передаваемого в Shiptor заказа флаг «Собирать со склада». Выбранная настройка регулирует тип посылки для клиентов с подключенной услугой фулфилмента (сборка на складе Shiptor или на складе клиента) [по умолчанию вкл].

Ведение полного лога всех запросов к API и ответов сервера с указанием времени и дополнительной информации о работе модуля [по умолчанию выкл]. Результат сохраняется в отдельный файл и может быть скачан. Также присутствует кнопка или ссылка «Очистить лог».
Автоматическое получение внутренних статусов заказов от Shiptor без участия оператора. При отключенной опции процесс регулируется в ручном режиме через административную панель. Интервал опроса позволит минимизировать нагрузку на сервера [выкл по умолчанию].
Автоматическое получение товарных остатков от Shiptor без участия оператора [по умолчанию выкл]. Интервал опроса позволит минимизировать нагрузку на сервера. При отключённой опции процесс регулируется в ручном режиме через административную панель. Актуально только для клиентов с подключенной услугой фулфилмента.
Синхронизация номенклатуры через выбор поля, соответствующего уникальному shopArticle в Shiptorе («Артикул товара в магазине») [некое уникальное поле в ИМ по умолчанию]. Реализуется выпадающим списком полей из карточки товара или скрытым уникальным id товара. Возможно комбинирование со свойствами товара, которое даст уникальный набор идентификации конкретной вариации товара . Значение этого уникального поля будет использоваться в качестве shopArticle в методах AddProduct, AddPackage, GetProduct и пр.
Если в CMS присутствует своя система статусов заказов, надо предусмотреть возможность установления соответствий между статусами Shiptor и встроенными статусами CMS, чтобы система могла автоматически менять внутренние статусы при изменении статусов в Shiptor. Желательно делать этот функционал на отдельной вкладке или странице, т.к. их список хоть и ограничен, но может быть достаточно объемным [без соответствий по умолчанию].
Округление итоговой стоимости доставки до целых рублей (1 234.56 → 1 235.00) или до десятков рублей (1 234.56 → 1 230.00) [выкл по умолчанию]. Округление производится стандартной функцией математического округления.

Отдельно нужны следующие настройки:

Поля для ввода параметров усредненной посылки по умолчанию: длина [10см], ширина [20 см], глубина [30 см], вес [3 кг]
Поля для ввода параметров усредненного товара по умолчанию: длина [10см], ширина [10 см], глубина [20 см], вес [1 кг]
Сопоставление при необходимости полей из системы, используемой клиентом, и полей, нужных для оперирования при расчетах и передаче заказа в Shiptor в модуле/интеграции: адрес отправителя, адрес получателя, код ПВЗ, и т.д., включая раздельные поля для юридических и физических лиц.
Выгрузка номенклатуры по кнопке в Shiptor или загрузка уже созданной из Shiptor. Подробнее в пункте Список товаров и просмотр товара.

2.1 Создание и настройка профилей доставок. Настройки методов/тарифов и ограничений для них

После получения/установки/активации модуля/интеграции клиент там же в админ-панели должен создать профили доставки (и в дальнейшем иметь возможность их редактировать), которые будут формироваться из доступных в данный момент методов доставки, предоставляемых API Shiptor.

Каждый созданный пользователем профиль позволяет клиенту многократно использовать одни и те же методы доставки с разными ограничениями, параметрами и настройками (например, DPD Курьер с разбивкой по регионам и с отдельными настройками для каждого из них).

Профиль должен не только включать один или несколько доступных методов доставки, но и содержать ряд дополнительных настроек, таких как:

Чекбокс включения или отключения вывода данного профиля на странице оформления заказа [включено по умолчанию].
Поле для ввода индивидуального названия профиля, которое будет отображаться на странице оформления заказа и в админ-панели. Пользователи могут переименовывать стандартные названия методов в что-то совершенно свое, особенно в случае использования "дефолтной"/приоритетной доставки или собственных доставок Shiptor)
Интерфейс выбора картинки логотипа при отображении профиля на на странице оформления заказа и опционально в админ-панели
Чекбокс, который включает отображение срока доставки [значение из общих настроек по умолчанию]. Переопределяет общие настройки.
Поле для ввода количества дней, прибавляемых к сроку доставки [значение из общих настроек по умолчанию]. Переопределяет общие настройки.
Поле для ввода или селект выбора географических ограничений (например, служба DPD Самовывоз, которая применяется только для Московской области без Москвы, или только для Москвы, или для всей РФ без Москвы и области) [не настроено по умолчанию].
Поле для управления сортировкой профиля. Влияет на порядок отображения доступных и включенных профилей при оформлении заказа. Например: профили с наименьшим значением сортировки отображаются выше остальных, а профили с одинаковым значением сортируются внутри группы по наименованию. Сортировку можно также реализовать не в виде ручного задания значений, а в виде перемещения профилей мышью в админ-панели.
Поле для ввода фиксированной стоимости доставки (например, 400 рублей за любую доставку в рамках данного профиля и его ограничений) [не настроено по умолчанию].
Поле для настройки бесплатной доставки [не настроено по умолчанию]. Она становится бесплатной в профиле при сумме заказа больше указанного значения. Опционально: доставка в профиле становится бесплатной при весе заказа больше указанного значения
Поля для ввода диапазона цен заказа, в рамках которого данный профиль будет доступен (например, для заказов в диапазоне 1000-4999 руб) [не настроено по умолчанию].
Поля для ввода диапазона веса заказа, в рамках которого данный профиль будет доступен (например, для заказов в диапазоне 5-9.999 кг) [не настроено по умолчанию].
Селект с выбором типа плательщика (физ. лицо, юр. лицо или оба), который может видеть этот профиль [оба типа доступны по умолчанию].
Поле наценки (в процентах или в рублях) на стоимость доставки [не настроено по умолчанию]. Опционально: на стоимость заказа и на стоимость корзины.
Информационное поле, отображающее уникальное название метода доставки от Shiptor, выраженное в семействе тарифов [заполняется автоматически в зависимости от включенных в профиль методов]. Например, название профиля «Курьерская доставка по Москве», а связан он с методом из семейства тарифов «DPD parcel courier».
Склад Shiptor [значение из общих настроек по умолчанию].
Чекбокс включения и выключения страхования предоплаченных заказов (заказы с наложенным платежом страхуются всегда) [включено по умолчанию]. Позволяет указывать оценочную стоимость заказа в размере суммы товаров в корзине. В противном случае минимальная оценочная стоимость будет равна 10 руб.
Передавача заказов в Shiptor автоматически или только в ручном режиме позже [вручную][опционально].
Специфические настройки профиля сквозной доставки (2.3 Специфические настройки профилей сквозной доставки).

При помощи профилей реализуются даже такие схемы, как сеть региональных складов клиента (интернет-магазина) по РФ, каждый из которых обслуживает свой регион и использует склад Shiptor в Москве (фулфилмент) со своими вариантами доставок внутри Москвы. Именно профили доставки определяют, какие типы доставок включены и применимы в каждом конкретном случае для покупателя интернет-магазина и указанного им населенного пункта.

2.2 Получение возможных методов (тарифов) доставки для пользователя интеграции

У каждого зарегистрированного клиента Shiptor есть свой Личный кабинет с включенными в нем методами (тарифами) доставки. Их набор и тарифная сетка может быть индивидуально настроена администратором Shiptor.

Для получения всех доступных методов доставки конкретного клиента в текущий момент времени необходимо использовать запрос getShippingMethods.

Описание характеристик методов доставки, возвращаемых API Shiptor:

Уникальный идентификатор метода

Поскольку тарифы доставок могут быть изменены в любой момент (например, клиент будет переведен на персональные тарифы), нельзя привязываться к перечню ранее полученных ID методов доставки для клиента. При изменении тарифов они станут частично или полностью недоступными. Для определения метода доставки, к которому привязываются выбранные клиентом настройки профиля, надо использовать поле группы метода (семейства тарифов): group в ответе на запросы к getShippingMethods и calculateShipping.

Пример:
Клиент в модуле создал профиль доставки с DPD Курьер, сделал различные настройки.
Через некоторое время тарифы поменялись.
Чтобы провести миграцию настроек на новый тариф, нам надо определить какая служба доставки теперь соответствует DPD Курьер.
Для этого мы из новых доступным методов доставки выбираем метод с той же группой, что была ранее у DPD Курьер. И продолжаем работать с ней с теми же настройками, что и раньше.

Способы и типы доставок свойства category

Ориентируясь на значение в свойстве category, возвращаемом при запросах getShippingMethods и calculateShipping, можно определить тип доставки, способ получения отправления и способ отгрузки (для сквозных доставок).

Сквозные методы (регион-регион)

Пункт самовывоза — Пункт самовывоза: «delivery-point-to-delivery-point»
Дверь — Пункт самовывоза: «door-to-delivery-point»
Дверь — Дверь: «door-to-door»
Пункт самовывоза — Дверь: «delivery-point-to-door»

От склада Shiptor в Москве, в том числе и экспорт

В пункты самовывоза, постаматы: «delivery-point»
До двери: «to-door»
В отделение почты РФ: «post-office»

Географические ограничения для профиля доставки

Получая справочник стран, регионов, районов и населенных пунктов, можно предлагать пользователю установить для них нужные ему ограничения. Метод для запроса справочника: getSettlements.

Один из возможных вариантов реализации ограничения
В момент отображения блока расчета и выбора доставки в оформлении заказа сравнивать указанные покупателем Населенный Пункт по базовой части КЛАДР и смотреть, в какой регион, район или город он входит. Таким образом можно выбрать Москву, Московскую область и остальную Россию как имеющие совершенно разные настройки доставки.

Как проверять принадлежность населенного пункта к области
КЛАДР Москвы начинается с 77, области — с 50, всё остальное — РФ.
Более подробную информацию можно найти на сайте kladr-rf.ru или в базе ФИАС.

Сортировка профилей доставки по приоритету

Приоритетность профилей доставки позволяет установить сортировку выводимых видов доставки при оформлении заказа и использовать «доставку по умолчанию», то есть самую приоритетную в данном конкретном случае.

Профиль доставки по умолчанию:

В большинстве платформ предусмотрена возможность автоматического выбора первого по сортировке профиля доставки, отображаемого при оформлении заказа.

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

2.3 Специфические настройки профилей сквозной доставки

Пояснения по определению сквозных методов доставки читайте в п. «2.2 Получение доступных тарифов (методов) доставки для клиента».

Если выбран сквозной метод доставки, то в профиле автоматически должны появиться следующие настройки:

Поле для ввода или селект выбора населенного пункта отправителя. Для подсказок пользователю можно использовать метод suggestSettlement. Главное — получать и хранить КЛАДР-код отправителя для дальнейшего использования его в запросах на расчет и создание посылки.
Поля для ввода контактных данных отправителя: телефон, ФИО, email. Также можно предусмотреть использование контактной информации из настроек платформы или задать общую настройку для профилей [из настроек магазина по умолчанию].
Селект или карта для выбора ПВЗ отгрузки — специфично только для методов с category delivery-point-to-delivery-point и/или delivery-point-to-door [первый ID по городу отправителя]. В профилях, которые не включают указанные category методов сквозной доставки, данную настройку отображать не нужно. Для получения вариантов ПВЗ используют метод getDeliveriPoints с флагом self_pick_up
Поле для задания отсрочки даты отгрузки в указанном количестве дней [завтрашний день по умолчанию]. Рабочие дни запрашиваются методом getDaysOff.
Селект выбора временного интервала забора [не выбрано по умолчанию]. Запрашивается методом getPickUpTime. Может быть удален из API Shiptor — перед выполнением уточнить возможность такой опции.
Чекбокс подтверждения отгрузки в сквозную доставку методом confirmShipment [не подтверждать по умолчанию]. Когда заказ будет передан в Shiptor, то он автоматически будет подтвержден, за него спишутся средства и заявка будет передана курьеру или в ПВЗ.

Для методов доставки «От склада» или «Экспорт» эти настройки не нужны.

2.4 Настройка методов оплаты, указание наложенного платежа и оплаты наличными

Shiptor предлагает два способа взятия наложенного платежа :

оплата наличными при получении;
оплата картой при получении.

Их доступность зависит от конкретного метода доставки.

Чтобы модуль/интеграция понимал, какие методы оплаты могут быть наложенным платежом и в каком случае он будет по карте, надо в админ-панели модуля/интеграции выводить список доступных в платформе способов оплаты с возможностью управления:

какие из типов оплат в системе являются наложенным платежом;
какие из выбранных в качестве наложенного платежа типов оплат являются наличными, а какие картой.

Если в системе нет доступных способов оплаты для определения их наложенным платежом, то такие способы оплаты необходимо создать.
После этого модуль/интеграция сможет корректно рассчитывать стоимость и возможность доставки для выбранного метода оплаты при оформлении или редактировании заказа.

Примечание о доступности наложенного платежа:

Почта России не может принять наложенный платеж картой («category»: «post-office»).
Не все курьеры («category»: «to-door») и самовывоз («category»: «delivery-point») могут принять наложенный платеж как картой, так и наличными. Необходимо оперировать свойством cod (сумма наложенного платежа) при запросе CalculateShipping, а также свойствами cod (наличные) и card (терминал для карт) при запросе getDeliveryPoints. В противном случае фильтровать ответ.

Особенности работы работы с экспортом

Расчет доставки за рубеж, исключая Беларусь и Казахстан, как и добавление таких посылок в Shiptor отличаются рядом особенностями. К ним относятся:

Для получения возможных методов и стоимости используйте метод calculateShippingInternational.
Возможна ситуация, что будет доступен только 1 метод доставки.
Наложенный платеж при экспорте невозможен, соответственно, параметр cod не используется. Стоимость заказа при расчете передается в параметре declared_cost.
Учет страхования происходит с помощью параметра insurance.
При написании интеграции правила страхования уточняйте у менеджера Shiptor по экспорту или на сайте.
На момент написания инструкции поля «город получателя» в функции нет. Он не нужен, т.к. на расчет влияет только выбранная страна.
На стороне клиента нужно предусмотреть добавление пошлины в доставку при превышении порога суммы товаров или описать в документации к интеграции необходимость использования наценки в профилях экспорта. Это делается путём ограничения их отображения по сумме корзины.
API самостоятельно прибавляет пошлину и НДС к стоимости доставки.
Правила применения пошлины и ее сумма описаны в соответствующем разделе ЛК Shiptor.

Добавление посылки на экспорт

Для передачи экспортного отправления в Shiptor используйте метод addPackage__Export.
Включать в посылку услугу доставки не нужно, т.к. нет наложенного платежа и распечатываемого чека.
Обязательно декларируется товар с ценой, т.к. есть пошлина за таможенное оформление груза при превышении суммы вложения.
Названия товаров обязательно должны быть на английском!

Редактирование посылки на экспорт

Для редактирования экспортного отправления в Shiptor используйте метод editPackage__Export.

2.5 Редактирование/создание заказа в админ-панели

Интерфейс редактора в админ-панели должен соответствовать по функциональности странице оформления заказа. Минимальные требования к редактору по опциям:

Изменить контактные данные получателя.
Изменить страну доставки. Требуется перерасчет стоимости и возможности доставки.
Изменить населенный пункт доставки. Требуется перерасчет стоимости и возможности доставки.
Изменить набор товаров в корзине. Требуется перерасчет стоимости и возможности доставки.
Изменить профиль доставки.
Изменить ПВЗ в случае доставки самовывозом.
Изменить временной интервал для Shiptor курьер.
Изменить отложенную дату отправки для Shiptor курьер.
Поставить/снять флаг «Собирать со склада».
Изменить способ оплаты. Требуется перерасчет стоимости и возможности доставки.
Применить/убрать купон/маркетинговую акцию. Требуется перерасчет стоимости и возможности доставки в случае изменения входных параметров.

Дополнительно можно расширить редактор следующими опциями:

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

Редактор должен позволять изменять заказ до передачи в Shiptor и после.
Клиенту необходимо предоставить возможность выбора места сохранения изменений: магазин, Shiptor или оба варианта.

Обратите внимание, что редактирование заказа после передачи и сохранения в Shiptor возможно только в следующих случаях:

статус посылки NEW и в history нет «назначен бин» (не ушла на сборку для фулфилмента);
статус посылки checking-declaration и в history нет «назначен бин» (не ушла на сборку для фулфилмента).

Исходя из этого необходимо на стороне клиента отслеживать доступность редактирования переданных заказов и, если это невозможно, явно сообщать об этом, например информером:
«Редактирование заказа невозможно, так как статус заказа в Shiptor xxxxx. Пожалуйста, свяжитесь со своим менеджером в Shiptor для дополнительной консультации по данному вопросу».

Соответственно, желательно по заказу явно отображать информацию о:

текущем статусе заказа в Shiptor;
истории операций с посылкой в Shiptor (массив history в ответе на getPackage);
истории ошибок с посылкой (массив problems в ответе на getPackage).

Методы изменения заказов в Shiptor

Стандартная в пределах СНГ editPackage.
Экспортная editPackage__Export.

Практически полностью повторяют структуру AddPackage, но добавляется ID изменяемого заказа в Shiptor.

2.6 Список заказов и просмотр заказа

В общем списке заказов, который отображает заказы, оформленные на методы Shiptor, должен присутствовать минимальный набор следующих полей:

Номер заказа в системе. Поле невыключаемое.
Номер заказа в Shiptor. Поле невыключаемое. Можно выводить RP от Shiptor, но в редких случаях RP могут отличаться от ID заказа в Shiptor. Необходимо это учитывать.
Номер отгрузки для методов сквозной доставки. Отображается в свойстве shipment при ответе на getPackages.
Адрес доставки: город/улица/пвз или иное. Поле можно выключить.
Покупатель: ФИО/телефон/e-mail или иное. Поле можно выключить.
Метод выбранной доставки или ее профиль. Информация передаётся в строковом формате: «DPD самовывоз», «Shiptor Курьер» и т.д. Поле можно выключить.
Статус заказа в системе. Поле невыключаемое.
Статус заказа в Shiptor. Можно не отображать, если в системе есть ассоциация на "родные" статусы для нее. Подробнее об этом читайте в 2.1 Создание и настройка профилей доставок.
Дата оформления заказа. Поле невыключаемое.
Финансовая информация по заказу: способ оплаты, сумма заказа, сумма наложенного платежа, стоимость доставки или иное. Поле можно выключить.
Трек-номер посылки в курьерской службе. Поле можно выключить. Трек-номер присваивается после передачи в курьерскую службу, т.е. при получении статуса «sent».

Невыключаемые поля отображаются в таблице всегда, остальные можно скрыть через фильтр колонок. Важно для списка заказов предусмотреть возможность подбора по данным, введенным пользователем. Минимальная воронка на подбор должна опираться на невыключаемые поля.

Также можно расширить выводимую информацию, например следующими полями:

Статус посылки в курьерской службе. Статусы курьерской службы отображаются в разделе Checkpoints метода getPackages после получения заказом статуса sent.
Рассчитанная стоимость доставки на момент оформления/редактирования заказа.
Временной интервал доставки для метода Shiptor Курьер.
Отложенная дата отправки для метода Shiptor Курьер.
Дата забора для методов сквозной доставки.
Временной интервал забора для методов сквозной доставки.

Подробнее о получении статусов в соответствующем пункте раздела Back-end.

Также в интерфейс управления списком должны быть добавлены следующие кнопки пакетных действий:

«Передать выбранные заказы в Shiptor». При этом заказы должны иметь возможность отмечаться чекбоксом.
«Обновить информацию по заказам Shiptor». Получить статусы, трек-номера транспортной компании (ТК) и пр.
«Удалить выбранные заказы в Shiptor». Доступно только по заказам, оформленным с флагом is_fulfilment, у клиентов с подключенной услугой фулфилмента через метод removePackage. Обратите внимание, что удаление заказа после передачи и сохранении в Shiptor возможно только в следующих случаях:
- Статус посылки NEW и в history нет «назначен бин» (не ушла на сборку для фулфилмента).
- Статус посылки checking-declaration и в history нет «назначен бин» (не ушла на сборку для фулфилмента). Поэтому необходимо на стороне клиента отслеживать доступность редактирования переданных заказов и, если это невозможно, явно сообщать об этом, например информером: «Удаление заказа невозможно, так как статус заказа в Shiptor xxxxx. Пожалуйста, свяжитесь со своим менеджером в Shiptor для дополнительной консультации по данному вопросу».

Над общим списком заказов должна выводиться информация о статусе передачи заказов в Shiptor, обновлении информации по ним, а также ссылка на лог обмена данными или текст, поясняющий, где его искать в навигации сайта/модуля/интеграции.

2.7 Список товаров и просмотр товара

Необходимо выводить товарные остатки со склада в:

списке товаров в админ-панели;
карточке товара в админ-панели.

Актуально в том случае, если такая опция включена в админ-панели и у клиента подключена услуга фулфилмента в Shiptor. При проверке остатков на фулфилменте желательно иметь в списке товаров/карточке товара отдельное поле «Shiptor», чтобы там актуализировались остатки на складе Shiptor и не смешивались с остатками в магазине. Если магазин поддерживает несколько складов и записи каждого из них выделяются под синхронизацию с Shiptor, это поле не нужно.

Метод получения товарных остатков getProducts. При указании ShopArticle вернутся данные по конкретному товару, без него — по всем.
Поясняющий скриншот:

Отдельно нужен функционал синхронизации номенклатуры в каждом из направлений:

Загрузка номенклатуры из магазина в ЛК Shiptor. Можно добавить опцию, которая позволяет выбрать отельные товары или сразу все. Для загрузки используется метод addProduct, где shopArticle - уникальный для магазина идентификатор товара. При получении ошибки InvalidIssetShopArticle рекомендуем выводить пользователю сообщение о позиции номенклатуры в магазине, совпадающей по идентификатору с имеющейся номенклатурой ЛК. В этом случае номенклатура не будет добавлена в Shiptor.
Обновление номенклатуры, переданной в Shiptor ранее. Для этого используется метод editProduct, где shopArticle - уникальный для магазина идентификатор товара, ранее переданный в Shiptor.
Выгрузка номенклатуры из Shiptor и сохранение в магазине. Значение из shopArticle используется для заполнения поля товара в магазине для соответствия уникальному идентификатору в Shiptor. При нахождении дубля в магазине рекомендуем предлагать пользователю Обновить или Отказаться от добавления позиции со ссылкой на дубль. Метод выгрузки всей номенклатуры — getProducts без указания shopArticle в запросе.

3. Back-end

3.1 Передача заказа в Shiptor

Заказ может передаваться в Shiptor в автоматическом или ручном режиме в зависимости от общих настроек в админ-панели или профилях доставки.
Для автоматической передачи необходимо предусмотреть разрешающие условия. Например, получение полной оплаты для предоплаченных заказов, наличие конкретного статуса системы для заказов с наложенным платежом или комбинацию условий.
Передача заказа в Shiptor производится не только с декларированием товаров из номенклатуры, ранее переданной в Shiptor, но и с декларированием услуг, включенных в заказ из ранее переданных или заведенных в личном кабинете Shiptor.
Перед передачей заказа надо проверить наличие в номенклатуре в ЛК Shiptor товаров и услуг, затронутых заказом, завести в номенклатуре Shiptor недостающие и только затем создать посылку.

Для уменьшения числа предварительных запросов перед передачей заказа в Shiptor можно у товаров на сайте клиента (в модуле или интеграции) завести флаг «номенклатура товара заведена в Shiptor» и «номенклатура услуги заведена в Shiptor». При загрузке номенклатуры отмечается соответствующее поле. Таким образом мы убираем необходимость предварительной проверки через запрос(ы) к Shiptor, выполняя его «локально» в базе клиента.

Если в модуле/интеграции дополнительное поле не заведено, то непосредственно перед сохранением заказа потребуется выполнять запросы на:

Добавление товара в номенклатуру методом AddProduct. В случае повторного добавления вернется ошибка.
Добавление услуги в номенклатуру методом AddService. В случае повторного добавления вернется ошибка. Стоимость услуги обязательно 0 (ноль).

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

Добавление посылки в Shiptor

Для передачи заказов используются следующие методы:

От склада Shiptor/Сберлогистика

Один заказ addPackage.
Пакет заказов addPackagesStandard.
Пакет заказов с одновременным добавлением в забор курьером Shiptor addPackagesStandardPickUp.

Сквозная доставка

Пакет заказов с отгрузкой курьеру addPackagesCourier.
Пакет заказов с отгрузкой в ПВЗ addPackagesDeliveryPoint.

!Мы рекомендуем при передаче сквозных отправлений группировать их по type + courier и соответственно передавать в виде пакета заказов (Packages), чтобы у службы доставки не было несколько заявок по одному отправлению в каждой.

Для автоматической передачи заказов дату отгрузки, интервал и флаг подтверждения брать из настроек профилей. Для ручной передачи можно выводить всплывающее окно с возможностью перевыбора.

Экспорт:

Один заказ addPackage__Export.

Комментарии к работе с методами

В departure / shipping_method и delivery_point указываются ID выбранной пользователем доставки и ID выбранного ПВЗ (если используется ПВЗ).
Если выбрана курьерская доставка, то поле delivery_point должно отсутствовать, иначе при передаче заказа в API Shiptor будет сгенерирована ошибка.

У товаров и услуг (то есть в блоках products и services) указывается актуальная для данного конкретного заказа цена. Таким образом можно использовать товары с плавающей ценой и различные виды доставки под одним артикулом и одним названием «Доставка» без необходимости постоянного переопределения в номенклатуре Shiptor.

Обратите внимание: для тестирования работы с посылками клиенты на фулфилменте при запросе AddPackage(s) могут использовать флаг no_gather: true и явно тестовые данные по отправлению. Это необходимо, когда на складе Shiptor уже заведена номенклатура с остатками, чтобы избежать автоматической сборки/отправки посылки.

Наложенный платеж и объявленная ценность (страховка)

Наложенный платеж (доступен только в РФ) указывается в поле cod. Если отсутствует, передавать 0.
Наложенный платеж должен быть строго равен сумме по товарам и услугам включенным в посылку.
Объявленная ценность указывается в поле declared_cost, и не может быть меньше 10 рублей (актуально на момент написания инструкции).

Правило соотношения этих двух полей: cod <= declared_cost. То есть наложенный платеж не может быть больше, чем объявленная ценность. Например, если магазин уже получил частичную оплату от покупателя за заказ, но хочет застраховать его полную стоимость, то указанный наложенный платёж становится меньше полной (застрахованной) стоимости на сумму предоплаты.

Если наложенный платеж по заказу будет осуществляться банковской картой, то при передаче заказа в Shiptor необходимо передавать флаг cashless_payment со значением true (строго булевского типа).

!Добавление стоимости услуги в заказ с наложенным платежом увеличивает общую стоимость относительно расчета доставки (calculateShipping выполняется по товарам) заказа и Shiptor снова ее пересчитывает (то есть появляется рекурсия). Для минимизации разницы в стоимости доставки для магазина и покупателя клиент может использовать опцию наценки в профилях доставки. Размер наценки можно уточнить на странице тарифов РКО.

3.2 Получение статусов заказов

Получение списка новых сгруппированных статусов выполняется функцией getStatusList.

Получение статуса для посылки выполняется функцией getPackage.

Для списка посылок: getPackages.

В поле result — current_status возвращается внутренний статус в Shiptor (полный перечень можно получить методом getStatusList).

В поле result — status (устаревшее) возвращается внутренний статус в Shiptor (new, checking-declaration, waiting-pickup и другие).

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

«checkpoints»: [
{
«date»: «2016-10-25T12:10:04+03:00»,
«message»: «Отправлена из сортировочного центра»,
«details»: «Сортировочный пункт (Москва)»
},
],

Подробнее на скриншотах:

Напоминаем, что история операций над заказом в Shiptor получается из массива history в ответе функции getPackage:

Получение статусов прекращается для посылок в следующем состоянии в Shiptor:

recycled: Утилизирована,
lost: Утеряна.

Проверка рекомендуется для статусов:

delivered: Доставлена — после доставки может быть возвращена;
removed: Удалена — удаленная может быть восстановлена.

3.3 Телеметрия и передача статистики в Shiptor в HTTP-заголовке

В HTTP-заголовок при запросах AddPackage и AddPackages любых видов добавить 2 новых поля для статистики. Они должны отправляться в Shiptor при каждом таком запросе):

Integration-Name = <название системы> (например «Bitrix»)
Integration-Version = <версия модуля>

4. Логирование

Полный лог запросов

Необходим чекбокс активации записи в лог.

Предусмотреть:

строку статуса, если чекбокс включен: «Ведется с 2017.09.24 16:35»;
ссылку или кнопку на скачивание файла с этим логом;
кнопку очистки лога с уведомлением о событии с обновлением строки статуса.

Лог ведётся в текстовом формате. В него сохраняются все запросы к серверу и все ответы/ошибки сервера в виде JSON (по аналогии с API https://shiptor.ru/doc/) для последующего анализа.

Лог передачи заказов

Можно предусмотреть вариант дополнительного краткого лога, фиксирующего только запросы к серверу и ответы/ошибки по методам добавления заказов в Shiptor.

История изменений

Версия 1 от 24.07.2020 — актуальная

Екатерина Корзунина