API

API предназначено для автоматического расчета стоимости и сроков доставки EMS-отправлений.

Функционирование API предполагает выполнение HTTP запросов со стороны клиентов и выдачу сервером соответствующих им результатов в формате JSON.

В настоящее время API реализует выполнение следующих методов:

  • ems.test.echo – проверка доступности сервиса;
  • ems.get.locations – получение списков идентификаторов, используемых для кодирования пунктов отправки и получения в запросах расчета стоимости доставки;
  • ems.get.max.weight – получение значения максимально допустимого веса отправления;
  • ems.calculate – расчет стоимости и сроков доставки.

I. Общая структура запроса


Все запросы к API имеют следующий формат:

http://emspost.ru/api/rest/?<набор параметров>

где <набор параметров> - набор параметров запроса, представленный в соответствии со стандартами оформления http-запросов. Параметры запросов к API разделяются на 2 типа:

  • общие параметры для всех запросов.
  • специфические параметры метода API, применяются только в запросах определенных методов.

К общим параметрам запросов относятся следующие:

  • method – обязательный параметр для любого запроса содержащий имя метода API. Допустимыми значениями являются:
    • ems.test.echo
    • ems.get.locations
    • ems.get.max.weight
    • ems.calculate
  • plain – параметр, отключающий режим кодирования символов Unicode в ответе сервера в соответствии со спецификацией JSON. Параметр не является обязательным. Допустимые значения:
    • true – кодирование не осуществляется, символы Unicode выводятся в ответ «как есть» (см. примеры далее).
  • callback – параметр, использующийся для выполнения XSS (Сross Site Sсriрting) запросов, для вызова API из JavaScript. Значением является имя функции клиента, в качестве аргументов которой должен быть подставлен ответ сервера (см. примеры далее). Параметр не является обязательным.

Специфические параметры методов описаны ниже в соответствующих разделах.

II. Ответ сервера


Ответы сервера представляют собой данные в формате JSON, соответствующие поступившему запросу. Общий вид ответа:

{"rsp":{<статус обработки запроса >,<данные ответа>}}

<статус обработки запроса > указывается в ответе в поле stat, например:

{"rsp":{"stat":"ok",<данные ответа>}}

Допустимые значения:

  • ok – запрос обработан, ответ содержит запрашиваемые данные
  • fail – при обработке запроса произошла ошибка, ответ содержит информацию об ошибке

При возникновении ошибки выводится результат вида:

{"rsp":{"stat":"fail","err":{<информация об ошибке>} }}

<информация об ошибке> содержит два поля:

  • поле code содержит код ошибки
  • поле msg содержит описание ошибки

и имеет вид:

{"rsp":{"stat":"fail","err":{"code":"101","msg":"Wrong location type. Allowed: cities, regions, countries"}}}


III. Общие примеры запросов и ответов


1. Запрос тестирования доступности:

http://emspost.ru/api/rest/?method=ems.test.echo

Ответ сервера:

{"rsp":{"stat":"ok","msg":"successeful"}}

2. Запрос тестирования доступности с установленным параметром callback:

http://emspost.ru/api/rest/?method=ems.test.echo&callback=jsonEMSApi

Ответ сервера:

jsonEMSApi({"rsp":{"stat":"ok","msg":"successeful"}})


IV. Метод ems.get.locations


Возвращает список идентификаторов, используемых для кодирования пунктов отправки и получения в запросах расчета стоимости доставки.


Специфические параметры метода


  • type (обязательный) — тип запрашиваемых местоположений. Допустимые значения:
    • cities – получить список идентификаторов городов России, для которых может быть рассчитана доставка;
    • regions– получить список идентификаторов регионов России, для которых может быть рассчитана доставка;
    • russia – получить объединенный список идентификаторов городов и регионов России, для которых может быть рассчитана доставка;
    • countries – получить список идентификаторов стран, для которых может быть рассчитана доставка.

Ответ сервера


Блок <данные ответа> для запроса ems.get.locations содержит массив locations вида:

