Page Comparison

запрос save

Для создания и редактирования заказов по API используется структура application/xml и HTTP-метод POST.

Входные данные запроса save

...

Не рекомендуется создавать более 1000 заказов за один запрос.

Примечание Если вы хотите создать целое расписание из заранее назначенных заказов, вам следует сначала создать отдельные заказы с помощью метода save, а потмом назначить из на нужные даты и машины с помощью метода import.

Входные данные запроса save

#	Название поля	Тип данных	Длина	Обязательно	Пример	Описание
Секция аутентификации
1	sessionID	Текст

4.

Да

Идентификатор сессии, полученный от сервера после запроса авторизации.

Срок жизни сессии – 5 минут. Если в течении этого времени в рамках сессии были проведены запросы, то срок жизни сессии увеличивается еще на 5 минут

Секция заказов

1

orderReference

Текст

64

Нет

mID6890394

Внешняя ссылка (Поле "Идентификатор заказа" в приложении). Идентификатор заказа не должен содержать символ «*», если в дальнейшем планируется использование метода getOrderStatuses

2

areaOfControl

Текст

255

Да

Распределительный центр.

3

date

Дата

Да

Дата окна разгрузки. Формат зависит от локализации в конфигурации аккаунта. Например, для Англии формат - “DD/MM/YYYY”. Для России - “ДД.MM.ГГГГ”

4

client

Нет

Примечание Все идентификационные номера заказов, передаваемые в систему с помощью данного метода, должны быть уникальными!
2	areaOfControl	Текст	255	Да	Ногинск	Распределительный центр. Данное поле обязательно только, если в аккаунте создано несколько распределительных центров и не настроены территории. Если настроены территории, при создании заказов достаточно указать только адрес расположения клиента, а Максоптра, используя территории, отнесёт тот или иной заказ к соответствующему распределительному центру.
3	date	Дата		Да	12.12.2019	Дата временного окна доставки/сбора. Формат - “DD.MM.YYYY”.
4	client			Нет
4.1	name	Текст	255	Нет	ИП Нестерова	Наименование заказчика
4.2	contactPerson	Текст	255	Нет	Нестерова Н.П.	Контактное лицо (имя и фамилия)
4.3	contactNumber	Текст	255	Нет	+70000000001	Телефонный номер заказчика или контактного лица
4.4	contactEmail	Текст	255	Нет

Контактное лицо адрес

nn75max@gamail.com

Адрес электронной почты

5

location

Да

5.1

name

Текст

255

Да

Название местоположения клиента. Поле обязательно если не указан globalId.

5.2

address

клиента. Возможно указать несколько адресов электронной почты для получения уведомлений, при этом адреса указываются через точку с запятой.
4.5	enableSMSNotification	Логический	true/false	Нет	Отправлять/не отправлять СМС-уведомления клиентов на уровне заказа. Активировано по умолчанию.
4.6	enableEMAILNotification	Логический	true/false	Нет	Отправлять/не отправлять Email-уведомления клиентов на уровне заказа. Активировано по умолчанию.
5	location			Да
5.1	name	Текст	255	Да

