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

Доставка курьером

Доставка в точки самовывоза

Получение списка служб доставки

 

1. Описание интеграции курьерской доставки

Для того чтобы воспользоваться новой версией нужно в запросе к API InSales на создание внешнего способа доставки передать флаг api_version='v2' или создать способ доставки через интерфейс магазина указав соответствующую версию API.

Для внешнего способа доставки с флагом api_version='v2' меняется формат запроса к внешнему сервису.

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

 

 

Пример запроса к внешнему сервису:

{
  "order": {
    "order_lines": [
      {
        "quantity":1,
        "weight":100, // Вес в кг
        "dimensions":"100х10х3" //Габариты в формате ШхГхВ
      }
    ],
    "shipping_address": {
      "full_locality_name":"д Андреевка, Горшеченский район, Курская обл.", // Полное название населенного пункта
      "location": {
        "kladr_code":"4600500005300", // Код населенного пункта по КЛАДР
        "zip":"123456",
        "country":"RU",
        "state":"Курская",
        "state_type":"обл",
        "area":"Горшеченский",
        "area_type":"р-н",
        "city":null,
        "city_type":null,
        "settlement":"Андреевка",
        "settlement_type":"д",
        "address":"",
        "street":null,
        "street_type":null,
        "house":null,
        "flat":null,        
        "is_kladr":true // Флаг обозначающий, что адрес определен по КЛАДР
      }
    },
    "items_price":321,
    "total_weight":"0.0"
  }
}

Внешний сервис должен позволять выполнять CORS запросы устанавливая в ответе на запрос заголовоки:

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Language, Content-Language, Content-Type
 

В ответе ожидаются следующие данные:

[ 
  {
    "price": 100, // Стоимость доставки    
    // Для срока доставки может быть указано описание и\или числовые значения min и\или max
    "delivery_interval": {
      "min_days": 1, // Минимальный срок доставки
      "max_days": 3, // Максимальный срок доставки
      "description": "от 1 до 3-х дней" // Текстовое описание срока доставки
    },
    // Внутрениий идентификатор тарифа службы доставки. Нужен для возможности пересчета стоимости доставки при изменении состава заказа
    // Обязательно если вы возвращаете боле одного вариант доставки
    "tariff_id": 1,
    "shipping_company_handle": "my_company", //Если вы агрегатор служб доставки, передайте название конкретной компании, если нет, укажите свою
    // Название варианта доставки. 
    // Обязательно если вы возвращаете боле одного вариант доставки
    "title": "Быстрая доставка курьером",
    // Описание варианта доставки. 
    // Обязательно если вы возвращаете боле одного вариант доставки
    "description": "Доставка осуществляется в любой день и в любое время",
    // Доп поля заказа
    "fields_values": [
      {
        "handle": "my_awesome_field",
        "value": "new value"
      }
    ],
    // Сообщения о невозможности рассчитать доставку
    // При наличии ошибок в этом поле оформление заказа блокируется
    "errors": [],
    // Если вы рассчитали приблизительную стоимость доставки 
    // и для точного рассчета не хватает данных, можно указывать это здесь.
    // К примеру вес и габариты указаны не у всех товаров
    "warnings": [] 
  },
  {
    "price": 50, // Стоимость доставки    
    // Для срока доставки может быть указано описание и\или числовые значения min и\или max
    "delivery_interval": {
      "min_days": 3, // Минимальный срок доставки
      "max_days": 5, // Максимальный срок доставки
      "description": "от 3-х до 5 дней" // Текстовое описание срока доставки
    },
    // Идентификатор тарифа доставки. Нужен для возможности пересчета стоимости доставки при изменении состава заказа
    // Обязательно если вы возвращаете боле одного вариант доставки
    "tariff_id": 2,
    "shipping_company_handle": "my_company", //Идентификатор службы доставки
    // Название варианта доставки. 
    // Обязательно если вы возвращаете боле одного вариант доставки
    "title": "Медленная доставка курьером",
    // Описание варианта доставки. 
    // Обязательно если вы возвращаете боле одного вариант доставки
    "description": "Доставка осуществляется только по будним дням",
    // Доп поля заказа
    "fields_values": [
      {
        "handle": "my_awesome_field",
        "value": "new value"
      }
    ],
    // Сообщения о невозможности рассчитать доставку
    // При наличии ошибок в этом поле оформление заказа блокируется
    "errors": [],
    // Если вы рассчитали приблизительную стоимость доставки 
    // и для точного рассчета не хватает данных, можно указывать это здесь.
    // К примеру вес и габариты указаны не у всех товаров
    "warnings": [] 
  }
]

В новой версии API можно возвращать массив с разными тарифами и они будут отрисованы в корзине как самостоятельные способы доставки. ВАЖНО! Если у вас больше одного тарифа, то в ответе необходимо задать значение поля tariff_id. После оформления заказа по этому значению будет произовдиться пересчет стоимости доставки в случае изменения состава корзина или адреса доставки.

Значение поля tariff_id должно быть однозначно привязано к тарифу доставки.

Доступные значения для поля shipping_company_handle можно получить сделав запррос к API на следующий ресурс

 

2. Описание интеграции доставки в точки самовывоза

 

