Интеграция

Инструкция по работе с API компании МАУ

  1. Общая часть

API компании МАУ предназначен для автоматического приёма заказов на доставку посредством HTTP POST запросов в форматах XML или JSON.

Для упрощения процесса отладки существует тестовый сервер. Адрес сервера предоставляется по запросу. Адрес рабочего сервиса предоставляется после завершения интеграции и заключения договора.

  • Функции сервиса

Сервис API позволяет:

— отправить любое количество заказов для занесения их в информационную базу компании МАУ;

— проверить статусы отправленных в компанию МАУ заказов за произвольный период, с отбором по статусу или идентификатору входящего пакета . (отбор по статусу\идентификатору пока находится на стадии отладки)

  • Отправка заказов

Сервис APIпринимает заказы для занесения в информационную базу через метод POST. Каждый запрос считается сообщением. Заказы описываются реквизитами (см. п. 3.1.) и помещаются в тело запроса. При этом, чем меньше заказов будет в сообщении, тем быстрее будет получен ответ.

  • Реквизиты заказов

Для заказов, отправляемых через сервис API предусмотрены следующие реквизиты:

Обязательные поля:

orderReference – трек-номер;

pickupCity – город забора заказа;

deliveryDate — дата доставки заказа (в формате: date Тип ДАТА (http://www.w3.org/2001/XMLSchema));

deliveryCity — город доставки;

deliveryType – тип доставки (строка, может принимать следующие значения «dd или дд» — дверь/дверь, «wd или сд» — склад/дверь, «ww или сс» — склад/склад, «dw или дс» — дверь/склад);

deliveryCost – стоимость доставки (число);

deliveryTax – ставка НДС доставки (строка, может принимать значения «0/10/20/NoTax»);

deliveryTaxAmount – сумма НДС доставки (число);

clientName – имя клиента (название компании для юр. лиц);

contactPerson – контактное лицо;

contactNumber – контактный телефон (в формате);

contactEmail – адресэл. почты;

customerLocationName – местоположение клиента;

cost – стоимость (число);

prepaymentAmount – сумма внесённой предоплаты (число);

сapacity – вес заказа, кг (число);

dropWindowStart –доставка с (время, в формате time http://www.w3.org/2001/XMLSchema));

dropWindowEnd — доставка до (время, в формате time (http://www.w3.org/2001/XMLSchema));

items — товарный состав заказа со следующими обязательными полями:

name -наименование товара;

quantity –количество товара (число);

cost – стоимость товара (число);

tax: ставкаНДС товара (строка, может принимать значения «0/10/20/NoTax/БезНДС»);

taxAmount – суммаНДС (число);

Дополнительные поля:

volume – объём (число);

packLength – длина упаковки, сантиметры (число);

packWidth: ширина упаковки, сантиметры (число);

packHeight: высота упаковки, сантиметры (число);

additionalinstructions – дополнительные инструкции;

vehicleRequirements – требования к автотранспортному средству;

pickupLocationName – адрес забора заказа;

pickupDate – дата забора заказа (Тип ДАТА (http://www.w3.org/2001/XMLSchema));

needPickup – необходимость забора (булево);

latitude: географическая широта;

longitude: географическая долгота.

Item barcode – штрихкод товара$

Все реквизиты, если не указано отдельно, должны быть представлены в формате string (http://www.w3.org/2001/XMLSchema).

Числовые реквизиты представляются в формате — float (http://www.w3.org/2001/XMLSchema);

Булевы реквизиты – в формате boolean (http://www.w3.org/2001/XMLSchema).

  • Пример POST запроса

Пример запроса в формате JSON:

{«#value»: [

      {

      «orderReference»: «15727589208642»,

      «pickupCity»: «Санкт-Петербург»,

«pickupLocationName»: «Россия, Санкт-петербург, Санкт-Петербург, ул. Киевская, д. 3, квартира 623, подъезд 14, код домофона 623, этаж 17»,

      «pickupDate»: «2019-05-19T18:00:00»,

      «needPickup»: false,

«deliveryDate»: «2019-05-19T18:00:00»,

      «deliveryCity»: «СПб»,

      «deliveryType»: «dd»,

      «deliveryCost»: 249,

      «deliveryTax»: «20»,

      «deliveryTaxAmount»: 41.50,

      «clientName»: «КузнецоваПолина»,

      «contactPerson»: «КузнецоваПолина»,

      «contactNumber»: «contactNumber0»,

      «contactEmail»: «contactEmail0»,

      «customerLocationName»: «customerLocationName0»,

      «customerLocationAddress»: «customerLocationAddress0»,

      «capacity»: 0,

      «volume»: 0,

      «packWidth»: 0,

      «packHeight»: 0,

      «packLength»: 0,

      «IsPartialGiveoutDisabled»: false,

      «cost»: 320,

      «prepaymentAmount»: 320,

      «additionalinstructions»: «additionalinstructions0»,

      «vehicleRequirements»: «vehicleRequirements0»,

      «dropWindowStart»: «12:01:01»,

      «dropWindowEnd»: «15:00:00»,

      «latitude»: «latitude0»,

      «longitude»: «longitude0»,

      «items»:       [

{

«name»: «Старейшие гостиницы Петербурга (Букинистика)»,

«quantity»: 1,

            «cost»: 320,

            «tax»: «0»,

            «taxAmount»: 10,

            «barcode»: «15734689733555»

         }

      ]

   },

      {

       «orderReference»: >%101%105243504″,

      «pickupCity»: «СПб»,

      «pickupLocationName»: «Россия, 197341, Санкт-петербург, Санкт-Петербург, ул. Афанасьевская, д. 11, к. 1»,

      «pickupLocationAddress»: «Россия, 197341, Санкт-петербург, Санкт-Петербург, ул. Афанасьевская, д. 11, к. 1»,

      «pickupDate»: «2019-05-19T10:10:50»,

      «needPickup»:  true,

      «deliveryDate»: «2019-05-19T10:10:50»,

      «deliveryCity»: «deliveryCity1»,

«deliveryType»: «dd»,

      «deliveryCost»: 0,

«deliveryTax»: «0»,

      «deliveryTaxAmount»: 0,

«clientName»: «ТереховаМаргаритаЖановна»,

      «contactPerson»: «ТереховаМаргаритаЖановна»,

«contactNumber»: «contactNumber1»,

      «contactEmail»: «contactEmail1»,

      «customerLocationName»: «customerLocationName1»,

      «customerLocationAddress»: «customerLocationAddress1»,

      «capacity»: 0.5,

      «volume»: 0.04,

      «packWidth»: 0,

      «packHeight»: 0,

      «packLength»: 0,

      «IsPartialGiveoutDisabled»: false,

      «cost»: 1054.12,

      «prepaymentAmount»: 1054.12,

      «additionalinstructions»: «additionalinstructions1»,

      «vehicleRequirements»: «vehicleRequirements1»,

      «dropWindowStart»: «10:00:00»,

      «dropWindowEnd»: «17:00:00»,

«latitude»: «latitude1»,

«longitude»: «longitude1»,

      «items»:       [

                  {

            «name»: «Лакдляволос «Professionnelle», сверхсильнаяфиксация, 500 мл (Лакдляволос)»,

«quantity»: 1,

            «cost»: 436,

            «tax»: «20»,

            «taxAmount»: 0,

            «barcode»: «15841173489741»

},

                  {

            «name»: «Детский концентрированный стиральный порошок «Burti», 900 г (Стиральный порошок для детской одежды)»,

«quantity»: 2,

            «cost»: 309.06,

            «tax»: «10»,

            «taxAmount»: 0,

            «barcode»: «15953247266000»

}

      ]

   }

  • Проверка статусов заказов

Сервис API позволяет проверить статусы отправленных ранее заказов за произвольный период. Для запросов по проверке статусов используется метод GET. В заголовке запроса также должны обязательно присутствовать реквизиты XAPIKEY и ContentType. Первый содержит секретный ключ для идентификации партнера, второй может принимать одно из значений —  application/xml  или application/json. Данный реквизит влияет на формат возвращаемых данных. Тело запроса включает в себя два реквизита from и to, для отбора по дате. Значения обоих реквизитов – дата в формате гггг-мм-дд. 

  • Пример ответа сервиса API МАУ на GET запрос

Ответ отправляется в формате XML:

  • Описание взаимодействия

Взаимодействие организовано следующим образом:

Для начала нужно получить от компании МАУ логин, пароль и секретный ключ API (APIKey) – специальную шифрованную строку, которая должна быть помещена в заголовок запроса. Тип авторизации – Basic. Данные размещаются в теле сообщения в одном из форматов, XML или JSON, согласно вышеприведённому описанию.