Интеграция

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

Общая часть

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. В заголовке запроса также должны обязательно присутствовать реквизиты X—API—KEY и Content—Type. Первый содержит секретный ключ для идентификации партнера, второй может принимать одно из значений — application/xml или application/json. Данный реквизит влияет на формат возвращаемых данных. Тело запроса включает в себя два реквизита from и to, для отбора по дате. Значения обоих реквизитов – дата в формате гггг-мм-дд.

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

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

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

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

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