Добавление заказа в отгрузку (parcel/insert)
Добавление заказа в отгрузку (parcel/insert)
Добавить заказ в список ожидающих отгрузки в ПВЗ (parcel/insert)
Метод позволяет зарегистрировать заказы в системе для дальнейшей отгрузки в ПВЗ.
URL запроса: https://api.multi-point.net/index.php?route=parcel/insert&api_key=XXX
(где XXX, ключ API сгенерированный в панели управления поставщика ПВЗ).
Тип запроса: POST
Параметры POST запроса
Параметр | Описание | Формат | Обязательно |
external_order_id | Внешний идентификатор отправления присвоенный в базе поставщика | строка | Нет |
point_id | Идентификатор отделения в который будет произведена отгрузка отправления | целое число | Да |
barcode | Штрих-код отправления, используется если планируется использовать собственные этикетки. Если параметр не задан, штрих-код будет присвоен автоматически/ Штрих-код не используется если в заказе добавлены упаковки packagesю | строка | Нет |
parcel_number | Номер отправления (Номер заказа в системе поставщика который передали получателю) | строка | Нет |
customer | ФИО получателя | строка | Нет |
telephone | Телефон получателя | строка | Нет |
email | E-mail получателя | строка | Нет |
total | Объявленная (оценочная) стоимость отправления, может включать в себя стоимость доставки и обязательно включает в себя итоговую стоимость всех товаров, возможные значения от 1 до 250 000 | число с плавающей точкой | Да |
delivery_price | Стоимость доставки для получателя, может быть включена в объявленную стоимость и обязательно включается в стоимость к оплате, если стоимость к оплате отличная от 0, возможные значения от 0 до 250 000 | число с плавающей точкой | Нет |
price | Стоимость к оплате, если стоимость к оплате отличная от 0, то должна включать в себя стоимость доставки + итоговую стоимость всех товаров, возможные значения от 0 до 250 000 | число с плавающей точкой | Да |
quantity | Количество упаковок (грузовых мест) в отправлении, возможные значения от 1 до n | целое число | Да |
weight | Вес отправления в граммах | целое число | Нет |
note | Примечание к отправлению для сотрудника ПВЗ | строка | Нет |
packages | Перечень упаковок (коробок) в заказе, см. структуру packages в таблице ниже | массив | Нет |
items | Перечень товаров в отправлении, см. структуру items в таблице ниже | массив | Нет |
Структура packages (не рекомендуется использовать упаковки, если в заказе 1 грузовое место)
Параметр | Описание | Формат | Обязательно |
barcode | Штрих-код или артикул упаковки, задается самостоятельно, на стороне Multi Point не генерируется | строка | Да |
weight | Вес упаковки в граммах (итоговый вес всех упаковок должен соответстовать итоговому весу заказа) | строка | Нет |
Структура items
Параметр | Описание | Формат | Обязательно |
package_barcode | Штрих-код упаковки, если упаковки были добавлены | строка | Нет |
item_barcode | Штрих-код или артикул товара | строка | Нет |
item_name | Наименование товара | строка | Да |
item_quantity | Количество единиц | целое число | Да |
item_price | Стоимость одной единицы товара | число с плавающей точкой | Да |
Пример реализации запроса на PHP с помощью CURL
$parcel = array(); $parcel['external_order_id'] = '336455QT'; // Внешний ключ отправления $parcel['point_id'] = 6; // Идентификатор отделения, обязательный параметр $parcel['barcode'] = '1223456789'; // Штрих-код отправления $parcel['parcel_number'] = 'Тест'; // Номер отправления, обязательный параметр $parcel['customer'] = 'Иванов Иван Иванович'; // ФИО получателя $parcel['telephone'] = '899933333'; // Номер телефона получателя $parcel['email'] = 'example@mail.com'; // E-mail получателя $parcel['total'] = 2000.00; // Объявленная (оценочная) стоимость, обязательный параметр $parcel['delivery_price'] = 200.00; // Стоимость доставки для получателя $parcel['price'] = 2200.00; // Итоговая стоимость к оплате $parcel['quantity'] = 1; // Количество упаковок (грузовых мест) в отправлении $parcel['weight'] = 200; // Вес отправления $parcel['note'] = 'Тест'; // Примечание для сотрудника ПВЗ $parcel['packages'] = array( // Массив упаковок array( 'barcode' => '88889999', // Штрих-код упаковки 'weight' => 150, // Вес в граммах ),
array( 'barcode' => '99998888', // Штрих-код упаковки 'weight' => 50, // Вес в граммах ), ); $parcel['items'] = array( // Массив товаров array( 'package_barcode' => '88889999', // Штрих-код упаковки 'item_barcode' => '2311313', // Штрих-код товара 'item_name' => 'Джинсы синие', // Наименование товара 'item_quantity' => 1, // Количество единиц товара 'item_price' => 1000 // Цена за единицу ), array( 'package_barcode' => '99998888', // Штрих-код упаковки 'item_barcode' => '45654644', // Штрих-код товара 'item_name' => 'Футболка белая', // Наименование товара 'item_quantity' => 1, // Количество единиц товара 'item_price' => 1000 // Цена за единицу ) ); $ch = curl_init(); curl_setopt_array($ch, array( CURLOPT_URL => 'https://api.multi-point.net/index.php?route=parcel/insert&api_key=XXX', CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_0, CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query($parcel), CURLOPT_HTTPHEADER => array('Content-Type: application/x-www-form-urlencoded') )); $response = curl_exec($ch); curl_close($ch); $result = json_decode($response, true); return $result;
Успешный результат выполнения примера
Array ( [parcel_id] => 164 // Идентификатор отправления [success] => Успешно! // Подтверждение что запрос успешно выполнен )Выполнено с ошибками (список возможных ошибок и их описание смотрите ниже в справочнике)
Array ( [error] => Array // Массив ошибок ( [point] => Отделение не найдено! // Ошибка в параметре point_id [total] => Объявленная стоимость должна соответствовать значению от 1 до 250000! // Ошибка в объявленной стоимости
[warning] => Внимательно проверьте данные на ошибки! // Данная ошибка всегда возвращается если запрос не удался
) )
Справочник ошибок
Строковый код ошибки | Текст ошибки | Возможные причины |
warning | У Вас нет прав для изменения списка отправлений! | Не передан параметр api_key или в параметре передан некорректный ключ API. Так же ошибка может возникнуть, если в панели поставщика, для пользователя, не установлены права на внесение изменений в отгрузку отправлений. |
warning | Внимательно проверьте данные на ошибки! | Один или несколько параметров не переданы или переданы некорректные значения. Основная ошибка. Возвращается всегда если запрос не удался. |
point | Отделение не найдено! | Не передан параметр point_id или в параметре передан некорректный идентификатор отделения |
duplicate_order_id | Отправление с таким order_id уже зарегистрировано в системе! | Отправление с таким внешним ключом, уже зарегистрировано в системе (дубль отправления) |
barcode | Штрих-код должен быть от 4 до 96 символов! | Не корректно передан параметр barcode |
total | Объявленная стоимость должна соответствовать значению от 1 до 250000! | Не передан параметр total или значение параметра не входит в диапазон от 1 до 250000 |
total | Объявленная стоимость должна быть равна стоимости товаров с учётом/без учёта стоимости доставки и равна или больше стоимости к оплате! | Не корректно передано значение параметра total. Ошибка возникает только если были переданы товары и итоговая стоимость товаров, с учётом или без учёта стоимость доставки, не совпадает с значением параметра total. |
price | Стоимость к оплате должна соответствовать значению от 0 до 250000! | Не передан параметр price или значением параметра не входит в диапазон от 0 до 250000 |
price | Стоимость к оплате должна быть больше или равна %s! | Исполнитель (Владелец ПВЗ) установил ограничение на минимальную сумму к оплате. Добавление заказов ниже этой стоимости запрещено. Необходимо связаться с исполнителем (владельцем ПВЗ) что бы он убрал ограничения. |
price | Стоимость к оплате должна быть равна стоимости товаров с учётом стоимости доставки или только стоимости доставки или 0.00! | Не корректно передано значение параметра price. Ошибка возникает только если были переданы товары и стоимость к оплате не равна 0 или стоимости доставки или итоговой стоимости товаров, с учётом или без учёта стоимость доставки. |
quantity | Введите количество упаковок! | Не передан параметр quantity или значение параметра не входит в диапазон от 1 до n |
item_barcode | Штрих-код или артикул должен быть от 1 до 128 символов! | Не передан или не корректно передан параметр item_barcode для одного или нескольких товаров |
item_name | Наименование товара должно быть от 1 до 128 символов! | Не передан или не корректно передан параметр item_name для одного или нескольких товаров |
item_quantity | Необходимо указать количество единиц товара! | Не передан или не корректно передан параметр item_quantity для одного или нескольких товаров |
item_price | Необходимо указать стоимость за единицу! | Не передан или не корректно передан параметр item_price для одного или нескольких товаров |
Array ( [error] => Array // Массив ошибок ( [duplicate_order_id] => Отправление с таким order_id уже зарегистрировано в системе!
[warning] => Внимательно проверьте данные на ошибки! // Данная ошибка всегда возвращается если запрос не удался
),
[parcel_id] => 17331
)