Для того, чтобы воспользоваться новой версией, нужно в запросе к 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>
{
"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:
shipping_company_handle - идентификатор службы доставки
Доступные значения для поля shipping_company_handle можно получить, сделав запррос к API на следующий ресурс.
fields_values - дополнительные поля заказа
delivery_interval - объект, описывающий сроки доставки. Значения min_days и max_days желательны, но не обязательны. description - обязательное поле.
payment_method - массив с указанием возможных способов оплаты заказа:
Если для одной точки самовывоза существует более одного тарифа, то можно в описании точки добавить поле 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>