Интеграция
Инструкция по работе с 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, согласно вышеприведённому описанию.