Для всех запросов существует единый вход в API

Для всех запросов существует единый вход в API

http://www.megaexp.ru/api.php

далее по тексту URLAPI

 

Загрузка отправлений

 

· Представляет собой отправку XML документа на URLAPI POST запроса. Кодировка XML документа должна быть UTF-8;

· В одном XML документе может быть только один заказ!

 

 

Пример запроса (далее описание полей). Обязательные поля выделены цветом:

 

<?xml version="1.0" encoding="UTF-8"?>

<document>

  <doc_type>100</doc_type>

  <key>admin</key>

<doc_date>08.05.2013 11:50:03</doc_date>

  <order>

         <registry>787687</registry>

         <megapolis>m123123</megapolis>

<agent_id>1</agent_id>

         <comment>доставить с 18 до 21 в рабочие дни</comment>

         <articles>

               <article>

                      <article_id>f324</article_id>

                      <article_name>пижама</article_name>

                      <article_price>200.56</article_price>

                      <article_weight>0.8</article_weight>

                      <article_count>44</article_count>

               </article>

               <article>

                      <article_id>f980</article_id>

                      <article_name>планшет Samsung 8.0" n5100 16gb белый</article_name>

                      <article_price>21990</article_price>

                      <article_weight>1.2</article_weight>

                      <article_count>1</article_count>

               </article>

               <article>

                      <article_id>f944</article_id>

                      <article_name>Гарнитура Plantronix m155 bluetooth multipoint</article_name>

                      <article_price>1780.99</article_price>

                      <article_weight>0.4</article_weight>

                      <article_count>9</article_count>

               </article>

         </articles>

         <option>

               <op_inventory>1</op_inventory>

               <op_category>1</op_category>

               <op_type>2</op_type>

               <op_notification></op_notification>

               <op_fragile>0</op_fragile>

               <op_packing>2</op_packing>

           <op_take>1</op_take>

         </option>

         <cost>

               <cost_delivery>38420.03</cost_delivery>

               <cost_insurance>400</cost_insurance>

               <cost_public>38420.03</cost_public>

               <cost_article>38420.03</cost_article>

         </cost>

         <dimension>

               <weight_end>38420.03</weight_end>

               <weight_article>6.4</weight_article>

               <capacity>0.8</capacity>

         </dimension>

         <person>

                               <fio>Иванов Иван Иванович</fio>

               <phone>+7(926)344-77-88</phone>

               <email>[email protected]</email>

         </person>

         <address>

               <zip>121467</zip>

               <region>Москва</region>

               <area></area>

               <city>Москва</city>

<place></place>

               <street>Ленинградский проспект</street>

               <house>3</house>

               <building>5</building>

                   <flat>78</flat>

               <office></office>

               <floor>4</floor>

               <full>г. Москва ленинградский проспект д.3 стр.5 офис 78 этаж 4</full>

         </address>

         <client>

               <client_contract>д9923-23-07-2009</client_contract>

         </client>

  </order>

</document>

 

Справочники

 

Код оператора доставки

ID	Наименование
1	EMS
2	Почта России

 

Виды приема отправлений

ID	Наименование
1	В окне приема
2	Курьером

 

Виды отправлений

ID	Наименование
1	Отправление EMS
2	Обычное отправление
3	Письмо
4	Почтовая карточка
5	Письмо 1-го класса
6	Бандероль
7	Бандероль 1-го класса
8	Посылка
9	Посылка стандартная
10	Посылка нестандартная
11	Посылка тяжеловесная
13	Посылка тяжеловесная крупногабаритная

 

Категории отправлений

ID	Наименование
1	Заказное(ая)
2	Простое
3	С наложенным платежом
4	С объявленной ценностью
5	Со страхованием

 

Вид уведомлений

ID	Наименование
1	Заказное
2	Простое

 

Вид дополнительной упаковки

ID	Наименование

- пока не поддерживается системой (ожидается)

 

Закрытие реестра

 

· Представляет собой отправку XML документа на URLAPI POST запроса. Кодировка XML документа должна быть UTF-8;

