Новый график работы терминалов в Москве на прием и выдачу грузов. Подробнее >>>

По дополнительным вопросам обращайтесь по телефону +7 (495) 232 48 11 доб. 097

Скачать API.docx

Введение

Для организации технического взаимодействия транспортной компании «Мейджик Транс» с клиентами и партнёрами реализован программный интерфейс (далее: API), работающий на основе протокола HTTP.

Данное руководство ориентировано в первую очередь на технических специалистов, имеющих навыки программирования и знание основ протокола HTTP.

Общие сведения

API использует протокол HTTP для транспортировки данных. Используется два типа запросов: GET или POST (предпочтительнее последний). Все запросы являются синхронными и не зависят друг от друга. Весь функционал API разделён на методы и сгруппирован в модули.

Протокол запроса к API

Шаблон URL для запроса к API выглядит следующим образом:

#BASE_URL#/#MODULE#/#METHOD# . #FORMAT#

#BASE_URL# – путь к API (на текущий момент: http://magic-trans.ru/api/v1/, v1 – это версия API, в дальнейшем может меняться, но обратная совместимость будет сохранена)

#MODULE# – символьный код модуля, уникален в системе. Список доступных модулей отражён в таблице 1.

#METHOD# – символьный код вызываемого метода, уникален в рамках одного модуля.

#FORMAT# – формат возвращаемых данных. Система может отвечать на запросы либо в формате JSON, либо XML. По умолчанию – JSON. Если нет необходимости указывать этот параметр, то точка на конце URL также не нужна!

Примеры:

http://magic-trans.ru/api/v1/module/method – ответит в формате JSON

http://magic-trans.ru/api/v1/module/method.json – ответит в формате JSON

http://magic-trans.ru/api/v1/module/method.xml – ответит в формате XML

Протокол ответа

Объект, описывающий ответ, всегда содержит 4 ключа:


Таблица 1. Ключи ответа API

Ключ

Тип

Примечания

status

boolean

true в случае успешного исполнения запроса, false – в случае ошибки.

error

integer

код ошибки, возможные значения описаны в таблице 2. Если ошибок нет, то значение 0.

message

string

Текст с описанием ошибки.

result

mixed

Результат выполнения запроса. Формат ответа зависит от метода и запроса.

При получении данных в формате XML ответ оборачивается в тег <response/>.

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

{"status":true,"error":0,"message":null,"result":null}

Пример ответа в формате XML:

<response>
   <status>true</status>
   <error>0</error>
   <message/>
   <result/>
</response>

Коды ошибок

Таблица 2. Коды ошибок

Код ошибки

Описание

0

Нет ошибок.

1

Неизвестная ошибка.

2

Модуль не найден.

3

Метод не найден.

100

По заданному направлению перевозка грузов не осуществляется.

101

Не указан город.

102

Город не найден.

103

Не указаны обязательные параметры груза.

104

Индивидуальный расчет.

200

Не указан номер трека.

201

Номер трека не найден.

Список доступных модулей

Таблица 3. Доступные модули

Символьный код

Описание

dictionary

Справочники. Организует выдачу типовых данных, необходимых для расчёта.

delivery

Организует расчёт доставки исходя из входных параметров.

Модуль справочников.

Получение списка городов.

Код метода: getCityList

Пример URL: http://magic-trans.ru/api/v1/dictionary/getCityList

Код параметра

Обяз.

Возможные значения

terminal

нет

Y - выводить только те города, которые являются терминалами

N - обратное

не задано - все

delivery

нет

Y - выводить только те города, в которые осуществляется доставка

N - обратное

не задано - все

name

нет

Фильтрация по названию города. Можно передавать часть названия для поиска города.

Описание возвращаемого результата:

Массив объектов, описывающих города. Каждый объект содержит ключи:

Код параметра

Возможные значения

id

Числовой идентификатор города в системе «Мейджик Транс».

name

Название города.

delivery

Флаг (Y/N), показывающий, осуществляется ли доставка в данный город.

terminal

Флаг (Y/N), показывающий, является ли город терминалом.

Получение параметров для доставки по городу.

Код метода: CityDelivery

Пример URL: http://magic-trans.ru/api/v1/delivery/CityDelivery

Код параметра

Обяз.

Возможные значения

from

да

