retailCRM Документация

Порядок интеграции службы доставки через API

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

14.11.2017

    - 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.

27.09.2017

09.06.2017

22.03.2017

01.03.2017

Возможности интеграции

API системы позволяет:

  1. Производить расчет стоимости доставки по данным заказа по запросу пользователя системы
  2. Передавать пользователю системы актуальный для данного заказа набор терминалов
  3. Формировать различные упаковки в рамках одного заказа на доставку
  4. Формировать заказ на доставку, передавая в службу доставки необходимую информацию о заказе
  5. Редактировать и удалять заказ на доставку в определенных статусах по запросу пользователя системы
  6. Массово обновлять статусы для незавершенных заказов
  7. Передавать для печати документы по заказам из служб доставки по запросу пользователя
  8. Создавать, редактировать и удалять заявки на забор товара службой доставки

Работа с API производится в соответствии с правилами работы с API. Для интеграции используются API-методы секции Доставки.

Для интеграции необходимо:

  1. USER Запросить у пользователя API-ключ для доступа к системе
  2. API Зарегистрировать новый интеграционный модуль доставки
  3. USER Произвести необходимые настройки на странице настройки интеграции в системе
  4. USER Создать тип доставки связанный с новой интеграционной доставкой
  5. SYSTEM Запросы связанные с созданием и изменением заказов на доставку будет инициировать система в процессе работы пользователя
  6. API Отправлять актуальные данные по статусам доставок

Этапы с пометкой USER — это этапы, где данные предоставляются или заполняются пользователем. Этапы с пометкой API выполняются посредством API-запросов от службы доставки через API системы. Этап с пометкой SYSTEM подразумевает запросы осуществляемые системой к службе доставке с учетом настроек заданных при регистрации.

При возникновении ошибки при API-запросе к службе доставки, необходимо вернуть ответ (HTTP статус 200) в формате:

{
    "success": false,
    "errorMsg": "Текст ошибки" // Сообщение об ошибке. Будет отображаться пользователю в карточке заказа
}

Если в ответ на запрос расчета стоимости доставки или в ответ на запрос данных по заказу от сервера службы доставки был возвращен не валидный ответ, информация об этом запишется в Журнал действий, тип записи "Интеграционные доставки".

Для идентификации регионов, городов и улиц, помимо текстовых названий, передаются идентификаторы из сервиса Geohelper.

Регистрация и конфигурация службы доставки

Регистрация новой доставки, а также изменение настроек существующей производится с помощью метода POST /api/v5/integration-modules/{code}/edit. Если интеграционный модуль с кодом code уже существует, метод меняет его параметры, в противном случае создается новый модуль. При регистрации доставки передается уникальный код integrationModule[clientId], который будет позволять службе доставки идентифицировать аккаунт системы.

Параметры:

В поле integrationModule[integrations][delivery][actions] в виде ассоциативного массива ("Код метода": "Путь") задаются пути до конкретных методов. Список методов:

Некоторые методы не обязательны для реализации. Если они не требуются для интеграции их можно не передавать в массиве actions. Методы save, get, print, shipmentSave, shipmentDelete не обязательны к реализации. Если не передан метод save, то запросы на оформления доставки не отправляются. Если не передан метод shipmentDelete, то возможности редактирования и удаления заявки на отгрузку не будет. Метод delete не обязателен, если не используется метод save. Метод calculate не обязателен, если не используется метод save. В случае если не реализован метод calculate интеграция позволяет только вручную указывать номер отправления в карточке заказа и производить трекинг. Метод shipmentPointList не обязателен, если "selfShipmentAvailable": false. Не допускается передавать одинаковые значения для разных методов.

В поле integrationModule[integrations][delivery][requiredFields] передается массив полей, которые должны быть обязательными для заполнения для данной доставки. Возможные значения:

В поле integrationModule[integrations][delivery][payerType] можно указать массив возможных типов плательщиков за доставку. В случае доставки наложенным платежом в зависимости от типа плательщика возможны 2 варианта оплаты за доставку:

  1. Плательщик отправитель sender - в наложенный платеж входит стоимость доставки и стоимость товаров. Услуги доставки оплачиваются магазином.
  2. Плательщик получатель 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"
        }
    ]
}

Получение конфигурации интеграции

Метод позволяет получить данные интеграционного модуля службы доставки 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. Метод позволяет передавать статусы отдельно для каждого заказа в момент смены статуса или передавать историю изменений по группе заказов через определенные промежутки на усмотрение службы доставки.

Важно: За один запрос можно обновить статусы не более чем для 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][].

Проверять работу расчета стоимости нужно для следующих случаев:

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

Проверка создания/редактирования заявки на доставку

Необходима, если был передан путь для метода save в integrationModule[integrations][delivery][actions][].

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

При проверке создания/редактирования заявки на доставку нужно проверить следующие случаи:

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

Проверка печатных форм

Необходима, если был передан путь для метода 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 раз и после сохранения больше для редактирования недоступно.


Редакция от 15.01.2019 14:37