· Пользователь может принудительно закрыть сегодняшний реестр (см. описание тега <stop>), для ускорения передачи отправлений в службу логистики ООО Мегаполис. Принудительно закрыть реестры текущего дня можно строго с 8:00 текущего дня по 17:00 текущего дня. Все не закрытые реестры автоматически закрываются в 17:00 и передаются в логистическую службу ООО Мегаполис;

 

 

Пример запроса (далее описание полей). Обязательные поля выделены цветом:

 

<?xml version="1.0" encoding="UTF-8"?>

<document>

  <doc_type>101</doc_type>

  <key>admin</key>

<doc_date>08.05.2013 11:50:03</doc_date>

  <stop>1</stop>

</document>

 

Описание полей (обязательные поля выделены цветом)

Document	список	корневой элемент
	doc_type	целое число	номер формы документа, для данного документа содержит 101
	doc_date	строка	дата документа в формате [дд].[мм].[гггг] [чч]:[мм]:[сс]
	key	строка	логин клиента API. Логин выдается при заключении договора
	stop	0 или 1	Если поле содержит 1 то будет произведено принудительное закрытие реестров текущего дня. Это означает что закрытые реестры будут переданы в логистическую службу ООО Мегаполис

 

В любом случае будет возвращен документ, содержащий отправления текущего дня:

<?xml version="1.0" encoding="UTF-8"?>

<document>

  <doc_type>201</doc_type>

  <doc_date>08.07.2013 11:50:03</doc_date>

  <error>0</error>

  <orders>

         <order>

               <megapolis>m777777</megapolis>

               <registry>wwwwwwww</registry>

               <open>0</open>

         </order>

         <order>

               <megapolis>m123123</megapolis>

               <registry>wwwwwwww</registry>

               <open>0</open>

         </order>     

</orders>

</document>

 

Тег <error> - содержит общее количество ошибок, в случае успеха содержит 0.

Если значение тега <error> отлично от нуля, то документ будет содержать сообщения об ошибках например:

 

Если были ошибки то, отдаётся следующий XML документ (документ также включает данные о реестрах текущего дня):

 

<?xml version="1.0" encoding="UTF-8"?>

<document>

  <doc_type>201</doc_type>

  <doc_date>08.07.2013 11:50:03</doc_date>

  <error>1</error>

  <messages>

         <message>прием реестров на сегодня закрыт</message>

  </messages>

  <orders>

         <order>

               <megapolis>m777777</megapolis>

               <registry>wwwwwwww</registry>

               <open>0</open>

         </order>

         <order>

               <megapolis>m123123</megapolis>

               <registry>wwwwwwww</registry>

               <open>0</open>

         </order>     

  </orders>

</document>

Тег <messages> может содержать любое количество тегов <message>. В теге <message> содержится описание ошибки.

 

Расчет тарифа

 

Работа с API расчета тарифа представляет собой GET запросы вида URLAPI?[параметр1]=[значение1]&[параметр2]=[значение2]&… и т.д.

Запрос

№	Параметр GET запроса	Описание
1	geo	Возможно два варианта: 1) Передается целое число. Целочисленный идентификатор геополитического объекта в БД Мегаполис. Фактически содержит id – в качестве базового (родительского) объекта для последующей возврата данных по подчиненным объектам и (или) стоимости доставки для заданного в параметре геополитического объекта. Пример URLAPI?geo=674 2) Список. Для идентификации геополитического объекта списком наименований в соответствии с иерархией, например URLAPI?geo[]=московская область&geo[]=долгопрудный. Возвратит список подчиненных объектов и (или) стоимость доставки (в данном примере в город Долгопрудный Московской области)
2	search	Текстовая строка UTF-8. Строка, переданная в API для поиска дочерних элементов у элемента с заданным geo. Поиск осуществляется по не менее чем двум символам (буквы, цифры). При поиске проверяется совпадение по первым символам русскоязычных наименований объектов. Максимально в массиве data возвращается не более 40 найденных совпадений. Если строка поиска не задана и запрос направлен на получение информации о геополитических объектах, массив data может содержать 40 наиболее часто запрашиваемых геополитических объектов. Данные поля копируются из GET запроса к API.
9	weight	Число с плавающей точкой. Число с плавающей точкой, содержит общий вес товаров в отправлении. Если вес не задан определить стоимость доставки нельзя!
10	cost	Число с плавающей точкой, содержит объявленную стоимость отправления.
11	np	Число с плавающей точкой, содержит сумму наложенного платежа отправления.
12	npin	Наличие этого параметра говорит API что в сумму расчета тарифа доставки необходимо включить сумму наложенного платежа.
8	hash	Строка в кодировке UTF-8. Выдаётся пользователю, если для него существует специальный расчет тарифов. Служит идентификатором пользователя в API.

 

