Версия 1.0.6
Специальная оболочка для интегарции (Чекаут Shiptor) обладает своим API.
API Чекаута предназначено для ускорения интеграции с Shiptor. Одно из основных его преимуществ: визуальная настройка в панели управления Чекаута методов доставки. Вне зависимости от сложности правил и ограничений, применяемых к ним и расчету на основе параметров корзины, можно получить нужный результат со стороны API при помощи одной простой функции simpleCalculate.
Чтобы реализовать схожий функционал самостоятельно, программисту с хорошим знанием предмета потребуется месяц работы или больше. Здесь же всё это выполняется в едином интерфейсе настройки расчетов и выбранных методов доставки.
Передаваемые в API Чекаута заказы попадают в панель обработки заказов и затем оттуда передаются автоматически (настроенным правилом) или вручную в панель логистики Shiptor (личный кабинет).
Обратите внимание: в зависимости от того, какой ключ будет указан: API или виджет, вы можете использовать это API как на стороне сервера (server-side), так и со стороны ваших скриптов (front-side).
В интересах безопасности наших клиентов часть функций недоступна для использования со стороны виджетов. Это указано в их описании (уточнения появятся чуть позднее).
Чтобы лучше понять практические аспекты использования функций, о которых пойдёт речь в этом разделе, скачайте Техническое Задание на интеграцию с примерами и пояснениями.
Используемые сокращения:
Для обмена данными с КЧ используется формат JSON: и запрос, и ответ в этом формате. Часть запросов просто транслируются напрямую из Shiptor API с авторизацией (отмечены в таб. 1.1 как оригинальные), однако некоторые запросы слегка отличаются в пользу больших возможностей (специальные в таб. 1.1). Также есть запросы, специфичные для КЧ (специальные в таб 1.1). Все они должны направляться на https://checkout.shiptor.ru/api.
Таблица 1.1 Список доступных запросов к API КЧ:
|
Название метода |
Описание |
Тип |
|
getDeliveryPoints |
Получение списка ПВЗ для конкретной курьерской службы. |
Специальный |
|
suggestSettlement |
Получение списка НП, подходящих под поисковый запрос. |
Оригинальный |
|
simpleSuggestSettlement |
Упрощенное получение списка НП. |
Специальный |
|
calculateShipping |
Расчет доставки. |
Оригинальный |
|
simpleCalculate |
Расчет доставки с учетом настроек из оболочки КЧ. |
Специальный |
|
getWare |
Получение информации о товаре по его артикулу. |
Специальный |
|
addOrder |
Добавление заказа. |
Специальный |
|
setProduct |
Добавление или обновление информации о товаре. |
Специальный |
|
getShippingMethods |
Получение списка методов доставки Shiptor. | Оригинальный |
| getAllShippingMethods | Получение своих методов доставки из КЧ вместе с методами доставки Shiptor. | Специальный |
| getStatusList | Получение списка доступных статусов заказов Shiptor. | Оригинальный |
| getSites | Получение списка магазинов, заведенных в КЧ. | Специальный |
| getSettlements | Получение списка доступных населенных пунктов, регионов и стран от API Shiptor. | Оригинальный |
| getPackage | Получение информации по одному отправлению. | Оригинальный |
| setDataBasic | Передача статистической информации о системе, использующей интеграцию. | Специальный |
| simpleAddPackage | Создание товаров, отсутствующих в номенклатуре ЛК Shiptor до момента добавления заказа. | Специальный |
|
getOrder |
Получение информации о заказе. |
Специальный |
|
getOrders |
Получение информации о перечне заказов. |
Специальный |
Все запросы должны снабжаться специальным виджет-ключом (ВК), получаемым в КЧ.
Этот ключ используется в качестве доступа к организации, заведенной в КЧ. Запросы без ВК, будут вызывают ошибку авторизации. Если в результате обработки или выполнения запроса в API КЧ возникла какая-либо ошибка, в поле error будет добавлено её описание. Чаще всего они возникают при авторизации (отсутствует ВК, нет тела запроса, не указано название метода), при валидации (не заполнены обязательные поля) или при исполнении запросов в API Shiptor. В случае успешной обработки запроса вернется JSON с полем result, содержащим результат его выполнения.
Внешняя структура всех запросов одинакова. На первом уровне вложенности идут поля: wk (содержит ВК), method (содержит название вызываемого метода) и params (сюда передаются детальные параметры запроса). Отличия заключаются в объекте params.
Таблица 1.2 Основная часть любого запроса к API КЧ
| wk | строка | Виджет-ключ. |
| method | строка | Название метода. |
|
params |
объект |
Объект, содержащий тело запроса. |
Все три поля строго обязательны. Даже там, где может не быть тела запроса, нужно передавать пустой объект в params.
Возвращаемый JSON будет в строковом виде, то есть нужно будет выполнить разбор JSON из строки в объект JS (при помощи JSON. parse() или аналогов), в ассоциативный массив или стандартный класс PHP (при помощи json_decode() или аналогов).
Полностью идентичен оригинальному запросу getDeliveryPoints. Предназначен для получения списка ПВЗ для конкретного метода доставки в конкретный НП. В отличие от оригинального запроса допускает указание сразу нескольких идентификаторов методов доставки в виде массива.
Структура запроса getDeliveryPoints:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
shipping_method |
да |
целое число/массив |
Идентификатор нужного метода доставки или массив идентификаторов. |
|
kladr_id |
да |
строка |
КЛАДР-код НП назначения. |
|
cod |
нет |
булев |
Признак наложенного платежа. |
|
card |
нет |
булев |
Признак наложенного платежа по карте. |
|
limits |
нет |
объект |
Объект с ограничениями по габаритам и весу. |
|
weight |
нет |
число |
Ограничение по весу (кг). |
|
height |
нет |
число |
Ограничение по высоте (см). |
|
length |
нет |
число |
Ограничение по длине (см). |
|
width |
нет |
число |
Ограничение по ширине (см). |
Пример запроса на получение ПВЗ:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"method": "getDeliveryPoints",
"wk":"8UUD5H2D5P6AD8XKJV2X2FGS8G78",
"params": {
"shipping_method":[11,14],
"kladr_id": "77000000000",
"cod": true,
"card": false,
"limits": {
"weight": 30,
"length": 30,
"width": 30,
"height": 10
}
}
}
В ответ вернется JSON, содержащий в поле result массив ПВЗ для указанного метода доставки. Если был указан массив идентификаторов методов доставки, то в result ПВЗ будут в двумерном массиве. Его ключи совпадают с указанными идентификаторами методов доставки, а содержимое (одномерные массивы) — со списком ПВЗ для каждой службы.
{
"result": [
[],
[
{
"id": 63121,
"courier": "boxberry",
"address": "109382, Москва г, Судакова ул, д.10",
"phones": [
"+7(499)391-56-22"
],
"trip_description": "Метро - Люблино.\nКакой выход из метро - последний вагон из центра.\nОстановка - Проспект 40 лет Октября.\nПримерное расстояние от остановки до Отделения - 50 м.\n6-этажное нежилое здание.\nЭтаж - 1.\nРасположение входа в отделение - отдельный вход с улицы, Магазин \"Автозапчасти\".",
"work_schedule": "пн-пт: 09.30-20.00, сб-вс: 09.30-18.00",
"shipping_days": 1,
"cod": true,
"card": true,
"gps_location": {
"latitude": 55.672417,
"longitude": 37.744774
},
"kladr_id": "77000000000",
"shipping_methods": [
76,
14
],
"limits": {
"max_weight": {
"value": 31,
"unit": "kg"
},
"volume": 0.48,
"self_pick_up": true
},
"code": "190811",
"type": "point",
"updated_at": "2019-10-24 03:26:58",
"prepare_address": {
"administrative_area": "г Москва",
"settlement": null,
"street": "ул Судакова",
"house": "10",
"postal_code": "109382"
},
"shipping_method": 14
}
]
}
Повторяет структуру оригинального запроса suggestSettlement. Предназначен для получения списка НП, подходящих под задаваемый поисковый запрос.
Структура запроса suggestSettelment:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
query |
да |
строка |
Строка, по которой выполняется поиск НП из API Shiptor. |
|
country_code |
нет |
строка |
Двухбуквенный код страны, в которой ищется желаемый НП (RU, KZ, BY). |
Если известен регион, НП можно указать его в query через пробел, но это не всегда дает желаемый результат. В ответе сервера возвращается 100 подходящих вариантов, среди которых может не быть нужного. В таком случае попробуйте сделать запрос с указанием региона искомого НП или же без него.
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "2DR6XXTX!N2FKP2D7MMEMK",
"method": "suggestSettlement",
"params": {
"query": "Воронеж",
"country_code": "RU"
}
}
В результате запроса в поле result вернется массив НП или же пустой массив, если подходящего варианта не нашлось.
{
"result": [
{
"kladr_id": "36000001000",
"name": "Воронеж",
"type": "город",
"short_readable": "г Воронеж",
"type_short": "г",
"administrative_area": "Воронежская область",
"readable_parents": "Воронежская область",
"country": {
"name": "Россия",
"code": "RU"
}
},
{
"kladr_id": "36000004000",
"name": "Воронеж-45",
"type": "город",
"short_readable": "г Воронеж-45",
"type_short": "г",
"administrative_area": "Воронежская область",
"readable_parents": "Воронежская область",
"country": {
"name": "Россия",
"code": "RU"
}
},
{
"kladr_id": "36000003000",
"name": "Нововоронеж",
"type": "город",
"short_readable": "г Нововоронеж",
"type_short": "г",
"administrative_area": "Воронежская область",
"readable_parents": "Воронежская область",
"country": {
"name": "Россия",
"code": "RU"
}
},
{
"kladr_id": "37019000078",
"name": "Воронеж",
"type": "деревня",
"short_readable": "Шуйский р-н., д Воронеж",
"type_short": "д",
"administrative_area": "Ивановская область",
"readable_parents": "Ивановская область, Шуйский район",
"country": {
"name": "Россия",
"code": "RU"
}
},
{
"kladr_id": "22015000007",
"name": "Воронеж",
"type": "поселок",
"short_readable": "Змеиногорский р-н., п Воронеж",
"type_short": "п",
"administrative_area": "Алтайский край",
"readable_parents": "Алтайский край, Змеиногорский район",
"country": {
"name": "Россия",
"code": "RU"
}
},
{
"kladr_id": "36005000006",
"name": "Губари",
"type": "село",
"short_readable": "Борисоглебский р-н., с Губари",
"type_short": "с",
"administrative_area": "Воронежская область",
"readable_parents": "Воронежская область, Борисоглебский район",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+3"
}
]
}
Аналогичен предыдущему запросу, однако возвращает уже отфильтрованный список НП по специальному алгоритму: только те населенные пункты, название которых начинается с искомой строки. Структура запроса и ответ полностью повторяют обычный запрос suggestSettlement.
Структура запроса simpleSuggestSettlement:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| params | да | объект | Объект, содержащий тело запроса. |
| query | да | строка | Строка, по которой выполняется поиск НП из API Shiptor. |
| country_code | нет | строка | Двухбуквенный код страны, в которой ищется желаемый НП (RU, KZ, BY). |
| strict | нет | булев | Фильтрация выводимых названий НП по точному соответствию запросу. |
| region | нет | строка | Фильтрация выводимых НП по названию административно-территориальной единицы. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU290TDF",
"method": "simpleSuggestSettlement",
"params": {
"query": "Воронеж",
"country_code": "RU"
}
}
Возвращаемый ответ:
{
"result": [
{
"kladr_id": "36000001000",
"name": "Воронеж",
"type": "город",
"short_readable": "г. Воронеж",
"type_short": "г.",
"administrative_area": "Воронежская область",
"readable_parents": "Воронежская область",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+3"
},
{
"kladr_id": "22048000004",
"name": "Воронежская-Молодёжная",
"type": "станция",
"short_readable": "Тальменский р-н., ст Воронежская-Молодёжная",
"type_short": "ст",
"administrative_area": "Алтайский край",
"readable_parents": "Алтайский край, Тальменский район",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+7"
},
{
"kladr_id": "22015000007",
"name": "Воронеж",
"type": "поселок",
"short_readable": "Змеиногорский р-н., п Воронеж",
"type_short": "п",
"administrative_area": "Алтайский край",
"readable_parents": "Алтайский край, Змеиногорский район",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+7"
},
{
"kladr_id": "27018000012",
"name": "Воронежское-3",
"type": "село",
"short_readable": "Хабаровский р-н., с Воронежское-3",
"type_short": "с",
"administrative_area": "Хабаровский край",
"readable_parents": "Хабаровский край, Хабаровский район",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+10"
},
{
"kladr_id": "48017000008",
"name": "Воронежское Маланино",
"type": "деревня",
"short_readable": "Хлевенский р-н., д Воронежское Маланино",
"type_short": "д",
"administrative_area": "Липецкая область",
"readable_parents": "Липецкая область, Хлевенский район",
"country": {
"name": "Россия",
"code": "RU"
},
"timezone": "UTC+3"
}
]
}
Полностью повторяет структуру стандартного запроса calculateShipping. Предназначен для расчета доставки с наложенным платежом в отдельно взятый НП отправления, которое имеет конкретные габариты и вес. Если в поле country_code указать код страны, отличный от RU, KZ или BY, будет выполнен расчет доставки за рубеж calculateShippingInternational, и в ответ вернутся уже экспортные методы. В качестве страны отправления (departure_country_code) будет выбрана РФ (RU), в качестве страны назначения (destination_country_code) — значение из country_code. Поля, отмеченные звездочкой (*), не обрабатываются в расчете, а значение insurance запроса calculateShippingInternational устанавливается из настроек КЧ.
Структура запроса calculateShipping:
|
Название |
Обязательное поле |
Тип |
Описание |
| method | да | строка | Название метода. |
| wk | да | строка | Виджет-ключ. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
length |
да |
число |
Длина (см). |
|
width |
да |
число |
Ширина (см). |
|
height |
да |
число |
Высота (см). |
|
weight |
да |
число |
Вес (кг). |
|
cod |
да* |
число |
Сумма наложенного платежа в руб, если отсутствует — передавайте 0. |
|
declared_cost |
да |
число |
Сумма оценочной стоимости (руб). Если присутствует наложенный платеж, то оценочная стоимость должна быть равна ему. Если нет, то здесь можно указывать любую сумму от 10 руб и больше. |
|
kladr_id |
да* |
строка |
КЛАДР-код НП назначения. |
|
kladr_id_from |
нет* |
строка |
КЛАДР-код НП отправления для расчета сквозной доставки. |
|
courier |
нет |
строка |
Можно ограничить возвращаемые методы доставки конкретной курьерской службой, указав ее код. Варианты указаны в описании поля запроса calculateShipping по ссылке. |
|
country_code |
нет |
строка |
Двухбуквенный код страны, в которой ищется желаемый НП. Если указать РФ (RU), Казахстан (KZ) или Беларусь (BY), то будет выполнен обычный расчет доставки. Если же указать, например, Германию (DE), тогда запрос станет считать доставку зарубеж, при которой в качестве страны отправления устанавливается RU (РФ). |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"method": "calculateShipping",
"wk":"8UUD5H2D5P6AD8XKJV2X2FGS8G78",
"params": {
"length": 10,
"width": 10,
"height": 10,
"weight": 10,
"cod": 10,
"declared_cost": 10,
"kladr_id": "77000000000",
"courier": "dpd",
"country_code": "RU"
}
}
В ответ в поле result придет объект из двух полей: request и methods. В поле request будет содержаться объект исходного запроса, а в methods — массив доступных методов доставки или же пустой массив, если для заданных исходных данных не нашлось методов доставки.
{
"result": {
"request": {
"length": 10,
"width": 10,
"height": 10,
"weight": 10,
"cod": 10,
"declared_cost": 10,
"country_code": "RU",
"kladr_id": "77000000000"
},
"methods": [
{
"status": "ok",
"method": {
"id": 35,
"name": "Shiptor Самовывоз",
"category": "delivery-point",
"group": "shiptor_terminal",
"courier": "shiptor",
"comment": "",
"description": null,
"help_url": "https://shiptor.ru/help/common/all-delivery-methods#shiptor-selfpickup"
},
"cost": {
"services": [
{
"service": "shipping",
"sum": 80,
"currency": "RUB",
"readable": "80,00 руб."
},
{
"service": "cod",
"sum": 40,
"currency": "RUB",
"readable": "40,00 руб."
},
{
"service": "cost_declaring",
"sum": 0.02,
"currency": "RUB",
"readable": "0,02 руб."
}
],
"total": {
"sum": 120.02,
"currency": "RUB",
"readable": "120,02 руб."
}
},
"days": "1 рабочий день",
"priority": 1
},
{
"status": "ok",
"method": {
"id": 18,
"name": "DPD ПВЗ",
"category": "delivery-point",
"group": "dpd_eparcel_delivery",
"courier": "dpd",
"courier_code": "DPe",
"comment": "",
"description": null,
"help_url": "https:\/\/shiptor.ru\/help\/common\/all-delivery-methods#dpd-selfpickup",
"constraints": {
"min_declared_cost": 0
}
}
}
}
Специальный запрос, в основе которого лежит calculateShipping. Он выполняет расчет доставки, а также применяет к нему настройки клиента КЧ, ассоциированного с ВК, который передаётся в запросе. Сюда входят: скидки/наценки, доступность способов доставки, увеличение показываемых сроков доставки, габариты и вес по умолчанию, а также все будущие настройки, запланированные к реализации.
Кроме этого, выполняется расчет габаритов исходя из настроек в КЧ. Если не передать длину, ширину, высоту и вес в соответствующих полях, то процесс будет выполнен в зависимости от настроек в КЧ. Результатом становится либо полная подстановка габаритов по умолчанию (если в настройках КЧ указаны габариты как габариты посылки в целом), либо (если в настройках КЧ указаны габариты как габариты товара) попытка рассчитать эффективные габариты, опираясь на габариты товаров в составе корзины. Если, как в последнем случае, габариты у какого-либо товара не указаны, берутся параметры из настроек КЧ. Если передать габариты, они используются вместо значений по умолчанию.
Результат расчета вернется в поле request результирующего JSON.
Структура запроса simpleCalculate:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| domain | нет | строка | URL-адрес сайта, для которого создан отдельный магазин в КЧ. Если не передан, учитываются настройки для магазина по умолчанию. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
| stock | нет | число | Идентификатор склада для методов доставки от склада Shiptor. Если не передан, учитываются настройки КЧ. |
|
length |
да |
число |
Длина посылки (см), если в разделе КЧ «Опции доставки» для «Типа расчёта» выбрано «Для посылки». В противном случае параметр играет роль умолчания для товара. |
|
width |
да |
число |
Ширина посылки (см), если в разделе КЧ «Опции доставки» для «Типа расчёта» выбрано «Для посылки». В противном случае параметр играет роль умолчания для товара. |
|
height |
да |
число |
Высота посылки (см), если в разделе КЧ «Опции доставки» для «Типа расчёта» выбрано «Для посылки». В противном случае параметр играет роль умолчания для товара. |
|
weight |
да |
число |
Вес посылки (см), если в разделе КЧ «Опции доставки» для «Типа расчёта» выбрано «Для посылки». В противном случае параметр играет роль умолчания для товара. |
|
cod |
да |
число |
Сумма наложенного платежа (руб). Если отсутствует, передавайте 0. |
|
declared_cost |
да |
число |
Сумма оценочной стоимости (руб). Если присутствует наложенный платеж, то оценочная стоимость должна быть равна ему. В противном случае здесь можно указывать любую сумму от 10 руб и больше. |
|
courier |
нет |
строка |
Можно ограничить возвращаемые методы доставки конкретной курьерской службой, указав ее код. Варианты указаны в описании запроса calculateShipping по ссылке. |
|
kladr_id |
да |
строка |
КЛАДР-код НП назначения из справочника Shiptor. Для экспортных заказов необязателен и игнорируется. |
|
country_code |
да |
строка |
Двухбуквенный код страны назначения (RU, KZ, BY, ...). |
|
coupon |
нет |
массив |
Купон |
|
basket |
да |
массив |
Массив объектов товаров в корзине с количеством, габаритами, весом и стоимостью каждой позиции. |
|
id |
да |
строка |
Идентификатор товара в магазине. При работе с существующими товарами должен соответствовать shopArticle. |
|
name |
нет |
строка |
Название товара. |
|
price |
да |
число |
Стоимость 1 единицы товара. |
|
quantity |
да |
целое число |
Количество товара в этой позиции. |
|
length |
да |
число |
Длина товара (см). Можно передать 0 или null и тогда она будет взята из номенклатуры КЧ. |
|
width |
да |
число |
Ширина товара (см). Можно передать 0 или null и тогда она будет взята из номенклатуры КЧ. |
|
height |
да |
число |
Высота товара (см). Можно передать 0 или null и тогда она будет взята из номенклатуры КЧ. |
|
weight |
да |
число |
Вес товара (кг). Можно передать 0 или null и тогда он будет взят из номенклатуры КЧ. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU290TDF",
"method": "simpleCalculate",
"params": {
"length": 0,
"width": 0,
"height": 0,
"weight": 0,
"cod": 98000,
"declared_cost": 98000,
"kladr_id": "77000000000",
"country_code": "RU",
"basket": [
{
"id": "12003p",
"name": "Apple iPhone 6S Plus ",
"price": 40000,
"quantity":1,
"length":20,
"width": 15,
"height": 10,
"weight": 1.4
},
{
"id": "18000h",
"name": "Lenovo ",
"price": 18000,
"quantity":2,
"length":20,
"width": 10,
"height": 5,
"weight": 1
}
]
}
}
В ответ в поле result придет объект из двух полей: request и methods. В поле request содержится объект исходного запроса с габаритами посылки в целом, рассчитанными через КЧ, а в methods — массив доступных методов доставки или же пустой массив, если для заданных исходных данных не нашлось методов доставки.
{
"result": {
"request": {
"length": 30,
"width": 10,
"height": 10,
"weight": 1,
"cod": 98000,
"declared_cost": 98000,
"country_code": "RU",
"kladr_id_from": "77000000000",
"kladr_id": "77000000000",
"stock": true
},
"methods": [
{
"status": "ok",
"method": {
"id": 18,
"name": "DPD ПВЗ",
"category": "delivery-point",
"group": "dpd_eparcel_delivery",
"courier": "dpd",
"courier_code": "DPe",
"comment": "",
"description": null,
"help_url": "https://shiptor.ru/help/common/all-delivery-methods#dpd-selfpickup",
"constraints": {
"min_declared_cost": 0
}
},
"cost": {
"services": [
{
"service": "shipping",
"name": "Стоимость доставки",
"sum": 256.93,
"currency": "RUB",
"readable": "256,93 ₽"
},
{
"service": "cod",
"name": "Услуга обработки наложенного платежа",
"sum": 1764,
"currency": "RUB",
"readable": "1 764,00 ₽"
},
{
"service": "cost_declaring",
"name": "Услуга объявления оценочной стоимости",
"sum": 588,
"currency": "RUB",
"readable": "588,00 ₽"
}
],
"total": {
"sum": 2610,
"currency": "RUB",
"readable": "2610 руб."
}
},
"days": "2 рабочих дня",
"min_days": 2,
"max_days": 2,
"sd": false,
"priority": 100,
"types": [
"delivery_point",
"delivery_locker",
"terminal"
],
"min_declared_cost": 0
}
],
"payments": [
"cash",
"card",
"card_online"
],
"code": "bitrix_shiptor_ru",
"stock": 1
}
Специальный запрос, которого нет в API Shiptor. Он предназначен для получения информации об одном товаре по его Артикулу магазина.
Структура запроса getWare:
|
Название |
Обязательное поле |
Тип |
Описание |
| method | да | строка | Название метода. |
| wk | да | строка | Виджет-ключ. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
shop_article |
да |
строка |
Товарный артикул магазина. |
|
coupon |
нет |
массив |
Купон |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"method": "getWare",
"wk":"8UUD5H2D5P6AD8XKJV2",
"params": {
"shop_article": "HOLOD122"
}
}
В ответ придет информация о товаре в поле result. Если товар с таким артикулом не удалось найти, то в ответ вернется соответствующая ошибка.
{
"result": {
"id": 314382,
"name": "Холодильник",
"englishName": "platie-2",
"brand": null,
"barcode": null,
"article": null,
"shopArticle": "262#266",
"url": null,
"length": 20,
"width": 20,
"height": 20,
"weight": 1,
"price": "2999.00",
"retailPrice": "500.00",
"fragile": true,
"danger": false,
"perishable": false,
"needBox": false,
"adult": false,
"fulfilment": {
"total": 0,
"rest": 0,
"waiting": 0
},
"photos": [
{
"id": 22761,
"link": "URL изображения"
}
]
}
}
Специальный метод, добавляющий новый заказ в КЧ.
Структура запроса addOrder:
|
Название |
Обязательное поле |
Тип |
Описание |
| method | да | строка | Название метода. |
| wk | да | строка | Виджет-ключ. |
| domain | нет | строка | URL-адрес сайта, для которого создан отдельный магазин в КЧ. Если не передан, будут учитываться настройки для магазина по умолчанию из КЧ. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
| stock | нет | число | Идентификатор склада для методов доставки от склада Shiptor. Если не передан, используются настройки КЧ. |
|
length |
да |
число |
Длина посылки (см). |
|
width |
да |
число |
Ширина посылки (см). |
|
height |
да |
число |
Высота посылки (см). |
|
weight |
да |
число |
Вес посылки (кг). |
|
price |
да |
число |
Сумма по товарам в заказе. |
|
deliveryPrice |
да |
число |
Стоимость доставки. |
|
delivery_date |
нет |
строка |
Желаемая дата доставки в формате ГГГГ-ММ-ДД (для метода Сберкурьер). |
|
delivery_time |
нет |
число |
Желаемое время доставки (для метода Сберкурьер). Должен соответствовать индексу нужного временного интервала из ответа в методе getDeliveryTime. |
| payed | нет | булев | Признак оплаченности заказа. |
|
cod |
да |
булев |
Признак наложенного платежа. Для экспортных заказов всегда false. |
|
payment |
да |
строка |
Тип оплаты заказа: card (картой) или cash (наличными). Для экспортных заказов всегда card. |
|
departure |
да |
объект |
Объект, содержащий параметры доставки. |
|
shipping_method |
да |
целое число |
Идентификатор метода доставки. |
|
delivery_point |
нет |
строка |
Идентификатор выбранного ПВЗ, если выбран соответствующий метод доставки. |
|
comment |
нет |
строка |
Комментарий к заказу. |
|
address |
да |
объект |
Объект, содержащий адрес доставки. |
|
settlement |
да |
строка |
Наименование НП назначения. Для экспортных заказов должно быть написано латиницей. |
| address_line | да* | строка | Строка адреса вида «улица, дом, квартира» для тех случаев, когда адрес в виде единой строки. Если этот параметр не задан, то обязательно нужно задать поля: street и house (для доставки не в ПВЗ). |
|
street |
да* |
строка |
Улица назначения. Для экспортных заказов должна быть написана латиницей. |
|
house |
да* |
строка |
Номер дома. |
|
apartment |
нет |
строка |
Номер квартиры. |
|
country |
да |
строка |
Двухбуквенный код страны назначения (RU, KZ, BY, ...). |
| region | нет | строка |
Регион назначения. Обязателен для экспортных заказов и должен быть написан латиницей. |
|
postal_code |
нет |
строка |
Почтовый код. Обязателен для Почты России и экспортных заказов. |
|
|
да |
строка |
Электронная почта получателя. |
|
phone |
да |
строка |
Номер мобильного телефона получателя. |
|
name |
да |
строка |
Имя получателя. Для экспортных заказов должно быть написано латиницей. |
|
surname |
да |
строка |
Фамилия получателя. Для экспортных заказов должна быть написана латиницей. |
|
patronimic |
нет |
строка |
Отчество получателя (обязательно для Почты РФ). Для экспортных заказов должно быть написано латиницей. |
|
kladr_id |
да |
строка |
КЛАДР-код НП назначения из справочника Shiptor. Для экспортных заказов необязателен и игнорируется. |
|
products |
да |
массив объектов |
Массив объектов товаров в корзине с количеством и стоимостью. |
|
id |
да |
строка |
Идентификатор товара в магазине. При работе с существующими товарами должен соответствовать shopArticle. |
|
name |
нет |
строка |
Название товара. |
|
price |
да |
число |
Стоимость 1 единицы товара. |
|
quantity |
да |
целое число |
Количество товара в этой позиции. |
Если указан ПВЗ, поля street, house и apartment становятся необязательными и наоборот. В поле products должен быть массив товаров. Их нужно заранее добавить в номенклатуру ЛК. При создании заказа мы планируем автоматизировать добавление в номенклатуру ЛК тех товаров, которые не были загружены туда ранее.
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"method": "addOrder",
"wk":"8UUD5H2D5P6AD8XKJV2",
"params": {
"length": 25,
"width": 25,
"height": 25,
"weight": 3,
"price":98000,
"deliveryPrice": 500,
"declaredCost": 98500,
"cod": true,
"payment": "cash",
"departure":{
"shipping_method": 20,
"comment": "комментарий",
"address":{
"settlement": "Воронеж",
"street":"Кольцовская",
"house":"22",
"apartment":"12",
"country":"RU",
"postal_code":"394000",
"email":"retst@nert.ry",
"phone":"+79009009090",
"name":"Тестовая",
"surname":"АПИ",
"kladr_id":"36000001000"
}},
"products":
[
{
"id": "12003p",
"name": "Apple iPhone 6S Plus ",
"price": 40000,
"quantity":2
},
{
"id": "18000h",
"name": "Lenovo ",
"price": 18000,
"quantity":1
}
]
}
}
В ответ в поле result вернётся тот же самый объект заказа, который был отправлен на добавление. К нему будет добавлено ещё одно поле external_id, содержащее номер созданного заказа.
{
"result": {
"length": 25,
"width": 25,
"height": 25,
"weight": 3,
"price": 98000,
"deliveryPrice": 500,
"declaredCost": 98500,
"cod": true,
"payment": "cash",
"departure": {
"shipping_method": 20,
"comment": "комментарий",
"address": {
"settlement": "Воронеж",
"street": "Кольцовская",
"house": "22",
"apartment": "12",
"country": "RU",
"postal_code": "394000",
"email": "retst@nert.ry",
"phone": "+79009009090",
"name": "Тестовая",
"surname": "АПИ",
"kladr_id": "36000001000"
}
},
"products": [
{
"id": "12003p",
"name": "Apple iPhone 6S Plus ",
"price": 40000,
"quantity": 2
},
{
"id": "18000h",
"name": "Lenovo ",
"price": 18000,
"quantity": 1
}
],
"site": {
"is_default": true
},
"external_id": "202002121717-52038028",
"id": 26469
}
}
Специальный метод, добавляющий или обновляющий существующий товар. На вход принимает набор параметров, схожий с addProduct. Проверяет существует ли товар с таким артикулом магазина и, если существует, обновляет информацию о нём (editProduct). Если не существует, создает товар с таким артикулом магазина и заданными параметрами.
Структура запроса setProduct:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
shop_article |
да |
строка |
Товарный артикул магазина. |
|
url |
нет | строка | Ссылка на страницу с товаром в магазине. |
|
englishName |
нет | строка | Название товара на английском. |
|
name |
нет |
строка |
Название товара. |
|
length |
нет |
число |
Длина (см). |
|
width |
нет |
число |
Ширина (см). |
|
height |
нет |
число |
Высота (см). |
|
weight |
нет |
число |
Вес (кг). |
|
retail_price |
нет |
число |
Розничная цена в рублях. |
|
fragile |
нет |
булев |
Признак хрупкого товара. |
|
danger |
нет |
булев |
Признак опасного товара. |
|
perishable |
нет |
булев |
Признак скоропортящегося товара. |
|
need_box |
нет |
булев |
Признак потребности в упаковке товара. |
|
barcode |
нет |
строка |
Штрихкод товара. |
|
article |
нет |
строка |
Артикул товара. |
|
photos |
нет |
массив |
Изображения для товаров. |
|
price |
нет |
строка |
Оптовая цена (руб). |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6AD8XK",
"method": "setProduct",
"params": {
"shop_article": "HOLOD122",
"name": "Холодильник Бирюза",
"length": 58,
"width": 58,
"height": 210,
"weight": 30,
"retailPrice": 18000,
"fragile": true,
"danger": false,
"perishable": false,
"needBox": true,
"barcode": "46067820462034159",
"article": "HOLOD101",
"price": 15000,
"photos": [
{"link":"URL изображения" },
{"link": "URL изображения" }
]
}
}
Пример ответа:
{
"result": {
"jsonrpc": "2.0",
"result": {
"id": 1438897,
"name": "Холодильник Бирюза",
"englishName": null,
"brand": null,
"barcode": "46067820462034159",
"article": "HOLOD101",
"shopArticle": "HOLOD122",
"url": null,
"length": 58,
"width": 58,
"height": 210,
"weight": 30,
"price": "15000.00",
"retailPrice": 18000,
"fragile": true,
"danger": false,
"perishable": false,
"needBox": false,
"adult": false,
"fulfilment": {
"total": 0,
"rest": 0,
"waiting": 0
}
},
"id": 3050,
"photos": [
{
"id": 72,
"link": "URL изображения"
},
{
"id": 73,
"link": "URL изображения"
}
]
}
}
В ответе приходит id добавленных изображений. Используйте эти данные в запросе, если необходимо актуализировать галерею:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6AD8XKJV2",
"method": "setProduct",
"params": {
"shop_article": "HOLOD122",
"name": "Холодильник Бирюза",
"length": 58,
"width": 58,
"height": 210,
"weight": 30,
"retailPrice": 18000,
"fragile": true,
"danger": false,
"perishable": false,
"needBox": true,
"barcode": "46067820462034159",
"article": "HOLOD101",
"price": 15000,
"photos": [
{"id":72,"link":"URL нового изображения" }
]
}
}
Оригинальный запрос, позволяющий получить список доступных для клиента методов доставки Shiptor. Не имеет выходным параметров, помимо ВК и названия метода.
Структура запроса getShippingMethods:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| params | да | объект | Объект, содержащий тело запроса. |
| method | да | строка | Название метода. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU290TDF",
"method": "getShippingMethods",
"params": {}
}
Ответ идентичен ответу на метод getShippingMethods. Дополнительно возвращается поле active у каждого способа доставки. В нём передается признак активности метода в КЧ: true (активен) или false (неактивен).
{
"result": {
"1": {
"id": 1,
"name": "Shiptor Курьер",
"category": "to-door",
"group": "shiptor_courier",
"courier": "shiptor",
"courier_code": "OS",
"comment": "",
"description": null,
"help_url": "https:\/\/shiptor.ru\/help\/common\/all-delivery-methods#shiptor-courier",
"constraints": {
"min_declared_cost": 0
},
"active": true,
"site_id": 80
},
"11": {
"id": 11,
"name": "PickPoint",
"category": "delivery-point",
"group": "pickpoint",
"courier": "pickpoint",
"courier_code": "PPe",
"comment": "",
"description": null,
"help_url": "https:\/\/shiptor.ru\/help\/common\/all-delivery-methods#pick-point",
"constraints": {
"min_declared_cost": 0
},
"active": true,
"site_id": 80
},
}
}
Специальный запрос, позволяющий вдобавок к методам доставки Shiptor получить также и свои методы доставки клиента КЧ, если таковые имеются. Входных параметров не имеет, помимо ВК и названия метода.
Структура запроса getAllShippingMethods:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| domain | нет | строка | URL-адрес сайта, для которого создан отдельный магазин в КЧ. Если не передан, вернутся методы доставки для магазина по умолчанию из КЧ. |
| params | да | объект | Объект, содержащий тело запроса. |
| method | да | строка | Название метода. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU",
"method": "getAllShippingMethods",
"params": {}
}
Ответ идентичен ответу на метод getShippingMethods. Дополнительно возвращается поле active у каждого способа доставки. В нём передается признак активности метода в КЧ: true (активен) или false (неактивен).
{
"result": {
"1": {
"id": 1,
"name": "Shiptor Курьер",
"category": "to-door",
"group": "shiptor_courier",
"courier": "shiptor",
"courier_code": "OS",
"comment": "",
"description": null,
"help_url": "https://shiptor.ru/help/common/all-delivery-methods#shiptor-courier",
"constraints": {
"min_declared_cost": 0
},
"active": true,
"site_id": 1
},
"21": {
"id": 21,
"name": "PickPoint",
"category": "delivery-point",
"group": "pickpoint",
"courier": "pickpoint",
"courier_code": "PPe",
"comment": "",
"description": null,
"help_url": "https://shiptor.ru/help/common/all-delivery-methods#pick-point",
"constraints": {
"min_declared_cost": 0
},
"active": true,
"site_id": 1
},
"own1": {
"id": "own1",
"name": "Мой способ доставки",
"category": "to-door",
"group": "own_1",
"courier": "own",
"comment": "",
"description": null,
"active": false,
"site_id": 1
}
}
}
Оригинальный запрос, позволяющий получить список статусов заказов Shiptor. Не имеет входных параметров, помимо ВК и названия метода.
Структура запроса getStatusList:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ |
| method | да | строка | Название метода |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU290TDF",
"method": "getStatusList",
"params": []
}
Ответ идентичен ответу на метод getStatusList.
{
"result": {
"new": {
"code": "new",
"name": "Новая",
"group": {
"standard": "Доставка посылок не вмещающих услугу комплектации товаров на складе.",
"through": "Доставка посылок сквозным методом."
}
},
"pickup": {
"code": "pickup",
"name": "Ожидает забора",
"group": {
"through": "Доставка посылок сквозным методом."
}
}
}
}
Специальный запрос, позволяющий получить список магазинов, заведенных у клиента в КЧ. Не имеет входных параметров, помимо ВК и названия метода.
Структура запроса getSites:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6AD8XK",
"method": "getSites"
}
В ответе в ключе result придет массив, содержащий в качестве элементов пару значений: доменное имя магазина и его уникальный символьный код в КЧ.
"result": [
{
"domain": "доменное имя магазина 1",
"code": "символьный код 1"
},
{
"domain": "доменное имя магазина 2",
"code": "символьный код 2"
},
...
]
Оригинальный запрос, позволяющий получить список населенных пунктов API Shiptor, включая регионы. Входные параметры в ключе params идентичны методу getSettlements.
Структура запроса getSettlements:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| params | да | объект | Объект, содержащий тело запроса. |
| per_page | да | число | Сколько населённых пунктов нужно выводить на одну страницу. |
| page | да | число | Номер страницы. |
| types | нет | массив | Тип данных. |
| level | да | число | Уровень. |
| parent | да | строка | КЛАДР-код родителя. |
| country_code | нет | строка | Двухбуквенный код страны, в которой ищется желаемый НП (RU, KZ, BY) |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZ",
"method": "getSettlements",
"params": {
"per_page": 10,
"page": 1,
"types": [
"Город"
],
"level": 2,
"parent": "02000000000",
"country_code": "RU"
}
}
Возвращаемый ответ идентичен тому же методу.
{
"result": {
"count": 12,
"page": 1,
"per_page": 10,
"pages": 2,
"settlements": [
{
"kladr_id": "02000011000",
"name": "Подгорный",
"type": "Сельсовет",
"type_short": "с\/с",
"parents": [
{
"kladr_id": "02000000000",
"name": "Башкортостан",
"type": "Республика",
"type_short": "Респ"
}
]
}
]
}
}
Оригинальный запрос, позволяющий получить информацию по одному отправлению от API Shiptor. Входные параметры в ключе params идентичны методу getPackage.
Структура запроса getPackage:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ |
| method | да | строка | Название метода |
|
external_id |
нет | строка |
Идентификационный номер посылки в магазине. Обязателен, если не задан id. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU290TDF",
"method": "getPackage",
"params": {
"external_id": "ASD123"
}
}
Возвращаемый ответ идентичен тому же методу.
{
"result": {
"id": 1605834,
"previous_id": null,
"external_id": "ASD123",
"stock": 6,
"status": "removed",
"current_status": "removed",
"tracking_number": "RP1605834",
"external_tracking_number": null,
"created_at": "2019-12-05 11:52:29",
"weight": 0.012,
"length": null,
"width": null,
"height": null,
"cod": 10,
"declared_cost": 10,
"no_gather": false,
"label_url": "https:\/\/shiptor.ru\/package\/6c9d2880dedb52c2780369a56c497e7ed2480cc314174baa65f12586df03abec\/label.png",
"small_label_url": "https:\/\/shiptor.ru\/package\/6c9d2880dedb52c2780369a56c497e7ed2480cc314174baa65f12586df03abec\/print-label?size=1",
"sberbank_payment_qr_url": "https:\/\/shiptor.ru\/package\/6c9d2880dedb52c2780369a56c497e7ed2480cc314174baa65f12586df03abec\/qr.png",
"qr_payment_url_sberbank_delivery": "https:\/\/shiptor.ru\/package\/6c9d2880dedb52c2780369a56c497e7ed2480cc314174baa65f12586df03abec\/sberbank\/delivery\/qr.svg",
"qr_payment_url_cloudpayments_delivery": "https:\/\/shiptor.ru\/package\/6c9d2880dedb52c2780369a56c497e7ed2480cc314174baa65f12586df03abec\/cloudpayments\/delivery\/qr.svg",
"postamat_load_code": null,
"postamat_load_code_valid_till": null,
"sent_at": null,
"delivered_at": null,
"cost": {
"shipping_cost": null,
"cod_service_cost": null,
"compensation_service_cost": null,
"total_cost": 0
},
"departure": {
"shipping_method": {
"id": 19,
"name": "IML Курьер",
"category": "to-door",
"group": "iml_courier",
"courier": "iml",
"courier_code": "IMe",
"comment": "",
"description": null,
"help_url": "https:\/\/shiptor.ru\/help\/common\/all-delivery-methods#iml-courier",
"constraints": {
"min_declared_cost": 0
}
},
[…]
}
}
Специальный запрос, позволяющий передать статическую информацию о конкретной интеграции с КЧ.
Структура запроса setDataBasic:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| params | да | объект | Объект, содержащий тело запроса. |
| url | да | строка | Адрес сайта. Если их несколько, разделяйте точкой с запятой. |
| system_type | да | строка | Название CMS. |
| system_version | да | число | Версия CMS. |
| integration_version | да | число | Версия интеграции. |
| vendors | да | число | Число поставщиков. |
| daily_orders_total | да | число | Число заказов за последние сутки. |
| daily_orders_shiptor | да | число | Число заказов с доставкой Shiptor за последние сутки. |
Входные параметры следующие:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6A",
"method": "setDataBasic",
"params": {
"url": "доменное имя",
"system_type": "WooCommerce",
"system_version": "1.21",
"integration_version": "1.5",
"vendors": 1,
"daily_orders_total": 15,
"daily_orders_shiptor": 15
}
}
Возвращаемый ответ:
{
"result": true
}
Оригинальный запрос, который, прежде чем добавлять заказ, создает товары, отсутствующие в номенклатуре ЛК Shiptor. Входные параметры в ключе params идентичны методу addPackage.
Структура запроса simpleAddPackage:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| params | да | объект | Объект, содержащий тело запроса. |
| stock | нет | число | Идентификатор склада Shiptor. |
|
length |
да |
число |
Длина (см). |
|
width |
да |
число |
Ширина (см). |
|
height |
да |
число |
Высота (см). |
|
weight |
да |
число |
Вес (кг). |
|
cod |
да |
число |
Сумма наложенного платежа (руб). Если отсутствует, передавайте 0. |
| declared_cost | да | число | Сумма оценочной стоимости (руб). Если присутствует наложенный платеж, то оценочная стоимость должна быть равна ему. В противном случае здесь можно указывать любую сумму от 10 руб и больше. |
| external_id | нет | строка | Уникальный идентификатор заказа в вашем магазине. |
| departure | да | объект | Данные об отправлении. |
| shipping_method | да | число | ID способа доставки. |
| cashless_payment | нет | булев | Оплата картой. |
| comment | нет | строка | Комментарий. |
| address | да | строка | Данные об адресе доставки. |
| country | да | строка | Двухбуквенный код страны (RU, KZ, BY). |
| receiver | да | строка | Ф.И.О или название организации. |
| name | да | строка | Имя. |
| surname | да | строка | Фамилия. |
| patronymic | нет | строка | Отчество. |
| да | строка | Адрес электронной почты. | |
| kladr_id | нет | строка | Код КЛАДР населенного пункта. Его можно получить из справочника населенных пунктов. При отсутствии будет определен автоматически. |
| products | да | массив | Список продуктов. |
| shopArticle | да | строка | Артикул в магазине. |
| count | да | число | Количество товаров. |
| price | да | число | Цена продажи. |
| additional_service | нет | массив | Список дополнительных услуг. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "QKZZHABBYYG1PZZU",
"method" : "simpleAddPackage",
"params" : {
"stock": 1,
"length": 10,
"width": 10,
"height": 10,
"weight": 10,
"cod": 10,
"declared_cost": 10,
"external_id": "ASD123",
"departure": {
"shipping_method": 17,
"cashless_payment": true,
"comment": "Комментарий",
"address": {
"country": "RU",
"receiver": "Имя Фамилия Отчество",
"name": "Имя",
"surname": "Фамилия",
"patronymic": "Отчество",
"email": "test@example.com",
"phone": "+78005553535",
"postal_code": "101000",
"administrative_area": "Московская обл",
"settlement": "Москва",
"street": "Красная пл.",
"house": "1",
"apartment": "1",
"address_line_1": "Московская обл, Москва, Красная пл., 1, 1",
"kladr_id": "01000001000"
}
},
"products": [
{
"shopArticle": "CSV48",
"count": 20,
"price": 100
},
{
"shopArticle": "CSV10",
"count": 10,
"price": 756
},
{
"shopArticle": "CSV1",
"count": 1,
"price": 124.21
}
],
"additional_service": [
"express-gathering",
"partial-pay-out"
]
}
}
Возвращаемый ответ идентичен тому же методу.
{
"result": {
"id": 1479950,
"external_id": "ASD123",
"stock": 1,
"status": "new",
"current_status": "new",
"tracking_number": "RP1479950",
"external_tracking_number": null,
"created_at": "2019-10-23 13:26:11",
"weight": 10,
"length": 10,
"width": 10,
"height": 10,
"cod": 10,
"declared_cost": 10,
"no_gather": false,
"label_url": "https:\/\/shiptor.ru\/package\/e95a4eaa137c3fd0682700c863eaa8d0bb7ebea23c870bc3345517e6216bcca7\/label.png",
"small_label_url": "https:\/\/shiptor.ru\/package\/e95a4eaa137c3fd0682700c863eaa8d0bb7ebea23c870bc3345517e6216bcca7\/print-label?size=1",
"sberbank_payment_qr_url": "https:\/\/shiptor.ru\/package\/e95a4eaa137c3fd0682700c863eaa8d0bb7ebea23c870bc3345517e6216bcca7\/qr.png",
"postamat_load_code": null,
"cost": {
"shipping_cost": null,
"cod_service_cost": null,
"compensation_service_cost": null,
"total_cost": 0
}
}
}
Запрос, который позволяет получить информацию о заказе. Если он был передан в Shiptor, то статус будет получен из личного кабинета, если нет, то из кабинета Чекаута.
Структура запроса getOrder:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| external_id | да | строка | Идентификационный номер посылки в магазине. Обязателен, если не задан id. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6AD8XKJV2",
"method": "getOrder",
"params": {
"external_id": "201911"
}
}
В ответ в поле result придет информация о заказе. Если её не удалось найти, то в ответ вернется соответствующая ошибка.
{
"result": {
"basket": {
"items": [
{
"id": 4084,
"shopArticle": "236",
"quantity": 1,
"price": "2499.00"
}
],
"total": 1
},
"code": "201911251317-52033005",
"price": "2499.00",
"delivery_price": "309.00",
"declared_cost": "2499.00",
"tracking": null,
"weight": "0.40",
"length": "25.0",
"width": "10.0",
"height": "15.0",
"delivery": "19",
"pvz": "",
"payment": "card",
"payed": false,
"is_cod": false,
"status": "fresh",
"reciever": "тест тест тест",
"email": "test@mail.ru",
"phone": "+79999999999",
"zip": "123123",
"kladr_id": "77000000000",
"city": "Москва",
"address": null,
"region": null,
"country": "RU",
"street": "тестовая",
"house": "22",
"flat": "22",
"date_created": "25.11.2019 13:20",
"date_changed": "25.11.2019 13:20",
"comment": null,
"type": null,
"domain": "http:\/\/bitrix.shiptor.ru"
}
}
Заказ может иметь статус:
Запрос, который позволяет получить информацию о заказе. Если он был передан в Shiptor, то статус будет получен из личного кабинета, если нет, то из кабинета Чекаута.
Структура запроса getOrders:
|
Название |
Обязательное поле |
Тип |
Описание |
| wk | да | строка | Виджет-ключ. |
| method | да | строка | Название метода. |
| external_id | да | строка | Идентификационный номер посылки в магазине. Обязателен, если не задан id. |
Пример запроса:
{
"method": "getOrders",
"params": {
"external_id": [
"2019022",
"130"
]
},
"wk": "8UUD5H2D5P6A"
}
В ответ в поле result придет информация о заказах с указанныит идентификаторами.
{
"result": {
"201902201514-52036292": {
"id": 957198,
"external_id": "201902201514-52036292",
"stock": 1,
"status": "removed",
"tracking_number": "RP957198",
"created_at": "2019-02-21 12:50:49",
"weight": 0.4,
"height": 15,
"cod": 3000.21,
"no_gather": false,
"cost": {
"shipping_cost": "395.00",
"total_cost": 522.51
},
"departure": {
"shipping_method": {
"id": 59,
"name": "CDEK Дверь - ПВЗ",
"category": "door-to-delivery-point",
"group": "cdek_dt",
"courier": "cdek",
},
"address": {
"receiver": "Тестов Тест",
…
},
"delivery_days": 2,
"delivery_point": {
"id": 7507,
"courier": "cdek",
"address": "Москва, ул. Шарикоподшипниковская, 13 стр. А",
"phones": [
"+79268354377"
],
"kladr_id": "77000000000",
…
},
"130": {
"id": 1151151,
"external_id": "130",
"stock": 1,
"status": "removed",
"tracking_number": "RP1151151",
"created_at": "2019-05-29 13:01:11",
"weight": 3.3,
"length": 20,
"width": 20,
"height": 20,
"cod": 8110,
"declared_cost": 8110,
"no_gather": false,
"cost": {
"shipping_cost": "700.00",
"total_cost": 1044.68
},
"departure": {
"shipping_method": {
"id": 83,
"name": "CDEK ПВЗ Эконом",
"category": "delivery-point",
"group": "cdek_economy_delivery_point",
"courier": "cdek",
…
}
}
}
Добавляет или обновляет существующую категорию. Метод проверяет, есть ли категория с таким id или названием: если есть, обновляет её, если нет — создает новую с заданными параметрами.
Структура запроса setCategory:
| Название | Обязательное поле | Тип | Описание |
|---|---|---|---|
| wk | да | строка | Виджет-ключ |
| method | да | строка | Название метода |
| params | да | объект | Объект, содержащий тело запроса. |
| name | да | строка | Название категории |
| desc | нет | строка | Описание категории |
| parent | да | число | Идентификатор родительской категории |
| photo | нет | строка | Ссылка на изображение |
| id | нет | число | Идентификатор категории |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P",
"method": "setCategory",
"params": {
"name": "Категория",
"desc": "Описание категории",
"parent": 3,
"photo": "Ссылка"
}
}
Пример ответа:
{
"result": {
"id": 18,
"name": "Категория",
"description": "Описание категории",
"count_wares": 0,
"parent": 3,
"photo": "Ссылка"
}
}
Запрос, который позволяет получить список используемых категорий с информацией о них. Не имеет входных параметров, помимо ВК и названия метода.
Структура запроса getCategories:
| Название | Обязательное поле | Тип | Описание |
|---|---|---|---|
| wk | да | строка | Виджет-ключ |
| method | да | строка | Название метода |
| params | да | объект | Объект, содержащий тело запроса. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P",
"method": "getCategories",
"params": {}
}
Пример ответа:
{
"result": {
"18": {
"id": 18,
"name": "Тест апи категории",
"description": "Тест апи категории описание",
"count_wares": 0,
"parent": 3,
"photo": "ссылка на изображение"
}
}
}
Метод позволяет изменять данные о заказе.
Структура запроса updateOrder:
| Название | Обязательное поле | Тип | Описание |
|---|---|---|---|
| method | да | строка | Название метода. |
| wk | да | строка | Виджет-ключ. |
| domain | нет | строка | URL-адрес сайта, для которого создан отдельный магазин в КЧ. Если значение отсутствует, используются настройки для магазина по умолчанию. |
|
params |
да |
объект |
Объект, содержащий тело запроса. |
|
external_id |
да |
строка |
Идентификационный номер заказа, который необходимо обновить. |
|
length |
да |
число |
Длина посылки (см). |
|
width |
да |
число |
Ширина посылки (см). |
|
height |
да |
число |
Высота посылки (см). |
|
weight |
да |
число |
Вес посылки (кг). |
|
price |
да |
число |
Сумма по товарам в заказе. |
|
deliveryPrice |
да |
число |
Стоимость доставки. |
|
delivery_date |
нет |
строка |
Желаемая дата доставки в формате ГГГГ-ММ-ДД (для метода Сберкурьер). |
|
delivery_time |
нет |
число |
Желаемое время доставки (для метода Сберкурьер). Должен соответствовать индексу нужного временного интервала из ответа в методе getDeliveryTime. |
|
declaredCost |
да |
число |
Объявленная стоимость товаров в заказе. |
|
payed |
нет |
булев |
Признак оплаченности заказа. |
|
cod |
да |
булев |
Признак наложенного платежа. Для экспортных заказов всегда false. |
|
payment |
да |
строка |
Тип оплаты заказа: card (картой) или cash (наличными). Для экспортных заказов всегда card. |
|
departure |
да |
объект |
Объект, содержащий параметры доставки. |
|
shipping_method |
да |
целое число |
Идентификатор метода доставки. |
|
delivery_point |
нет |
строка |
Идентификатор выбранного ПВЗ, если выбран соответствующий метод доставки. |
|
comment |
нет |
строка |
Комментарий к заказу. |
|
address |
да |
объект |
Объект, содержащий адрес доставки. |
|
settlement |
да |
строка |
Наименование НП назначения. Для экспортных заказов должно быть написано латиницей. |
|
address_line |
да |
строка |
Строка вида «улица, дом, квартира» для тех случаев, когда адрес указывается в виде единой строки. Если параметр не задан, то к заполнению обязательны поля: street и house (для доставки не в ПВЗ). |
|
street |
да |
строка |
Название улицы НП назначения. Для экспортных заказов должно быть написана латиницей. |
|
house |
да |
строка |
Номер дома. |
|
apartment |
нет |
строка |
Номер квартиры. |
|
country |
да |
строка |
Двухбуквенный код страны назначения (RU, KZ, BY, ...). |
|
postal_code |
нет |
строка |
Почтовый индекс. Обязателен для Почты России и экспортных заказов. |
|
|
да |
строка |
Электронная почта получателя. |
|
phone |
да |
строка |
Номер мобильного телефона получателя. |
|
receiver |
да |
строка |
ФИО получателя. Для экспортных заказов должна быть написана латиницей. |
|
kladr_id |
да |
строка |
КЛАДР-код НП назначения из справочника Shiptor. Для экспортных заказов необязателен и игнорируется. |
|
products |
да |
массив объектов |
Массив объектов товаров в корзине с количеством и стоимостью. |
|
id |
да |
строка |
Идентификатор товара в магазине. При работе с существующими товарами должен соответствовать shopArticle. |
|
name |
нет |
строка |
Название товара. |
|
price |
да |
число |
Стоимость 1 единицы товара. |
|
quantity |
да |
целое число |
Количество единиц товара. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5",
"method": "updateOrder",
"params": {
"domain": "https://dev-crm.shiptor.ru",
"external_id" : "202010121443-52032971",
"price":15990,
"deliveryPrice": 500,
"declaredCost": 16490,
"length": 14,
"width": 2,
"height": 2.2,
"weight": 0.3,
"cod": true,
"payment": "card",
"payed": true,
"departure":{
"shipping_method": 20,
"comment": "комментарий",
"address":{
"settlement": "Москва",
"address_line":"пр-кт Труда, 45, кв.13",
"country":"RU",
"email":"test@test.ru",
"phone":"89000000000",
"receiver":"тест тест",
"kladr_id":"77000000000"
}},
"products":
[
{
"id": "xma2",
"name": "Смартфон Xiaomi Mi A2 Lite 3/32GB — Черный.",
"price": 15990.00,
"quantity":1
}
]
}
}
Пример ответа:
{
"result": {
"domain": "https:\/\/dev-crm.shiptor.ru",
"external_id": "202010121443-52032971",
"price": 15990,
"deliveryPrice": 500,
"declaredCost": 16490,
"length": 14,
"width": 2,
"height": 2.2,
"weight": 0.3,
"cod": true,
"payment": "card",
"payed": true,
"departure": {
"shipping_method": 20,
"comment": "комментарий",
"address": {
"settlement": "Москва",
"address_line": "пр-кт Труда, 45, кв.13",
"country": "RU",
"email": "test@test.ru",
"phone": "89000000000",
"receiver": "тест тест",
"kladr_id": "77000000000"
}
},
"products": [
{
"id": "xma2",
"name": "Смартфон Xiaomi Mi A2 Lite 3\/32GB — Черный.",
"price": 15990,
"quantity": 1
}
],
"id": 5579
}
}
После успешного обновления заказ получает статус «Новый».
Запрос, который позволяет получить список интервалов доставки для метода Сберкурьер. Не имеет входных параметров, помимо ВК и названия метода.
Структура запроса getDeliveryTime:
| Название | Обязательное поле | Тип | Описание |
|---|---|---|---|
| wk | да | строка | Виджет-ключ |
| method | да | строка | Название метода |
| params | да | объект | Объект, содержащий тело запроса. |
Пример запроса:
{
"id": "JsonRpcClient.js",
"jsonrpc": "2.0",
"wk": "8UUD5H2D5P6A",
"method": "getDeliveryTime",
"params": { }
}
Пример ответа:
{
"result": {
"0": "Не важно",
"1": "с 10:00 до 13:00",
"2": "с 13:00 до 18:00",
"4": "с 09:00 до 18:00",
"3": "с 18:00 до 21:00"
}
}