Для подключения доставки в точки самовывоза нет необходимости создавать способ доставки, достаточно создать источник данных для получения точек самовывоза 

 

Добавление источника данных для доставки в точки самовывоза

 

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

 

POST /admin/pick_up_sources.json

{
  "pick_up_source": {
    "title": "My company",
    "http_method": "POST",
    "url": "https://my_awesome_domain.com/get_points",
    "point_info_url": "https://my_awesome_domain.com/get_point_info"
  }
}

title - название службы доставки

http_method - см. описание ниже

url - адрес для получения информации о точках самовывоза

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

Подробнее про работу с API InSales можно найти тут https://wiki.insales.ru/wiki/%D0%97%D0%B0%D0%B3%D0%BB%D0%B0%D0%B2%D0%BD%D0%B0%D1%8F_%D1%81%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D0%B0 

Все метода для работы с источником данных можно найти тут https://api.insales.ru/?doc_format=JSON#pickupsource-create-pick-up-source-json

При добавлении нового источник данных следует учесть следующие нюансы: 

  • Источники данных привязаны к приложению и удаляются автоматически при удалении приложения
  • Если в поле method источника данных указано GET, то для получения информации о точках будет выполнен GET запрос (jsonp) с передачей только общей информации о заказе. Общий вес, общая стоимость. В данном случаем предполагается, что в ответе передаются все точки доставки.
   ?items_price=100.0&total_weight=100.0
  • Если в поле method указано POST, то для получения информации о точках будет выполнен POST запрос с передачей полного содержимого корзины
 
{
  "order": {
    "shipping_address": {
      "full_locality_name":"д Андреевка, Горшеченский район, Курская обл.",
      "location": {
        "kladr_code":"4600500005300", // Код населенного пункта по КЛАДР
        "region_zip":"123456",
        "country":"RU",
        "state":"Курская",
        "state_type":"обл",
        "area":"Горшеченский",
        "area_type":"р-н",
        "city":null,
        "city_type":null,
        "settlement":"Андреевка",
        "settlement_type":"д"
      }
    },
    "oder_lines": [
      {
        "quantity": 1,
        "weight": 100.0,
        "dimensions": "ШхГхВ"
      }
    ],
    "items_price": 100.0,
    "total_weight" 100.0
  }
}

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

 
{
  "id": "123",
  "order": { ... }
}
  • Для источников данных с методом POST ожидается поддержка CORS запросов. Для этого в ответе должен содержаться следующие заголовки:
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Accept, Accept-Language, Content-Language, Content-Type
 

 

 

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

[
  {
    "id": 123,
    "latitude": 55.76,
    "longitude": 37.64,
    "shipping_company_handle": "Моя компания",
    "price": 100,
    "title": "Захарова 10",
    "type": "locker",
    "address": "Москва, ул Марии Ульяновой д7",
    "description": "Постамат расположен в магазине Пятерочка",
    "phones": ["+7(495) 333 33 33"],
    "delivery_interval": {
      "min_days": 3,
      "max_days": 5,
      "description": "от 3-х до 4 дней"
    },
    "payment_method": ["CASH", "CARD", "PREPAID"]
  }
]

id: Уникальный идекнтификатор точки.

type:

  •     pvz - пункт выдачи заказа
  •     locker - постамат

shipping_company_handle: Идентификатор службы доставки

Доступные значения для поля shipping_company_handle можно получить сделав запррос к API на следующий ресурс

delivery_interval: объект описывающий сроки доставки. Значения min_days и max_days желательны, но не обязательны. description - обязательное поле.

payment_method: массив с указанием возможных способов оплаты заказа

  CASH - наличными в точке самовывоза

  CARD - банковской картой в точке самовывоза

  PREPAID - предоплата магазину (елси это значение не указано, то покупателю будет доступна только оплата в точке самовывоза)

 

Получение списка служб доставки

Список служб доставки можно получить обратившись по API к следующему ресурсу

GET /admin/shipping_companies.json

Действия приложения необходимые для подключения способа доставки.

1. Создаем доп поля для заказа (опционально) В доп полях можно хранить информацию необходимую для дальнейшей передачи в службу доставки (номер постамата, зона доставки и т.д.). При создании доп поля нужно передать destiny=3

https://wiki.insales.ru/wiki/InSales_API_-_%D0%94%D0%BE%D0%BF%D0%BE%D0%BB%D0%BD%D0%B8%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D1%8B%D0%B5_%D0%BF%D0%BE%D0%BB%D1%8F#.D0.94.D0.BE.D0.B1.D0.B0.D0.B2.D0.BB.D0.B5.D0.BD.D0.B8.D0.B5

2. Создаем способ доставки.

https://wiki.insales.ru/wiki/InSales_API_-_%D0%A1%D0%BF%D0%BE%D1%81%D0%BE%D0%B1%D1%8B_%D0%B4%D0%BE%D1%81%D1%82%D0%B0%D0%B2%D0%BA%D0%B8#.D0.94.D0.BE.D0.B1.D0.B0.D0.B2.D0.BB.D0.B5.D0.BD.D0.B8.D0.B5

В поле type указываем DeliveryVariant::External

Полезная статья?
Остались вопросы?
Отправь тикет в техподдержку!
Недавно просмотренные статьи