Ответ

Ответ API представляет собой JavaScript объект, передаваемый в формате JSON. В объекте могут присутствовать следующие поля:

№	Поле в объекте JavaScript	Описание
1	geo	Копируется из запроса к API
2	price	Число с плавающей точкой. Может отсутствовать в ответе. Число с плавающей точкой, содержит стоимость доставки если для элемента c заданным geo удалось её определить
3	data	Массив элементов. Может отсутствовать в ответе. Массив списка элементов. Формат элементов массива описан ниже. Максимально в массиве data возвращается не более 40 элементов для запросов геополитических объектов.
4	search	Копируется из запроса к API
6	error	Может отсутствовать в ответе. Содержит массив строк с ошибками в ходе работы API. В случае если ошибок нет содержит пустой массив.
7	message	Может отсутствовать в ответе. Содержит массив строк с сообщениями в ходе работы API.
9	weight	Копируется из запроса к API
10	cost	Копируется из запроса к API
11	np	Копируется из запроса к API
12	npin	Копируется из запроса к API
13	hash	Копируется из запроса к API

 

В поле data могут возвращаться списки геополитических объектов починенных заданному в параметре geo в соответствии с заданной строкой поиска в параметре search.

Каждый элемент массива data в ответе API представляет собой объект JavaScript с полями:

№	Поле в элементе массива data	Описание
1	id	Целое число. Обязательное поле. Целочисленный идентификатор объекта в соответствии с БД Мегаполис;
2	name	Обязательное поле. Русскоязычное наименование объекта (в случае если в списке геополитические объекты то название этого объекта) в кодировке UTF-8. Возвращаемые списки в поле data отсортированы по этому полю.
3	type	Обязательное поле. Содержит наименование типа объекта.

 

 

Трекинг отправлений

 

Получить трекинг можно только для отправлений, зарегистрированных в БД Мегаполис.

 

Работа с API по трекингу отправлений представляет собой GET запросы вида URLAPI?[параметр1]=[значение1]&[параметр2]=[значение2]&… и т.д.

Запрос

№	Параметр GET запроса	Описание
1	track	Номер отправления
2	view	Формализует форму ответа API. Может содержать значения: 1) data – данные возвращаются в формате JSON; 2) html – данные возвращаются в формате HTML;

 

Ответ

Ответ API передавается в формате установленном в параметре view запроса. Рассмотрим ответ в формате JSON, т.е. view = data, в таком случае ответ API содержит следующие поля:

№	Поле	Описание
1	code	Код отправления, присвоенный оператором доставки
2	weight	Число с плавающей точкой. Вес отправления
3	np	Сумма наложенного платежа отправления
4	oc	Сумма объявленной ценности отправления
6	zip	Почтовый индекс адреса получателя
7	done	0 или 1. 1 – признак что отправление вручено получателю или осуществлен возврат отправителю. 0 – отправление еще в пути.
9	address	Адрес получателя в сокращенном виде
10	step	Массив данных об этапах доставки отправления.

 

Массив step в ответе трекинга

№	Поле	Описание
1	date	Дата операции
2	zip	Почтовый индекс операции
3	address	Адрес операции
4	operation	Наименование операции
6	status	Статус операции

 

 

В случае если в качестве вида ответа установлен параметр view = html, ответ будет в виде HTML кода, образец:

 

URLAPI?track=4&view=html

Где «4» - это номер груза Мегаполис или ШПИ.

 

Штрихкоды

 

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

 

Для этого необходимо сделать запрос вида