Идентификатор города отправления

См. метод dictionary/getCityList

to

да

Идентификатор города получения

См. метод dictionary/getCityList

Описание возвращаемого результата:

Массив объектов, описывающих параметры груза и цену по каждому параметру. Ключи для массивов 'to' и 'from' одинаковые. Каждый объект содержит ключи:

Код параметра

Возможные значения

from

Массив, содержащий параметры по городу отправления груза.

to

Массив, содержащий параметры по городу приема груза.

└ id

Числовой идентификатор города в системе «Мейджик Транс».

└ name

Название города в системе «Мейджик Транс».

└ PROPERTY_M_5

Цена доставки по городу для грузов меньше 5кг.

└ PROPERTY_M_50

Цена доставки по городу для грузов больше 5кг и меньше 50кг.

└ PROPERTY_M_100

Цена доставки по городу для грузов больше 50кг и меньше 100кг.

└ PROPERTY_M_200

Цена доставки по городу для грузов больше 100кг и меньше 200кг.

└ PROPERTY_M_500

Цена доставки по городу для грузов больше 200кг и меньше 500кг.

└ PROPERTY_M_1000

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

└ PROPERTY_M_1500

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

└ PROPERTY_M_2000

Цена доставки по городу для грузов больше 1500кг и меньше 2000кг.

└ PROPERTY_M_2500

Цена доставки по городу для грузов больше 2000кг и меньше 2500кг.

└ PROPERTY_M_3000

Цена доставки по городу для грузов больше 2500кг и меньше 3000кг.

└ PROPERTY_M_5000

Цена доставки по городу для грузов больше 3000кг и меньше 5000кг.

└ PROPERTY_M_7000

Цена доставки по городу для грузов больше 5000кг и меньше 7000кг.

└ PROPERTY_M_10000

Цена доставки по городу для грузов больше 7000кг и меньше 10000кг.

└ PROPERTY_M_20000

Цена доставки по городу для грузов больше 10000кг и меньше 20000кг.

└ PROPERTY_V_01

Цена доставки по городу грузов объемом меньше 0.1м3.

└ PROPERTY_V_02

Цена доставки по городу грузов объемом больше 0.1м3 и меньше 0.2м3.

└ PROPERTY_V_03

Цена доставки по городу грузов объемом больше 0.2м3 и меньше 0.3м3.

└ PROPERTY_V_05

Цена доставки по городу грузов объемом больше 0.3м3 и меньше 0.5м3.

└ PROPERTY_V_1

Цена доставки по городу грузов объемом больше 0.5м3 и меньше 1м3.

└ PROPERTY_V_2

Цена доставки по городу грузов объемом больше 1м3 и меньше 2м3.

└ PROPERTY_V_4

Цена доставки по городу грузов объемом больше 2м3 и меньше 4м3.

└ PROPERTY_V_8

Цена доставки по городу грузов объемом больше 4м3 и меньше 8м3.

└ PROPERTY_V_12

Цена доставки по городу грузов объемом больше 8м3 и меньше 12м3.

└ PROPERTY_V_14

Цена доставки по городу грузов объемом больше 12м3 и меньше 14м3.

└ PROPERTY_V_16

Цена доставки по городу грузов объемом больше 14м3 и меньше 16м3.

└ PROPERTY_V_30

Цена доставки по городу грузов объемом больше 16м3 и меньше 30м3.

└ PROPERTY_V_35

Цена доставки по городу грузов объемом больше 30м3 и меньше 35м3.

└ PROPERTY_V_40

Цена доставки по городу грузов объемом больше 35м3 и меньше 40м3.

└ PROPERTY_V_86

Цена доставки по городу грузов объемом больше 40м3 и меньше 86м3.

└ PROPERTY_dim_04_04_04

Цена доставки по городу грузов габаритами до 0,4/0,4/0,4 д/ш/в (м).

└ PROPERTY_dim_05_05_05

Цена доставки по городу грузов габаритами до 0,5/0,5/0,5 д/ш/в (м).

└ PROPERTY_dim_15_09_1

Цена доставки по городу грузов габаритами до 1,5/0,9/1 д/ш/в (м).

└ PROPERTY_dim_15_09_12

Цена доставки по городу грузов габаритами до 1,5/0,9/1,2 д/ш/в (м).

