Оригинал статьи http://www.emspost.ru/ru/corp_clients/dogovor_docements/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"}}