API «EMS Russian Post»

Оригинал статьи 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"}}