Top.Mail.Ru

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

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

Методы для работы с источником

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

  • Источники данных привязаны к приложению и удаляются автоматически при удалении приложения.
  • Если в поле method источника данных указано GET, то для получения информации о точках будет выполнен GET запрос (jsonp) с передачей только общей информации о заказе. Общий вес, общая стоимость. В данном случаем предполагается, что в ответе передаются все точки доставки.
   ?items_price=100.0&total_weight=100.0
  • Если в поле method указано POST, то для получения информации о точках будет выполнен POST запрос с передачей полного содержимого корзины.

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

{
  "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

1. Создайте дополнительные поля для заказа (опционально). В дополнительных полях можно хранить информацию, необходимую для дальнейшей передачи в службу доставки (номер постамата, зона доставки и т.д.). При создании доп поля нужно передать 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>

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

В поле type нужно указать DeliveryVariant::External

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

<?xml version="1.0" encoding="UTF-8"?>
<delivery-variant>
<title>Курьером</title>
<description>Супер быстрая доставка</description>
<delivery-locations-attributes type="array">
<delivery-location>
<region>Респ Адыгея</region>
<city>Майкоп</city>
</delivery-location>
<delivery-location>
<region>Респ Адыгея</region>
<city>Красногвардейский район</city>
</delivery-location>
</delivery-locations-attributes>
<type>DeliveryVariant::PriceDepend</type>
</delivery-variant>

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

<?xml version="1.0" encoding="UTF-8"?>
<delivery-variant>
...
<add-payment-gateways>true</add-payment-gateways>
</delivery-variant>

Ответ:

HTTP/1.1 200 OK
<?xml version="1.0" encoding="UTF-8"?>
<object>
<id type="integer">57802</id>
<title>Курьером</title>
<description>Супер быстрая доставка</description>
<position type="integer">3</position>
<created-at type="timestamp">2012-02-22 12:56:51 +0400</created-at>
<updated-at type="timestamp">2012-05-17 11:55:07 +0400</updated-at>
<delivery-locations type="array">
<delivery-location>
<id type="integer">12136</id>
<region>Респ Адыгея</region>
<city>Майкоп</city>
</delivery-location>
<delivery-location>
<id type="integer">12137</id>
<region>Респ Адыгея</region>
<city>Красногвардейский район</city>
</delivery-location>
</delivery-locations>
<type>DeliveryVariant::PriceDepend</type>
</object>

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

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

Оценки: 0

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