"locations":[
<элемент местоположения> , <элемент местоположения>, … <элемент местоположения>
]

Где <элемент местоположения> - структура, содержащая 3 поля:

  • value - идентификатор местоположения.
  • name - название местоположения
  • type - тип местоположения. Допустимые значения соответствуют типу запроса: cities, regions или countries.

Например:

{"value":"city--abakan","name":"АБАКАН","type":"cities"}


Примеры использования метода


1. Получить список идентификаторов городов России в формате с отключенным кодированием Unicode-символов:

http://emspost.ru/api/rest/?method=ems.get.locations&type=cities&plain=true

Ответ сервера (в сокращенном виде):

{"rsp":{
"stat":"ok",
"locations":[
{"value":"city--abakan","name":"АБАКАН","type":"cities"},
{"value":"city--anadyr","name":"АНАДЫРЬ","type":"cities"},

... ,

{"value":"city--yaroslavl","name":"ЯРОСЛАВЛЬ","type":"cities"}
]}}

2. Получить список идентификаторов регионов. Символы Unicode по умолчанию кодируются в соответствии со стандартом JSON:

http://emspost.ru/api/rest/?method=ems.get.locations&type=regions

Ответ сервера (в сокращенном виде):

{"rsp":{
"stat":"ok","locations":[
{"value":"region--respublika-adygeja", "name":"\u0410\u0414\u042b\u0413\u0415\u042f\u0420\u0415\u0421\u041f\u0423\u0411\u041b\u0418\u041a\u0410","type":"regions"},

... ,

{"value":"region--tajmyrskij-ao", "name":"\u0422\u0410\u0419\u041c\u042b\u0420\u0421\u041a\u0418\u0419\u0414\u041e\u041b\u0413\u0410\u041d\u041e-\u041d\u0415\u041d\u0415\u0426\u041a\u0418\u0419\u0420\u0410\u0419\u041e\u041d","type":"regions"}
]}


V. Метод ems.get.max.weight


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


Специфические параметры метода


нет


Ответ сервера


<данные ответа > содержат значение max_weight, соответствующее максимально допустимому весу отправления.


Примеры использования метода


http://emspost.ru/api/rest/?method=ems.get.max.weight

Ответ сервера

"rsp":{"stat":"ok","max_weight":"31.5"}}


VI. Метод ems.calculate


Возвращает значение стоимости и сроков доставки EMS-отправления.


Специфические параметры метода


  • from (обязательный, кроме международной доставки) — идентификатор пункта отправления. Для получения списка допустимых идентификаторов используется метод ems.get.locations.
  • to (обязательный) - идентификатор пункта назначения. Для получения списка допустимых идентификаторов используется метод ems.get.locations.
  • weight (обязательный) — вес отправления. Значение не должно превышать максимально допустимый вес отправления, значение которого возвращается методом ems.get.max.weight.
  • type (обязательный для международной доставки) — тип международного отправления. Допустимые значения:
    • doc — документы (до 2-х килограм),
    • att — товарные вложения.

Ответ сервера


<данные ответа > содержат значение следующих полей:

  • price – стоимость отправления;
  • term – структура, содержащая информацию о сроках доставки внутрироссийских отправлений, состоящая из двух полей:
    • min – минимальный срок доставки;
    • max – максимальный срок доставки.

и имеют следующий вид:

"price":"630","term":{"min":"4","max":"6"}


Примеры использования метода


1. Запрос расчета стоимости и сроков доставки из Москвы в Омскую область отправления весом 1,5 кг:

http://emspost.ru/api/rest?method=ems.calculate&from=city--moskva&to=region--omskaja-oblast&weight=1.5

Ответ сервера:

{"rsp":{"stat":"ok","price":"870","term":{"min":"3","max":"5"}}}

2. Запрос стоимости доставки в Литву товарных вложений общим весом 0,5 кг:

http://emspost.ru/api/rest?method=ems.calculate&to=LT&weight=0.5&type=att

Ответ сервера:

{"rsp":{"stat":"ok","price":"1585"}}