Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 30 Next »

запрос save

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

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

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

#Название поляТип данныхДлинаОбязательноОписание

Секция аутентификации

1

sessionID

Текст


Да

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

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

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

1

orderReference

Текст

64

Нет

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

2

areaOfControl

Текст

255

Да

Распределительный центр. Данное поле обязательно только, если в аккаунте создано несколько распределительных центров и не настроены территории.

Если настроены территории, при создании заказов достаточно указать только адрес расположения клиента, а Максоптра, используя территории, отнесёт тот или иной заказ к соответствующему распределительному центру.

3

date

Дата


Да

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

4

client



Нет


4.1

name

Текст

255

Нет

Наименование заказчика

4.2

contactPerson

Текст

255

Нет

Контактное лицо (имя и фамилия)

4.3

contactNumber

Текст

255

Нет

Телефонный номер заказчика или контактного лица

4.4contactEmailТекст255Нет

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

Возможно указать несколько адресов электронной почты для получения уведомлений, при этом адреса указываются через точку с запятой.

4.5enableSMSNotificationЛогическийtrue/falseНетОтправлять/не отправлять СМС-уведомления клиентов на уровне заказа. Активировано по умолчанию.
4.6enableEMAILNotificationЛогическийtrue/falseНетОтправлять/не отправлять Email-уведомления клиентов на уровне заказа. Активировано по умолчанию.

5

location



Да


5.1

name

Текст

255

Да

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

5.2

address

Текст

255

Да*

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

5.3

latitude

Число

[-90;90]

Нет

Географическая широта адреса клиента, если в заказа передаются широта и долгота, то заказ будет расположен строго в соответствии с этими данными

5.4

longitude

Число

[-180;180]

Нет

Географическая долгота адреса клиента, если в заказа передаются широта и долгота, то заказ будет расположен строго в соответствии с этими данными

5.5

globalId

Текст

255

Нет

Уникальный идентификатор локации. Если в системе уже существует расположение клиента с точно таким же идентификатором, будет обновлено существующее расположение клиента и заказ будет ссылаться на обновленную запись.

5.6isVerifiedЛогическийtrue/falseНетПоле отвечает за проставление галочки "местонахождение проверено" в "расположениях клиента". true - галочка установлена, false - не установлена.
5.7enableSMSNotificationЛогическийtrue/falseНетОтправлять/не отправлять СМС-уведомления клиентов на уровне локации. Активировано по умолчанию.
5.8enableEMAILNotificationЛогическийtrue/falseНетОтправлять/не отправлять Email-уведомления клиентов на уровне локации. Активировано по умолчанию.
6schedulingZoneNameТекст255НетПоле отвечает за привязку к территории. Если поле не заполнено, происходит привязка к территории по координатам.

7

vehicleRequirements



Нет


7.1

name

Текст

255

Нет

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

8

dropWindows



Да

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

ПРИМЕЧАНИЕ!

В Максоптре доступна опция под названием Time window auto-replacement (Автозамена временных окон), которая позволяет использовать временные окна расположения клиента по умолчанию. При включенной опции поля dropWindows становятся необязательными. Если вам нужно подключить данную опцию, обратитесь в службу технической поддержки Максоптры.

В случае же, если вы хотите указать временные окра, отличающиеся от времени работы расположения клиента, используйте поля 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 (тело запроса):

<?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>
               <end>25.12.2014 19:00</end>
            </dropWindow>
         </dropWindows>
         <priority>1</priority>
         <durationDrop>02:10</durationDrop>
         <capacity>55</capacity>
         <volume>1</volume>
         <collection>false</collection>
         <additionalInstructions>Дополнительные рекоммендации</additionalInstructions>
         <stopSequence>first</stopSequence>
         <orderItems>
            <orderItem>
               <name>Пакет1</name>
               <barcode>6543216884</barcode>
            </orderItem>
            <orderItem>
               <name>Пакет2</name>
               <barcode>6111111114</barcode>
            </orderItem>
            <orderItem>
               <name>Пакет3</name>
               <barcode>666666686454666</barcode>
            </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

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

3

errors


3.1

error


3.1.1

errorCode

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

3.1.2

errorMessage

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

4

warnings


4.1

warning


4.1.1

warningCode

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

4.1.2

warningMessage

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


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

<?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>


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


  • No labels