Добавление заказа в отгрузку (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 для одного или нескольких товаров

В случае если возвращается ошибка duplicate_order_id, в ответном сообщение метода, возвращается значение parcel_id. Пример ответа с ошибкой duplicate_order_id будет выглядеть следующим образом: 

Array
    (
        [error] => Array // Массив ошибок
        (
        [duplicate_order_id] => Отправление с таким order_id уже зарегистрировано в системе!    
[warning] => Внимательно проверьте данные на ошибки! // Данная ошибка всегда возвращается если запрос не удался    
),
[parcel_id] => 17331
)