*Адрес клиента (точки где должна быть произведена разгрузка

ИП Нестерова (Вятская 15)

Название местоположения клиента. Поле обязательно, если не указан globalId.

5.2

address

Текст

255

Да*

Москва, ул. Вятская 15

или

помощь.стебель.ставка

Адрес клиента (точки где должна быть произведена разгрузка для заказов вида доставка или погрузка для заказов вида сбор). Поле обязательно если не указан globalId

, однако при незаполненном name клиентская локация не создается5

. Примечание Максоптра поддерживает формат кодирования адреса по системе What3Words. Если вы хотите использовать эту интеграцию, свяжитесь с командой техподдержки Максоптры. После этого вы сможете указывать в качестве адреса расположения клиента код из трех слов.
5.3	latitude	Число	[-90;90]	Нет	55.794178	Географическая широта адреса клиента, если в заказа передаются широта и долгота, то заказ будет расположен строго в соответствии с этими данными
5.4	longitude	Число	[-180;180]	Нет	37.582843	Географическая долгота адреса клиента, если в заказа передаются широта и долгота, то заказ будет расположен строго в соответствии с этими данными
5.5	globalId	Текст	255	Нет	72483236700	Уникальный идентификатор локации. Если в системе уже существует расположение клиента с точно таким же идентификатором, будет обновлено существующее расположение клиента и заказ будет ссылаться на обновленную запись.

5.6

См. также Идентификатор расположения клиента.
5.6	isVerified	Логический	true

-

/false

Нет

Поле отвечает за проставление галочки "местонахождение проверено" в "расположениях клиента". true - галочка установлена, false - не установлена.

6

5.7

schedulingZoneName

enableSMSNotification

Текст

Логический

255

true/false

Нет

Поле отвечает за привязку к территории. Если поле не заполнено, происходит привязка к территории по координатам.

7

vehicleRequirements

Нет

7.1

name

Текст

255

Нет

Наименование требования к транспортным средствам.

8

dropWindows

Да

Конструкция, содержащая информацию о допустимых окнах для разгрузки/погрузки товара на территории клиента. Каждая должна содержать в себе минимум одну конструкцию dropWindow, ее описание приведено ниже. Если заказ имеет несколько допустимых окон, то заказ должен содержать несколько конструкций dropWindow вложенных в одну dropWindows

8.1

dropWindow

Да

Конструкция, содержащая информацию об одном окне для разгрузки/погрузки товара на территории клиента. Должна содержать в себе 2 параметра: start и end, описание параметров приведено ниже.

8.1.1

start

Дата и время

Да

Начало временного окна для работы в пункте назначения. Формат зависит от локализации в конфигурации аккаунта. Например, для Англии формат - “DD/MM/YYYY HH:MM”. Для России - “ДД.ММ.ГГГГ ЧЧ:ММ”

8.1.2

end

Дата и время

Да

Окончание временного окна для работы в пункте назначения. Формат зависит от локализации в конфигурации аккаунта. Например, для Англии формат - “DD/MM/YYYY HH:MM”. Для России - “ДД.ММ.ГГГГ ЧЧ:ММ”

9

priority

Число

1

Нет

Приоритет заказа. Возможные значения: 1, 2, 3. Значения определяют приоритет по следующей шкале:

1 – Низкий

2 – Средний

3 – Высокий

Если значение будет пропущено, то в системе заказу автоматически будет проставлен "Средний" приоритет.

10

durationDrop

Время

Нет

Продолжительность разгрузки/погрузки у клиента, формат: ЧЧ:ММ

11

price

Число

255

Нет

Стоимость заказа. Тут указывается стоимость для клиента, она не берется в рассчет при составлении расписания. Поле носит информативный характер

12

capacity

Число

Нет

Первая единица измерения заказа, конфигурируется для каждого аккаунта отдельно. По умолчанию - Вес заказа

13

volume

Число

Нет

Вторая единица измерения заказа, конфигурируется для каждого аккаунта отдельно. По умолчанию - Объем заказа

14

collection

Логический

true/false

Нет

Признак определяющий вид заказа. Возможные значения: true/false.

Если указан true, создается заказ вида сбор, Если указан false, создается заказ вида доставка.

В случае отсутствия значения, автоматически будет проставлено значение false и создан заказ вида доставка.

15

additionalinstructions

Текст

255

Нет

Дополнительные инструкции

16

orderItems

16.1

orderItem

16.1.1

name

Текст

255

Нет

Наименование товара

16.1.2

barcode

Текст

255

Да

Поле обязательно если запрос содержит orderItem.

Штрих-код товара

17

dynamicAttributes

Нет

Данная секция может включать в себя перечень уникальных полей которые были добавлены для конкретного аккаунта через дополнительную конфигурацию

17.1

attribute

17.1.1

Атрибут “name”

255

Название дополнительного поля

17.1.2

Атрибут “value”

255

Значение для дополнительного поля

18

stopSequence

Текст

Нет

Предпочтительное положение в рейсе при составлении расписания. Возможные значение:

first – Заказ должен выполняться первым
last – Заказ должен выполняться последним
any – заказ может находиться на любой позиции в рейсе

Пример запроса save

Заголовки:

URL: /rest/2/distribution-api/orders/save

Метод: POST

Структура: application/xml

XML (тело запроса):

...

language	xml

...

Отправлять/не отправлять СМС-уведомления клиентов на уровне локации. Активировано по умолчанию.
5.8	enableEMAILNotification	Логический	true/false	Нет		Отправлять/не отправлять Email-уведомления клиентов на уровне локации. Активировано по умолчанию.
5.9	consignmentReference	Число	111	Да (для заказов Pickup & Delivery)	2486238149881481216	Номер группового заказа. Предоставляется из CRM клиента. Примечание Номер группового заказа должен быть уникальным на весь аккаунт. См. подробне в разделе Функциональность Pickup & Delivery.
5.10	consignmentLinkType	Текст	PickupAndDelivery	Да (для заказов Pickup & Delivery)	PickupAndDelivery	Тип связи между заказами. Данное поле явлется обязательным, если указан ConsignmentReference. Если тип связи не указан, то групповой заказ не формируется, и связанные заказы рассматриваются системой как два одиночных заказа. См. подробне в разделе Функциональность Pickup & Delivery.
6	schedulingZoneName	Текст	255	Нет	А	Поле отвечает за привязку к территории. Если поле не заполнено, происходит привязка к территории по координатам.
7	vehicleRequirements			Нет
7.1.	vehicleRequirement			Нет
7.1.1	name	Текст	255	Нет	Загрузка сзади	Наименование требования к транспортным средствам.
8	dropWindows			Да		Конструкция, содержащая информацию о допустимых окнах для разгрузки/погрузки товара на территории клиента. Каждая должна содержать в себе минимум одну конструкцию dropWindow, ее описание приведено ниже. Если заказ имеет несколько допустимых окон, то заказ должен содержать несколько конструкций dropWindow вложенных в одну dropWindows. Для многодневного планирования заказов следует указать временные окна с разными датами. ПРИМЕЧАНИЕ! В Максоптре доступна опция под названием Time window auto-replacement (Автозамена временных окон), которая позволяет использовать временные окна расположения клиента по умолчанию. Тогда (при включенной опции) поля dropWindows становятся необязательными. Если вам нужно подключить данную опцию, обратитесь в службу технической поддержки Максоптры. В случае же, если вы хотите указать временные окна, отличающиеся от времени работы расположения клиента, используйте поля dropWindows.
8.1	dropWindow			Да		Конструкция, содержащая информацию об одном окне для разгрузки/погрузки товара на территории клиента. Должна содержать в себе 2 параметра: start и end, описание параметров приведено ниже. Для многодневного планирования заказов укажите временные окна с разными датами.
8.1.1	start	Дата и время		Да	12/12/2019 8:00	Начало временного окна для работы в пункте назначения. Формат - “DD/MM/YYYY HH:MM”.
8.1.2	end	Дата и время		Да	12/12/2019 20:00	Окончание временного окна для работы в пункте назначения. Формат зависит от локализации в конфигурации аккаунта. Например, для Англии формат - “DD/MM/YYYY HH:MM”. Для России - “ДД.ММ.ГГГГ ЧЧ:ММ”
9	priority	Число	1	Нет	3	Приоритет заказа. Возможные значения: 1, 2, 3. Значения определяют приоритет по следующей шкале: 1 – Низкий 2 – Средний 3 – Высокий Если значение будет пропущено, то в системе заказу автоматически будет проставлен "Средний" приоритет. Подробне см. в разделе Уровни приоритетности заказов.
10	durationDrop	Время		Нет	00:15	Продолжительность разгрузки/погрузки у клиента, формат: ЧЧ:ММ
11	price	Число	255	Нет	3500.00	Стоимость заказа. Тут указывается стоимость для клиента, она не берется в рассчет при составлении расписания. Поле носит информативный характер
12	capacity	Число		Нет	1000	Первая единица измерения заказа, конфигурируется для каждого аккаунта отдельно. По умолчанию - Вес заказа
13	volume	Число		Нет	100	Вторая единица измерения заказа, конфигурируется для каждого аккаунта отдельно. По умолчанию - Объем заказа
14	collection	Логический	true/false	Нет		Признак определяющий вид заказа. Возможные значения: true/false. Если указан true, создается заказ вида сбор, Если указан false, создается заказ вида доставка. В случае отсутствия значения, автоматически будет проставлено значение false и создан заказ вида доставка.
15	additionalInstructions	Текст	255	Нет	Проверить целостность упаковки	Дополнительные инструкции
16	orderItems
16.1	orderItem					Товары - это отдельные позиции, входящие в один заказ (см.Параметр "Товары"). Раздел orderItems метода save состоит из нескольких полей: name, barcode, externalId, costPerUnit, quantity, description (см. ниже). Ни одно из этих полей не является обязательным. Если в заказе несколько товаров, каждый товар должен быть записан в отдельном тэге.
16.1.1	name	Текст	255	Нет	Шампанское "Лев Голицин", полусладкое	Наименование товара
16.1.2	barcode	Текст	255	Нет	3573994003328	Штрих-код товара (если есть).
16.1.3	externalId	Текст	255	Нет	ЛГШ05	Внешний идентификатор заказа (если есть).
16.1.4	costPerUnit	Текст	255	Нет	259.00	Цена за единицу товара (напр. за штуку, кг, коробку и т.д.)
16.1.5	quantity	Текст	255	Нет	20	Запланированное колчиество товаров в составе заказа, которое необходимо доставить клиенту.
16.1.6	description	Текст	255	Нет	Не бросать	Дополнительные сведения о товаре
17	dynamicAttributes			Нет		Данная секция может включать в себя перечень уникальных полей которые были добавлены для конкретного аккаунта через дополнительную конфигурацию
17.1	attribute
17.1.1	Атрибут “name”		255		Номер EMEI	Название дополнительного поля
17.1.2	Атрибут “value”		255		490154203237518	Значение для дополнительного поля
18	stopSequence	Текст		Нет	any	Предпочтительное положение в рейсе при составлении расписания. Возможные значение: first – заказ должен выполняться первым last – заказ должен выполняться последним any – заказ может находиться на любой позиции в рейсе. Данное значение указывается по умолчанию

Редактирование заказов через API

Через API вы можете редактировать запланированные, но НЕЗАФИКСИРОВАННЫЕ заказы. До того, как расписание будет зафиксировано, вы можете поменять любые параметры заказа, не влияющие на планирование. Данный параметр обновится в Максоптре автоматически.

Редактируемые параметры заказов через API:

Товары
Дополнительные указания
Заказчик
Контактное лицо
Телефон контакта
E-mail контакта
Динамические атрибуты

Нередактируемые параметры заказов через API:

Идентификатор заказа (наименование заказа) - На самом деле, вы можете отредактировать номер заказа, но в этом случае система просто создаст новый заказ с теми же параметрами.
Склад (распределительный центр)
Куда (адрес заказа)
Дата
Приоритет
Требования к ТС
Территория
Порядок в маршруте
Временные окна операции
Вес/Объём
Продолжительность операции
Тип заказа (сбор/доставка)

Если вы попытаетесь обновить через API поля, которые не разрешены к редактированию у запланированных заказов, появится ошибка: 1103 - "Заказ с таким идентификатором уже запланирован". Вам придется отпланировать заказ, отредактировать его, а затем запланировать заново.

Подробнее см. в разделе Редактирование запланированных заказов.

Пример запроса save

Заголовки:

Метод: POST

URL: [account-name].maxoptra.com/rest/2/distribution-api/orders/save

Структура: application/xml

XML (тело запроса):

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<apiRequest>
   <sessionID>8aa519d2c0af4f37a27a42a995528199</sessionID>
   <orders>
      <order>
         <orderReference>Test 001</orderReference>
         <areaOfControl>РЦ Самара</areaOfControl>
         <date>25.12.2014</date>
         <client>
            <name>ООО "Александр"</name>
            <contactPerson>Александр</contactPerson>
            <contactNumber>+7 927 123 45 67</contactNumber>
            <contactEmail>sergey@mail.ru</contactEmail>
         </client>
         <location>
            <name>Офис ООО "Александр"</name>
            <address>Россия, Самара, проспект Ленина, 14</address>
            <latitude>53.696</latitude>
            <longitude>-2.653</longitude>
            <globalId>1234567890</globalId>
            <isVerified>true</isVerified>
         </location>
         <schedulingZoneName>Center</schedulingZoneName>
         <vehicleRequirements>
            <vehicleRequirement name="Заморозка" />
            <vehicleRequirement name="Side-loading" />
         </vehicleRequirements>
         <dropWindows>
            <dropWindow>
               <start>25.12.2014 08:00</start>
               <end>25.12.2014 12:00</end>
            </dropWindow>
            <dropWindow>
               <start>25.12.2014 13:00</start>
               <orderReference>Test 001</orderReference><end>25.12.2014 19:00</end>
           <areaOfControl>РЦ Самара<</areaOfControl>dropWindow>
          <date>25.12.2014</date>  <dropWindow>
       <client>        <start>26.12.2014 08:00</start>
   <name>ООО "Александр"</name>             <contactPerson>Александр</contactPerson><end>26.12.2014 12:00</end>
            <contactNumber>+7 927 123 45 67</contactNumber></dropWindow>
            <dropWindow>
</client>          <location>       <start>26.12.2014 13:00</start>
     <name>Офис ООО "Александр"</name>        <end>26.12.2014 19:00</end>
   <address>Россия,   Самара, проспект Ленина, 14</address>   </dropWindow>
         <latitude>53.696<</latitude>dropWindows>
         <priority>1</priority>
  <longitude>-2.653</longitude>       <durationDrop>02:10</durationDrop>
     <globalId>1234567890</globalId>    <capacity>55</capacity>
         <isVerified>true<<volume>1</isVerified>volume>
         <<collection>false</location>collection>
         <additionalInstructions>Дополнительные <schedulingZoneName>Center<рекоммендации</schedulingZoneName>additionalInstructions>
         <vehicleRequirements><stopSequence>Последний</stopSequence>
          <orderItems>
 <vehicleRequirement name="Заморозка" />         <orderItem>
   <vehicleRequirement name="Side-loading" />          <<name>Пакет1</vehicleRequirements>name>
         <dropWindows>      <barcode>6543216884</barcode>
      <dropWindow>      </orderItem>
         <start>25.12.2014 08:00</start>
   <orderItem>
              <end>25.12.2014 12:00</end> <name>Пакет2</name>
               <<barcode>6111111114</dropWindow>barcode>
            <dropWindow>   <externalId>test_1</externalId>  
          <start>25.12.2014 13:00</start>    <costPerUnit>50</costPerUnit>  
         <end>25.12.2014 19:00</end>     <quantity>10</quantity>   
    </dropWindow>          </dropWindows> <description>Оставить перед дверью</description>
      <priority>1</priority>      </orderItem>
   <durationDrop>02:10</durationDrop>         <orderItem>
<capacity>55</capacity>          <volume>1</volume>     <name>Пакет3</name>
    <collection>false</collection>          <additionalInstructions>Дополнительные рекоммендации<<barcode>666666686454666</additionalInstructions>barcode>
          <stopSequence>first</stopSequence>     <externalId>test_2</externalId>  
  <orderItems>             <orderItem><costPerUnit>30</costPerUnit>
               <name>Пакет<<quantity>20</name>quantity>
               <description>Не <barcode>654321684<кантовать!</barcode>description>
            </orderItem>
         </orderItems>
         <dynamicAttributes>
            <attribute name="Manager" value="Антон Васильев" />
            <attribute name="Code" value="1234" />
         </dynamicAttributes>
      </order>
   </orders>
</apiRequest>

...

ответ save

Для создания и редактирования заказа в текущем решении API использует структуру application/xml в качестве структуры ответа.

Выходные данные ответа save

#	Название поля	Описание
1	orderReference	Внешняя ссылка (Поле «Идентификатор заказа» в

приложении

Максоптре)
2	status	Статус выполняемой операции для указанного заказа. Возможные значения представлены в

Приложении 1

разделе "Статусы операций создания, редактирования и удаления".
3	errors


3.1	error


3.1.1	errorCode	Код ошибки. Возможные значения представлены в

Приложении 2

разделе "Коды ошибок и предупреждений".
3.1.2	errorMessage	Описание ошибки. Возможные значения представлены в

Приложении 2

разделе "Коды ошибок и предупреждений".
4	warnings


4.1	warning


4.1.1	warningCode	Код предупреждения Возможные значения представлены в

Приложении 2

разделе "Коды ошибок и предупреждений".
4.1.2	warningMessage	Описание предупреждения. Возможные значения представлены

в Приложении 2.

...

в разделе "Коды ошибок и предупреждений".

Пример ответа save

Code Block

language	xml

<?xml version="1.0" encoding="UTF-8"?>
<apiResponse>
   <orders>
      <order>
         <orderReference>Order 001</orderReference>
         <status>Created</status>
         <errors>
            <error>
               <errorCode />
               <errorMessage />
            </error>
         </errors>
         <warnings>
            <warning>
               <warningCode />
               <warningMessage />
            </warning>
         </warnings>
      </order>
   </orders>
</apiResponse>

...

*Следует отметить что предупреждения не влияют на создание заказа и несут в себе исключительно информационную нагрузку.

...

См. также

Методы API. Заказы

import

Статусы заказов

Статусы операций создания, редактирования и удаления заказов

Коды ошибок и предупреждений

Редактирование запланированных заказов

Управление настройками уведомлений

Функциональность Pickup & Delivery