└ PROPERTY_dim_3_17_16

Цена доставки по городу грузов габаритами до 3/1,7/1,6 д/ш/в (м).

└ PROPERTY_dim_4_205_2

Цена доставки по городу грузов габаритами до 4/2,05/2 д/ш/в (м).

└ PROPERTY_dim_5_22_22

Цена доставки по городу грузов габаритами до 5/2,2/2,2 д/ш/в (м).

└ PROPERTY_dim_6_24_24

Цена доставки по городу грузов габаритами до 6/2,4/2,4 д/ш/в (м).

└ PROPERTY_dim_13_24_25

Цена доставки по городу грузов габаритами до 13/2,4/2,5 д/ш/в (м).

Получение списка упаковок.

Код метода: getPackageList

Пример URL: http://magic-trans.ru/api/v1/dictionary/getPackageList

Данный метод не принимает никаких параметров.

Описание возвращаемого результата:

Массив объектов, описывающих упаковку. Каждый объект содержит ключи:

Код параметра

Возможные значения

id

Числовой идентификатор упаковки в системе «Мейджик Транс».

name

Название вида упаковки.

Модуль расчёта.

Детальный расчёт

Код метода: calculate

Пример URL: http://magic-trans.ru/api/v1/delivery/calculate

Параметры:

Код параметра

Обяз.

Описание

from

да

Идентификатор города отправления.

См. метод dictionary/getCityList

to

да

Идентификатор города назначения.

См. метод dictionary/getCityList

regime

нет

Режимный груз.

Y – да

N – нет (по умолчанию)

price

нет

Объявленная стоимость груза, руб.

package

нет

Идентификатор дополнительной упаковки.

См. метод dictionary/getPackageList

items

да

Массив объектов с описанием параметров позиций груза. Каждый объект должен содержать ключи:

└ count

нет

Количество мест. По умолчанию – 1.

└ weight

да

Вес одной позиции, кг

└ volume

да*

Объём груза одной позиции, м3

└ length

да*

Длина позиции, м

└ width

да*

Ширина позиции, м

└ height

да*

Высота позиции, м

* Необходимо указывать либо объём, либо длину, ширину и высоту. Если указаны габариты, то объём будет рассчитан автоматически из приведённых данных.

Описание возвращаемого результата:

Объект, содержащий ключи:

Код параметра

Возможные значения

price

Общая стоимость перевозки, руб.

min

Минимальный срок доставки, дней.

max

Максимальный срок доставки, дней.

routes

Массив объектов, описывающих маршрут перевозки. В каждом объекте содержатся ключи:

└ from

Объект, описывающий город отправления. Объект содержит ключи:

└ id

Идентификатор города.

└ name

Название города.

└ to

Объект, описывающий город назначения. Объект содержит ключи:

└ id

Идентификатор города.

└ name

Название города.

└ price

Стоимость перевозки по этому маршруту, руб.

└ min

Минимальный срок доставки, дней.

└ max

Максимальный срок доставки, дней.

Отслеживание груза

Код метода: getOrderInfo

Пример URL: http://magic-trans.ru/api/v1/delivery/getOrderInfo

Параметры:

Код параметра

Обяз.

Описание

track

да

Номер трека.

Описание возвращаемого результата:

Объект, содержащий ключи:

Код параметра

Возможные значения

track

Номер трека.

date

Дата и время создания акта.

act

Номер акта.

marking

Маркировка груза.

status

Статус груза.

location

Текущее расположение.

estimation_date

Ориентировочная дата получения груза.

Пример использования API

Пример расчета стоимости перевозки

О компании
Услуги
Сервисы
Тарифы и сроки
Документы
Контакты

Вход в личный кабинет

E-mail:

Пароль:

У вас еще нет личного кабинета?
Заполните, пожалуйста, регистрационную форму.

Выберите ваш регион

Спасибо, за Ваш отзыв!

Мы признательны за положительную оценку нашей работы!

Перейти на главную страницу

Спасибо, что указали нам
на проблему!

Ваше обращение будет рассмотрено в ближайшее время. Мы свяжемся с Вами по указанным контактам. Номер вашего обращения: 332

Перейти на главную страницу

Спасибо, за ваше обращение!

Мы перезвоним Вам в ближайшее время!

Перейти на главную страницу