integrationModule[integrations][delivery][settings]. Оно позволяет получить или обновить настройки интеграционной доставки.
RequestCalculate добавлена передача содержимого упаковки calculate[packages][][items][].
PackageItem добавлены поля: externalId - идентификатор торгового предложения в магазине, xmlId - идентификатор торгового предложения в складской системе. Объект PackageItem используется в методах: Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["calculate"]} и Callback POST {integrationModule["baseUrl"]}/{configuration["actions"]["save"]}
integrationModule[integrations][delivery][shipmentDataFieldList][] - список дополнительных полей, использующихся для создания заявки на отгрузку.
- POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentSave"]} создание/редактирование заявки на отгрузку - POST {integrationModule["baseUrl"]}/{configuration["actions"]["shipmentDelete"]} удаление заявки на отгрузку
Для возможности работы с этими методами необходимо в методе POST /api/v5/integration-modules/{code}/edit в параметре integrationModule[integrations][delivery][actions][] передать пути для методов shipmentSave и shipmentDelete.
Configuration в списке обязательных полей requiredFields есть возможно указать обязательным поле "Терминал отгрузки", для этого надо в список добавить значение integrationDeliveryData.shipmentpointName.
RequestSave запроса на оформление доставки добавлена передача ставок НДС: save[packages][][items][][vatRate] - ставка НДС для товара в заказе. save[delivery][vatRate] - ставка НДС на услугу доставки. Оба этих поля могут принимать значение none что означает что товар/услуга доставки не облагается НДС.
Configuration добавлено необязательное булево поле rateDeliveryCost (по умолчанию true). Значение false нужно для случая, если служба доставки не рассчитывает стоимость доставки и метод calculate возвращает только информацию о доступных тарифах. Также добавлена возможность не указывать путь для метода calculate (путь для метода save также не должен быть указан). В этом случае интеграция позволяет вручную вбивать номер отправления и производить синхронизацию статусов доставки.
Configuration добавлен необязательный массив availableShipmentCountries - в нём задается список стран из которых доступна отправка. По умолчанию массив пустой, что означает, что ограничений на страны отправки нет.
save теперь, кроме кода ПВЗ, передается адрес доставки.
calculate добавлено поле extraDataAvailable - массив кодов полей из списка configuration["deliveryDataFieldList"], переданного в запросе конфигурации доставки. При выборе тарифа в карточке заказа, все поля, которых нет в массиве extraDataAvailable, будут скрыты.
Configuration добавлено необязательное текстовое поле description - может использоваться для передачи описания интеграции, в том числе для определения к какому аккаунту в службе доставки относится интеграция. Переданное значение выводится в настройках интеграции и в списке доступных интеграций в карточке типа доставки;
Configuration добавлено необязательное поле deliveryConfigurationUrl - содержит url по которому пользователь может перейти на страницу настроек интеграции на стороне службы доставки;
DeliveryDataField добавлено необязательное текстовое поле hint - в нем можно передать пояснение для пользователя как и когда использовать данное поле. Выводится в карточке заказа под соответствующем полем;
RequestCalculate и RequestSave добавлено поле currency содержащее код валюты;
RequestSave добавлено поле siteName (наименование магазина) и необязательное поле legalEntity (Наименование юридического лица продавца);
PackageItem добавлено поле offerId - идентификатор оффера в системе
ContentType должен принимать значение application/zip.
API системы позволяет:
Работа с API производится в соответствии с правилами работы с API. Для интеграции используются API-методы секции Доставки и Интеграция.
Для интеграции необходимо:
USER Запросить у пользователя API-ключ для доступа к системе
API Зарегистрировать новый интеграционный модуль доставки
USER Произвести необходимые настройки на странице настройки интеграции в системе
USER Создать тип доставки связанный с новой интеграционной доставкой
SYSTEM Запросы связанные с созданием и изменением заказов на доставку будет инициировать система в процессе работы пользователя
API Отправлять актуальные данные по статусам доставок
Этапы с пометкой USER — это этапы, где данные предоставляются или заполняются пользователем. Этапы с пометкой API выполняются посредством API-запросов от службы доставки через API системы. Этап с пометкой SYSTEM подразумевает запросы осуществляемые системой к службе доставке с учетом настроек заданных при регистрации.
При возникновении ошибки при API-запросе к службе доставки, необходимо вернуть ответ (HTTP статус 200) в формате:
{
"success": false,
"errorMsg": "Текст ошибки" // Сообщение об ошибке. Будет отображаться пользователю в карточке заказа
}Если в ответ на запрос расчета стоимости доставки или в ответ на запрос данных по заказу от сервера службы доставки был возвращен не валидный ответ, информация об этом запишется в Журнал действий, тип записи "Интеграционные доставки".
Для идентификации регионов, городов и улиц, помимо текстовых названий, передаются идентификаторы из сервиса Geohelper.
Регистрация новой доставки, а также изменение настроек существующей производится с помощью метода POST /api/v5/integration-modules/{code}/edit. Если интеграционный модуль с кодом code уже существует, метод меняет его параметры, в противном случае создается новый модуль. При регистрации доставки передается уникальный код integrationModule[clientId], который будет позволять службе доставки идентифицировать аккаунт системы.
Параметры:
apiKey - API-ключ системы
integrationModule - json, содержащий описание интеграционного модуля
integrationModule[integrations][delivery] - настройки конфигурации интеграции со службой доставки
В поле integrationModule[integrations][delivery][actions] в виде ассоциативного массива ("Код метода": "Путь") задаются пути до конкретных методов. Список методов:
calculate - Метод расчета стоимости доставки
save - Метод создания/редактирования доставки
get - Метод получения данных доставки.
delete - Метод удаления/отмены доставки. Вызывается если был отменен заказ, или если был изменен тип доставки у заказа.
print - Метод печати документов.
shipmentPointList - Метод получения списка терминалов отгрузки.
shipmentSave - Метод создания/редактирования заявки на отгрузку.
shipmentDelete - Метод удаления заявки на отгрузку.
Некоторые методы не обязательны для реализации. Если они не требуются для интеграции их можно не передавать в массиве actions.
Методы save, get, print, shipmentSave, shipmentDelete не обязательны к реализации. Если не передан метод save, то запросы на оформления доставки не отправляются. Если не передан метод shipmentDelete, то возможности редактирования и удаления заявки на отгрузку не будет.
Метод delete не обязателен, если не используется метод save.
Метод calculate не обязателен, если не используется метод save. В случае если не реализован метод calculate интеграция позволяет только вручную указывать номер отправления в карточке заказа и производить трекинг.
Метод shipmentPointList не обязателен, если "selfShipmentAvailable": false.
Не допускается передавать одинаковые значения для разных методов.
В поле integrationModule[integrations][delivery][requiredFields] передается массив полей, которые должны быть обязательными для заполнения для данной доставки. Возможные значения:
lastName - Фамилия покупателя
patronymic - Отчество покупателя
phone - Телефон покупателя
email - E-mail покупателя
length - Длина
width - Ширина
height - Высота
shipmentDate - Дата отгрузки
deliveryTime.from - Начало интервала времени доставки
deliveryTime.to - Окончание интервала времени доставки
manager - Менеджер заказа
deliveryAddress.regionId - При выборе региона обязать выбирать регион из выпадающего списка. В этом поле будет находиться идентификатор региона в сервисе geohelper (http://geohelper.info/ru/doc/api#get--api-v1-regions)
deliveryAddress.cityId - При выборе города обязать выбирать город из выпадающего списка. В этом поле будет находиться идентификатор города в сервисе geohelper (http://geohelper.info/ru/doc/api#get--api-v1-cities)
deliveryAddress.street - Наименование улицы доставки
deliveryAddress.streetId - При выборе улицы обязать выбирать улицу из выпадающего списка. В этом поле будет находиться идентификатор улицы в сервисе geohelper (http://geohelper.info/ru/doc/api#get--api-v1-streets)
deliveryAddress.flat - Квартира
deliveryAddress.index - Почтовый индекс
integrationDeliveryData.shipmentpointName - Терминал отгрузки
В поле integrationModule[integrations][delivery][payerType] можно указать массив возможных типов плательщиков за доставку. В случае доставки наложенным платежом в зависимости от типа плательщика возможны 2 варианта оплаты за доставку:
sender - в наложенный платеж входит стоимость доставки и стоимость товаров. Услуги доставки оплачиваются магазином.
receiver - в наложенный платеж включается только стоимость товаров заказа. Стоимость доставки всегда равна 0. Подразумевается, что служба доставки должна будет взять с покупателя переданную сумму наложенного платежа в пользу магазина и отдельно стоимость доставки в свою пользу.
Параметр integrationModule[integrations][delivery][selfShipmentAvailable] позволяет активировать работу с терминалами отгрузки. Если передано значение true, в карточке заказа появится поле, где можно будет выбрать терминал отгрузки из списка, получаемого методом shipmentPointList. Так же в настройках интеграции пользователь сможет задать терминалы отгрузки по умолчанию для каждого из своих складов. При расчете стоимости и оформлении доставки в качестве адреса отправки обычно отправляется адрес склада отгрузки, указанного в карточке заказа. В случае, когда для заказа выбран терминал отгрузки - в данных адреса отправки отправляется только код выбранного терминала отгрузки.
Ответ:
{
"code": "generic.delivery-service-code",
"success": true
}Служба доставки должна предусмотреть возможность подключения нескольких аккаунтов клиента. Для этого необходимо перед отправкой запроса на регистрацию интеграционного модуля доставки использовать метод получения информации об интеграционном модуле. В случае, если интеграция уже зарегистрирована и clientId не совпадает с текущим, то нужно в параметр integrationModule[code] передать код службы доставки с постфиксом, обеспечивающим уникальность кода (integrationModule[integrationCode] при этом должен оставаться без изменений). В таком случае создается новый интеграционный модуль и у клиента будет возможность работать с любым количеством аккаунтов в службе доставки, которые будут представлены как различные типы доставки. Также рекомендуется в поле integrationModule[integrations][delivery][description] передавать описание, которое поможет различить пользователю несколько одинаковых интеграций с разными аккаунтами (например можно передавать несколько последних цифр номера договора или номера аккаунта пользователя "Номер договора - ***42").
Интеграция позволяет передавать в конфигурации производитьвольный набор полей. В поле integrationModule[integrations][delivery][deliveryDataFieldList] перечисляются поля, которые будут выводится в карточке заказа. Если editable=true - данные редактируемых полей будут передаваться при формировании доставки. Если параметр affectsCost=true, данные поля будут передаваться при расчете стоимости доставки. В поле integrationModule[integrations][delivery][shipmentDataFieldList] указан набор полей, использующихся при работе с отгрузкой. Формат элементов списка shipmentDataFieldList полностью идентичен формату элементов deliveryDataFieldList.
Не обязательное редактируемое текстовое поле:
{
...
"deliveryDataFieldList": [
{
"code": "textField",
"label": "Текстовое поле",
"type": "text",
"required": false,
"affectsCost": false,
"editable": true
}
]
}Информационное текстовое поле:
{
...
"deliveryDataFieldList": [
{
"code": "textField",
"label": "Размер страховки",
"hint": "Использовать только при международно доставке",
"type": "text",
"required": false,
"affectsCost": false,
"editable": false
}
]
}Поле выводится в карточке заказа. Может быть заполнено при получении ответа на запрос формирования доставки или при обновлении статуса доставки.
Обязательное редактируемое числовое поле. Т.к. affectsCost=true - считается что поле влияет на стоимость доставки и значение поля отправляется в запросе на расчет стоимости доставки:
{
...
"deliveryDataFieldList": [
{
"code": "integerField",
"label": "Число мест",
"type": "integer",
"required": true,
"affectsCost": true
}
]
}Чекбокс:
{
...
"deliveryDataFieldList": [
{
"code": "checkboxField",
"label": "Переключатель",
"type": "checkbox",
"required": false,
"affectsCost": true
}
]
}Поле множественного выбора:
{
...
"deliveryDataFieldList": [
{
"code": "services",
"label": "Сервисы доставки",
"type": "choice",
"multiple": true,
"choices": [
{
"value": "ER3",
"label": "Осмотр"
}
{
"value": "RQW",
"label": "Доставка на выходных"
}
],
"affectsCost": true
}
]
}Поле с автокомплитом. Для его использования необходимо реализовать метод получения подсказок и передать url метода:
{
...
"deliveryDataFieldList": [
{
"code": "types",
"label": "Тип груза",
"type": "autocomplete",
"autocompleteUrl": "http://selivery.service.com/api/autocomplete/types"
}
]
}Поле с датой:
{
...
"deliveryDataFieldList": [
{
"code": "dateSimple",
"label": "Дата доставки",
"type": "date"
}
]
}Интеграция позволяет передавать в конфигурации набор настроек. В поле integrationModule[integrations][delivery][settings] перечисляются поля, которые сконфигурированы модулем. Рекомендуется давать возможность настраивать все параметры на стороне модуля и передавать в систему через это поле. Переданные настройки будут скрыты в настройках интеграции модуля в системе.
Настройки:
defaultPayerType - Плательщик за доставку по умолчанию
costCalculateBy - Стоимость доставки по умолчанию (Возможные значения auto|manual)
nullDeclaredValue - Нулевая объявленная стоимость по умолчанию
lockedByDefault - По умолчанию не отправлять данные в службу доставки
paymentTypes - Способы оплаты (Справочник объектов)
shipmentPoints - Склады (Справочник объектов)
statuses - Соответствие статусов (Справочник объектов)
deliveryExtraData - Дополнительные значения полей доставки по умолчанию
shipmentExtraData - Дополнительные значения полей отгрузки по умолчанию
Пример задания настроек:
{
"defaultPayerType": "sender",
"costCalculateBy": "auto",
"nullDeclaredValue": true,
"lockedByDefault": true,
"paymentTypes": [
{
"code": "cash",
"active": true,
"cod": true
}
],
"shipmentPoints": [
{
"code": "online",
"shipmentPointId": "1234",
"shipmentPointLabel": "Test"
}
],
"statuses": [
{
"code": "new",
"trackingStatusCode": "new"
}
],
"deliveryExtraData": {
"passport": "0000 000000"
},
"shipmentExtraData": {
"count": "5"
}
}Метод позволяет получить данные интеграционного модуля службы доставки GET /api/v5/integration-modules/{code}.
Для расчета стоимости доставки система инициирует POST вызов метода указанного в integrationModule[integrations][delivery][actions]["calculate"] конфигурации.
Расчёт стоимости происходит при открытии попапа со списком способов доставки.
Если для каких-либо тарифов не хватает переданных данных, служба доставки может для тарифа не передавать параметр cost, а в параметре description передавать сообщение для пользователя. В этом случае тариф будет не доступен для выбора, но будет отображаться в списке тарифов.
Если у службы доставки нет возможности рассчитывать стоимость доставки, при конфигурации интеграции можно передать параметр integrationModule[integrations][delivery][rateDeliveryCost] со значением false, в этом случае стоимость доставки cost передавать не нужно и стоимость определяется по правилам, заданным в типе доставке на стороне системы.
Для создания новой доставки система инициирует POST вызов метода указанного в integrationModule[integrations][delivery][actions]["save"] конфигурации. Запрос на редактирование доставки аналогичен запросу на создание, необходимо дополнительно передавать идентификатор заказа в службе доставки save["deliveryId"].
Создание новой доставки происходит в момент сохранения заказа, в котором выбран тип доставки, интегрированный с данной службой доставки. Редактирование доставки происходит при сохранении заказа, для которого уже была оформлена доставка и были произведены какие-либо изменения в заказе.
Если при регистрации интеграционного модуля был передан параметр integrationModule[integrations][delivery][codAvailable]=true то, в зависимости от выбранного в заказе типа оплаты, могут быть переданы данные о наложенном платеже. Флаг save[delivery][withCod] указывает нужно ли взимать наложенный платеж. Общая сумма наложенного платежа определяется как сумма по всем товарам в заказе save[packages][][items][][cod] (нужно учитывать что значение в этом поле - размер наложенного платежа за единицу товара), плюс величина платеж за услугу доставки save[delivery][cod]
Для получения данных для доставки система инициирует GET запрос метода указанного в integrationModule[integrations][delivery][actions]["get"].
Метод срабатывает в момент, когда через API системы создается новый заказ, либо редактируется заказ и передан идентификатор оформленной доставки order[delivery][data][externalId].
Для удаления доставки система инициирует POST вызов метода указанного в integrationModule[integrations][delivery][actions]["delete"].
Удаление доставки происходит если заказ не находится в статусе из конечной группы статусов (Выполнен или Отменен), статус доставки редактируемый isEditable=true и произошло изменение типа доставки, либо заказ был переведён в статус из группы Отменен.
Для обновления статусов доставки служба доставки должна использовать метод POST /api/v5/delivery/generic/{subcode}/tracking (subcode - символьный код экземпляра модуля, указанный в методе POST /api/v5/integration-modules/{code}/edit в поле integrationModule[code]). Метод позволяет передавать статусы отдельно для каждого заказа в момент смены статуса или передавать историю изменений по группе заказов через определенные промежутки на усмотрение службы доставки.
Важно: За один запрос можно обновить статусы не более чем для 100 заказов. При передаче большего числа заказов метод вернет сообщение об ошибке.
Для печати форм указанных при конфигурации в integrationModule[integrations][delivery][plateList] система инициирует POST запрос метода указанного в integrationModule[integrations][delivery][actions]["print"].
Запрос отправляется при печати документов службы доставки из карточки заказа, либо из списка заказов.
Служба доставки должна сформировать pdf-файл печатной формы и вернуть его в виде байтового массива. Также можно вернуть zip-архив документов, для этого content-type ответа должен принимать значение application/zip.
Если требует показать пользователю сообщение об ошибке, то нужно вернуть ответ с кодом 400. Содержимое ответа должно быть стандартным ответом с сообщением об ошибке.
Для работы с терминалами система инициирует GET запрос метода указанного в integrationModule[integrations][delivery][actions]["shipmentPointList"].
Запрос инициируется при выборе терминала отгрузки в карточке заказа.
Для создания заявки на забор товара система инициирует POST запрос метода указанного в integrationModule[integrations][delivery][actions]["shipmentSave"]
Запрос отправляется при сохранении новой отгрузки, либо при сохранении уже созданной отгрузки.
Если при регистрации модуля не бы передан путь до метода integrationModule[integrations][delivery][actions]["shipmentDelete"], то возможности редактирования и удаления заявки на отгрузку не будет.
Для удаления заявки на забор товара система инициирует POST запрос метода указанного в integrationModule[integrations][delivery][actions]["shipmentDelete"]
Запрос отправляется при изменении статуса отгрузки на Отменена.
При работе с autocomplete полями задаными в конфигурации integrationModule[integrations][delivery][deliveryDataFieldList] система будет инициализировать запрос к службе доставки используя GET запрос метода указанного в autocompleteUrl конфигурации соответствующего поля.
Перед отправкой модуля на публикацию необходимо проверить работоспособность модуля на своем аккаунте RetailCRM. Перед любой проверкой в карточке заказа нужно выбрать тип доставки, интегрированный с вашим модулем. Необходимо проверять как будет работать интеграция при введении корректных и при введении заведомо неверных данных (прошедшие даты даты отгрузки/доставки, нулевой вес и т.д.). При неверных данных модуль должен возвращаться ошибку, оформленную по правилам работы с API, содержащую сообщение с описанием проблемы, понятным пользователю (пример: дата доставки указана в прошлом, в таком случае модуль должен вернуть сообщение, которые бы указывало что именно "Дата доставки" указана не верно).
Необходима при условии integrationModule[integrations][delivery][selfShipmentAvailable] = true.
В карточке заказа выберите склад отгрузки, и проверьте что список терминалов приёма загружается без ошибок.
Необходима, если в списке дополнительных полей integrationModule[integrations][delivery][deliveryDataFieldList] есть поля, у которых type="autocomplete".
В карточке заказа найдите это поле в блоке "Доставка", и проверьте что список значений подгружается в него без ошибок.
Необходима, если был передан путь для метода calculate в integrationModule[integrations][delivery][actions][].
Проверять работу расчета стоимости нужно для следующих случаев:
integrationModule[integrations][delivery][codAvailable]=true);
integrationModule[integrations][delivery][allowPackages]=true);
integrationModule[integrations][delivery][payerType]).
Результатом работы для каждого случая должно быть либо понятное пользователю сообщение об ошибке в данных, либо список тарифов. При расчёте стоимости доставки все переданные параметры должны правильно учитываться, насколько это позволяет сервис доставки.
Необходима, если был передан путь для метода save в integrationModule[integrations][delivery][actions][].
Для создания заявки на доставку - зайдите в карточку заказа, выберите интеграционный тип доставки, заполните данные заказа и сохраните. Для редактирования - зайдите в карточку заказа, для которого была оформлена заявка на доставку, сделайте изменения в данных заказа и сохраните.
При проверке создания/редактирования заявки на доставку нужно проверить следующие случаи:
integrationModule[integrations][delivery][selfShipmentAvailable]=true);
integrationModule[integrations][delivery][codAvailable]=true);
integrationModule[integrations][delivery][allowPackages]=true);
Результатом работы для каждого случая должно быть либо понятное пользователю сообщение об ошибке, либо успешное сохранение заказа и получение номера отправления для заказа. После сохранения проверить, что все переданные параметры, которые может обработать сервис доставки, получены без ошибок.
Необходима, если был передан путь для метода print в integrationModule[integrations][delivery][actions][] и список доступных печатных форм integrationModule[integrations][delivery][plateList] не пуст.
Печать документов следует проверить из карточки заказа и из списка заказов для нескольких заказов (если integrationModule[integrations][delivery][platePrintLimit] > 1) для всех типов документов.
Необходима, если был передан путь для метода delete в integrationModule[integrations][delivery][actions][].
Проверять удаление лучше всего через изменение статуса заказа, для которого была оформлена доставка, на статус из группы Отменен.
Необходима, если был передан путь для метода get в integrationModule[integrations][delivery][actions][].
Для этой проверки в вашем сервисе должна быть созданная заявка на доставку с известным номером. Отправьте запрос на создание заказа в системе через API и в запросе передайте номер отправления (order[delivery][data][externalId]). В результате в системе должен быть создан заказ с оформленной заявкой на доставку, в который подгружены все необходимые данные по доставке из вашего сервиса.
Пример самого простого запроса на создание заказа:
{
"lastName": "test",
"delivery": {
"code": "<delivery_type_code>",
"data": {
"externalId": "<delivery_external_id>"
}
}
}Необходима, если был передан путь для метода shipmentSave в integrationModule[integrations][delivery][actions][].
Нужно проверить следующие случаи:
Необходима, если был передан путь для метода shipmentDelete в integrationModule[integrations][delivery][actions][].
Для удаление заявки на отгрузку - поменяйте статус заявки на Отменена.
Для того, чтобы в заказе можно было использовать интегрированную службу доставки, необходимо сначала создать тип доставки или использовать уже существующую. Зайдите в раздел Администрирование > Справочники > Типы доставок и нажмите на кнопку «Добавить».
В создаваемом типе доставки необходимо заполнить все поля, в том числе и поле «Интегрировать с». В данном поле необходимо указать ту службу доставки, которую Вы ходите использовать в заказе. Обратите внимание, что поле «Интегрировать с» заполняется 1 раз и после сохранения больше для редактирования недоступно.