Подключение внешнего способа доставки – купить за 1 сом КР | InSales.kg платформа управления онлайн продажами

Подключение внешнего способа доставки

  1. Доставка курьером
  2. Доставка в точки самовывоза
  3. Получение списка служб доставки

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

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

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

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

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

{
  "order": {
"account_id": 1, "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 на следующий ресурс

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

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


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

POST /admin/delivery_variants.xml
<?xml version="1.0" encoding="UTF-8"?>
<delivery-variant>
  <title>express delivery</title>
  <type>DeliveryVariant::Fixed</type>
  <description>text</description>
  <position type="integer">1</position>
  <add-payment-gateways type="boolean">true</add-payment-gateways>
  <delivery-locations-attributes type="array">
    <delivery-locations-attribute>
      <region>Оренбургская область</region>
      <city>Оренбург</city>
    </delivery-locations-attribute>
  </delivery-locations-attributes>
  <inverted type="boolean">false</inverted>
  <charge-up-to type="integer">1000</charge-up-to>
  <price type="integer">300</price>
  <show-calendar-in-checkout type="boolean">true</show-calendar-in-checkout>
  <delivery-date-required type="boolean">true</delivery-date-required>
  <forbid-weekends type="boolean">true</forbid-weekends>
  <estimated-delivery-period type="integer">2</estimated-delivery-period>
  <order-time-is-later>18:00</order-time-is-later>
  <forbidden-days>23.02,08.03,01.05</forbidden-days>
  <show-time-intervals-in-checkout type="boolean">true</show-time-intervals-in-checkout>
  <time-intervals-required type="boolean">true</time-intervals-required>
  <time-intervals>10-12,12-16,16-20</time-intervals>
  <pick-up-sources-attributes type="array">
    <pick-up-sources-attribute>
      <title>My company</title>
      <pick-up-source-http-method>POST</pick-up-source-http-method>
      <url>https://my_awesome_domain.com/get_points</url>
      <point-info-url>https://my_awesome_domain.com/get_point_info</point-info-url>
    </pick-up-sources-attribute>
  </pick-up-sources-attributes>
</delivery-variant>

Источники данных заполняются в pick-up-sources-attributes
Тег add-payment-gateways позволяет автоматически добавить все способы оплаты
Более подробно параметры запроса можно изучить здесь:

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

{
  "order": {
    "account_id": 1,
"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 уходит аналогичный запрос, и дополнительно InSales передает идентификатор точки самовывоза, полученый из ответа со списком точек. В ответ возможно указать те же поля, что и при получении списка точек. Если значение поля отличается от предыдущего значения, будет установлено новое значение.

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

{
  "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 дней"
    },
    "fields_values": [
      {
        "handle": "my_field",
        "value": "new_value"
      }
    ]
    "payment_method": ["CASH", "CARD", "PREPAID"],
  }
]

id - уникальный идентификатор точки

type:

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

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

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

fields_values - дополнительные поля заказа

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

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

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

Тарифы для точек самовывоза

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

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

Нет необходимости устанавливать поля price, delivery_interval и fields_values вне списка тарифов, если для точки есть информации о тарифах. Если тарифы определены, то поля price, delivery_interval и fields_values в описании точки будут проигнорированы.

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

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

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

GET /admin/shipping_companies.json

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

Запрос: POST /admin/fields.xml

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<field>
<position type="integer">8</position>
<for-buyer type="boolean">true</for-buyer>
<example></example>
<office-title>Статус покупателя</office-title>
<created-at type="datetime">2011-11-14T13:21:13+04:00</created-at>
<updated-at type="datetime">2012-06-18T12:42:15+04:00</updated-at>
<obligatory type="boolean">false</obligatory>
<id type="integer">389591</id>
<title>Статус покупателя</title>
<destiny type="integer">2</destiny>
<system-name nil="true"></system-name>
</field>

Ответ:

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<field>
   <position type="integer">8</position>
   <for-buyer type="boolean">true</for-buyer>
   <example></example>
   <office-title>Статус покупателя</office-title>
   <created-at type="datetime">2011-11-14T13:21:13+04:00</created-at>
   <updated-at type="datetime">2012-06-18T12:42:15+04:00</updated-at>
   <obligatory type="boolean">false</obligatory>
   <id type="integer">389591</id>
   <title>Статус покупателя</title>
   <destiny type="integer">2</destiny>
   <system-name nil="true"></system-name>
</field>
 

Оставить оценку

Оценка успешно отправлена.
Она будет проверена администратором перед публикацией.
Перед публикацией все оценки проходят модерацию

Оценки: 0

Остались вопросы?
Отправь тикет в техподдержку!
Еще нет своего магазина?
Создайте интернет-магазин на платформе InSales
Всё для продаж уже внутри!
Недавно просмотренные статьи