URLAPI?barcode=[номер отправления].

 

Пример URLAPI?barcode=EA271453407RU

 

Можно получить изображение и распечать штрих код, поместив в поле URL браузера URL вида

URLAPI?barcode=[номер отправления]

 

Или например вставить штрих код в HTML страничку, так

<img src=” URLAPI?barcode=[номер отправления]”>

 

 

Document

список корневой элемент         application список свойства заказа

 

  id целое число

Номер заказа

products список Свойства продукта

 

  contractor строка

Контрагент-поклажедатель

  provider строка

Поставщик контрагента

  internal строка

Кот товара

  artical строка

Артикул

  nomencl строка

Номенклатура

  unit строка

Единица хранения

  amount целое число

Количество

  woVAT число с плавающей точкой

Цена без НДС, руб

  wiVAT число с плавающей точкой

Цена с НДС, руб

  rateVAT число с плавающей точкой

Ставка НДС, %

  cost число с плавающей точкой

Стоимость, руб

  note текст

Примечание

 

Если товар успешно принят и записан в БД, будет возвращен ответ:

 

<document>

<doc_type>591</doc_type>

<doc_date>20-08-2013 09:51:05</doc_date>

<error>0</error>

  <good>

  <articals>

<artical>BAN3wsesegftgsef2uk3f1f</artical>

               <amount>55</amount>

         </articals>

  </good>

</document>

 

Тег <error> - содержит общее количество ошибок, в случае успеха содержит 0.

 

 

Document

список корневой элемент           error целое число Количество ошибок, в случае успеха 0  

 

good список Номера которые были добавлены в базу  

 

  articals список Номера товаров и количество которое было успешно добавлено в базу

 

    artical строка

Артикль товара

    amount целое число

Количество добавленного товара

 

Если в заказе есть хоть одна ошибка – заказ не принимается!

 

 

При этом вы получите следующий XML документ(в котором будет указаны текущие ошибки):

 

 

<document>

<doc_type>542</doc_type>

<doc_date>20-08-2013 09:51:05</doc_date>

<error>1</error>

<errors>

<error>Этот номер не уникален</error>

  </errors>

</document>

 

№	Корневой элемент	Описание
1	doc_type	целое число	номер формы документа
2	doc_date	строка	дата документа в формате [дд].[мм].[гггг] [чч]:[мм]:[сс]
3	error	целое число	количество ошибок
4	errors	список
5		error	строка	описание ошибки

 

Document

список корневой элемент           application список    

 

  id Целое число

Номер заявки

products список    

 

  product список  

 

    keeper строка

Организация-хранитель

    bailor строка

Контрагент-поклаждатель

      act строка

Номер заказа

      coder строка

