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

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

E-mail:

Пароль:

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

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

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

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

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

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

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

Перейти на главную страницу
Личный кабинет

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

Скачать API.docx

Введение

Для организации технического взаимодействия транспортной компании «Magic Trans» с клиентами и партнёрами реализован программный интерфейс (далее: 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

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

200

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

201

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

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

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

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

Описание

dictionary

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

delivery

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

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

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

Код метода: getCityList

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

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

Обяз.

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

terminal

нет

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

N - обратное

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

delivery

нет

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

N - обратное

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

name

нет

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

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

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

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

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

id

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

name

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

delivery

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

terminal

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

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

Код метода: getPackageList

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

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

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

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

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

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

id

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

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

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

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

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