Код(получателя

      surname строка

Фамилия

      name строка

Имя

      lastname строка

Отчество

      phone строка

Телефон

      counrty строка

Страна

      region строка

Регион/область

      area строка

Район

      delivery строка

Пункт доставки

      index строка

Индекс

      street строка

Улица

      house строка

Дом/ строение

      body строка

Корпус

      floor строка

Этаж

      office строка

Офис/квартира

      codei строка

Код(внутр)

      artical строка

Артикул(код котрагента)

      attachments строка

Вид вложения

      nomencl строка

Номенклатура(наименование товара)

      unit строка

Единица хранения

      amount целое число

Количество

      implprise число с плавающей точкой

Цена реализации, руб

      implsum число с плавающей точкой

Сумма реализации, руб

      nod строка

Наименование оператора доставки

      viewdep строка

Вид отправления

      categorydep строка

Категория отправления

      aoii строка

Наличие описи вложения

      flagnotif строка

Налицие уведомления

      viewnotif строка

Вид уведомления

      flagility строка

Признак хрупкости вложения

      accpack строка

Необходимость дополнительной упаковки

      viewaccpack строка

Вид дополнительной упаковки(короб, пакет и.т.п)

      weightdep строка

Расчетный вес отправления, кг/заказ

      tdv строка

Сумма объявленной/страховой ценности, руб./строка

      codamount строка

Сумма наложенного платежа, руб./строка

      node строка

Примечания

 

В случае если заказ успешно принят и записан в БД будет возвращен ответ:

<document>

  <doc_type>593</doc_type>

  <doc_date>26-08-2013 18:11:51</doc_date>

  <error>0</error>

  <good>

         <articals>

               <artical>RU1</artical>

         <amount>1</amount>

         </articals>

  </good>

</document>

 

Тег <error> - содержит общее количество ошибок, в случае успеха содержит 0.

 

Если были ошибки то, отдаётся следующий XML документ:

 

 

<document>

<doc_type>592</doc_type>

<doc_date>20-09-2013 08:12:05</doc_date>

<error>1</error>

<errors>

<error>Этот номер не уникален</error>

  </errors>

</document>

 

 

№	Корневой элемент	Описание
1	doc_type	целое число	номер формы документа
2	doc_date	строка	дата документа в формате [дд].[мм].[гггг] [чч]:[мм]:[сс]
3	error	целое число	количество ошибок
4	errors	список
5		error	строка	описание ошибки

 

 

Выдача номеров заказов

 

Работа с API выдача номеров заказа представляет собой GET запросы вида URL API?[параметр1]=[значение1]&[параметр2]=[значение2]&… и т. д.

 

Для всех запросов существует единый вход в API

http://www.megaexp.ru/api.php

далее по тексту URLAPI

 

Загрузка отправлений

 

· Представляет собой отправку XML документа на URLAPI POST запроса. Кодировка XML документа должна быть UTF-8;

· В одном XML документе может быть только один заказ!

 

 

Пример запроса (далее описание полей). Обязательные поля выделены цветом:

 

<?xml version="1.0" encoding="UTF-8"?>

<document>

  <doc_type>100</doc_type>

  <key>admin</key>

<doc_date>08.05.2013 11:50:03</doc_date>

  <order>

         <registry>787687</registry>

         <megapolis>m123123</megapolis>

<agent_id>1</agent_id>

         <comment>доставить с 18 до 21 в рабочие дни</comment>

         <articles>

               <article>

                      <article_id>f324</article_id>

                      <article_name>пижама</article_name>

                      <article_price>200.56</article_price>

                      <article_weight>0.8</article_weight>

                      <article_count>44</article_count>

               </article>

               <article>

                      <article_id>f980</article_id>

                      <article_name>планшет Samsung 8.0" n5100 16gb белый</article_name>

                      <article_price>21990</article_price>

                      <article_weight>1.2</article_weight>

                      <article_count>1</article_count>

               </article>

               <article>

                      <article_id>f944</article_id>

                      <article_name>Гарнитура Plantronix m155 bluetooth multipoint</article_name>

                      <article_price>1780.99</article_price>

                      <article_weight>0.4</article_weight>

                      <article_count>9</article_count>

               </article>

         </articles>

         <option>

               <op_inventory>1</op_inventory>

               <op_category>1</op_category>

               <op_type>2</op_type>

               <op_notification></op_notification>

               <op_fragile>0</op_fragile>

               <op_packing>2</op_packing>

           <op_take>1</op_take>

         </option>

         <cost>

               <cost_delivery>38420.03</cost_delivery>

               <cost_insurance>400</cost_insurance>

               <cost_public>38420.03</cost_public>

               <cost_article>38420.03</cost_article>

         </cost>

         <dimension>

               <weight_end>38420.03</weight_end>

               <weight_article>6.4</weight_article>

               <capacity>0.8</capacity>

         </dimension>

         <person>

                               <fio>Иванов Иван Иванович</fio>

               <phone>+7(926)344-77-88</phone>

               <email>[email protected]</email>

         </person>

         <address>

               <zip>121467</zip>

               <region>Москва</region>

               <area></area>

               <city>Москва</city>

<place></place>

               <street>Ленинградский проспект</street>

               <house>3</house>

               <building>5</building>

                   <flat>78</flat>

               <office></office>

               <floor>4</floor>

               <full>г. Москва ленинградский проспект д.3 стр.5 офис 78 этаж 4</full>

         </address>

         <client>

               <client_contract>д9923-23-07-2009</client_contract>

         </client>

  </order>

</document>