Описание API 2.1

Примеры запросов

Вы можете щелкнуть по ссылкам и посмотреть ответ сервера в читабельном виде.

Пример 1. Минимальный запрос, указаны индексы почтовых отделений

Указаны почтовый индекс отправителя и получателя, вес - 1000 г, ценность - 0 рублей. Остальные параметры будут установлены по умолчанию.
http://api.postcalc.ru/?f=101000&t=190000&w=1000&v=0&key=test

Исчерпывающий список почтовых индексов, используемых Postcalc.RU в данный момент, можно:

Посмотреть онлайн.
Скачать в виде дампа таблицы MySQL.
Скачать упрощенную версию в виде текста или дампа MySQL для Postcalc Light (таблица postcalc_light_post_indexes).

Примечание 1. В данном примере отсутствует переменная запроса p= (виды почтовых отправлений). Были подставленны значения по умолчанию - в текущей версии API это следующие 5 отправлений: ценная бандероль, ценная бандероль 1 класса, ценная посылка, ценная посылка 1 класса, курьерская доставка EMS. Настоятельно рекомендуется задавать список отправлений в явном виде, так как в последующих выпусках API переменная p= станет строго обязательной.

Примечание 2. Обратите внимание, что ценная бандероль и ценная бандероль 1 класса вернут ошибку расчета, так как их оценка не может быть менее 1 рубля.

Пример 2. Минимальный запрос, указаны ключи населенных пунктов

Минимальный запрос, вместо почтового индекса указаны ключи населенных пунктов на русском или английском языках, вес - 1000 г, ценность - 1000 рублей.
http://api.postcalc.ru/?f=Москва&t=Санкт-Петербург&w=1000&v=1000&key=test
http://api.postcalc.ru/?f=Сергиев_Посад,_50&t=Новокузнецк,_42&w=1000&v=1000&key=test
http://api.postcalc.ru/?f=Sergiyev_Posad,_50&t=Novokuznetsk,_42&w=1000&v=1000&key=test

Ключи населенных пунктов:

Для центров регионов состоят из названия населенного пункта: Москва, Самара, Благовещенск.
Для прочих населенных пунктов состоят из его названия и номера региона через запятую: Сергиев Посад, 50; Благовещенск, 2 (город в Башкортостане), Самара, 38 (село в Иркутской области); Самара, 79 (село в Еврейской АО).
Если в пределах одного региона находятся несколько населенных пунктов с одним названием, то через запятую добавляется район: Михайловка, 2, Абзелиловский; Михайловка, 2, Архангельский; Михайловка, 2, Бакалинский.

В ключе населенного пункта вместо номера региона можно указать его название (старый формат запроса), например: Сургут, Ханты-Мансийский-Югра автономный округ; Сергиев Посад, Московская область. Однако так делать не рекомендуется, так как это ухудшает читаемость и удлиняет строку запроса, кроме того, у регионов имеются альтернативные названия и они могут меняться.

Исчерпывающий список ключей населенных пунктов, используемых Postcalc.RU в данный момент, можно:

Посмотреть онлайн.
Скачать в формате дампа таблицы MySQL.
Скачать упрощенную версию в "старом" формате (вместо номера региона указано название) в виде текста или дампа MySQL для Postcalc Light (таблица postcalc_light_cities). "Старый" формат будет поддерживаться в течение 2021 года, далее поддержка не гарантируется.

Примечание. Если в переменной f= (или t=) указан не конкретный почтовый индекс, а населенный пункт, API самостоятельно ищет почтовые отделения, из которых/в которые можно отправить данный вид посылок. Это прежде всего относится к отправлениям для корпоративных клиентов, поскольку они принимаются и выдаются не во всех отделениях связи.
Например, если вы отправляете из московского отделения 105005 в отделение 190000 Посылку Онлайн, то запрос
http://api.postcalc.ru/?f=105005&t=190000&w=1000&v=1000&p=po&key=test
- вернет ошибку, так как в отделении 105005 приема Посылки Онлайн нет.
В то же время запрос
http://api.postcalc.ru/?f=Москва&t=190000&w=1000v=1000&p=po&key=test
- вернет корректный расчет, так как API самостоятельно найдет в пределах Москвы отделение связи, откуда можно отправить Посылку Онлайн.
Аналогично, запрос на доставку ЕКОМ в 190000 вернет ошибку, так как в 190000 ЕКОМ не выдается:
http://api.postcalc.ru/?f=105005&t=190000&w=1000&v=1000&p=ek&key=test
А запрос на доставку в Санкт-Петербург вернет правильный расчет:
http://api.postcalc.ru/?f=101000&t=Санкт-Петербург&w=1000v=1000&p=ek&key=test

Пример 3. Минимальный запрос на международную отправку

В параметре t= в этом случае задается название страны или код из 2 букв.
http://api.postcalc.ru/?f=Москва&t=DE&w=1000&v=0&key=test
http://api.postcalc.ru/?f=Москва&t=Германия&w=1000&v=0&key=test
Исчерпывающий список кодов и названий стран, используемых Postcalc.RU в данный момент, можно:

Посмотреть онлайн.
Скачать в виде дампа таблицы MySQL.
Скачать упрощенную версию в виде текста или дампа MySQL для Postcalc Light (таблица postcalc_light_countries).

Примечание. В предыдущих версиях API название страны задавалось в отдельной переменной c= в виде кода страны из 2 букв. Совместимость будет поддерживаться в течение 2021 года.

Пример 4. Расчет для физического лица без договора с Почтой России

http://api.postcalc.ru/?f=101000&t=190000&w=1000&v=1000&key=test&p=bv,pv,b1v,p1,em&co=0&d=now&ib=p&sv=fr,sm
Будут рассчитаны:
1. Отправления - ценная бандероль, посылка, ценная бандероль 1 класса, посылка 1 класса, EMS (p=bv,pv,b1v,p1,em).
2. Тарификация - для физического лица без договора с Почтой России (co=0). Это значит, что отправления для корпоративных клиентов не рассчитываются, даже если будут запрошены, а тарифы для ценной посылки, ценной посылки 1 класса и EMS Оптимальное будут несколько выше.
3. Расчет на сегодняшний день (d=now, по умолчанию, можно опустить).
4. База страховки - только объявленная ценность товарного вложения (ib=p, по умолчанию, можно опустить).
5. Дополнительные опции - хрупкое вложение и SMS получателю (sv=fr,sm).

Пример 5. Расчет для юридического лица или ИП, имеющего договор с Почтой России ("Корпоративный клиент").

http://api.postcalc.ru/?f=101000&t=191167&w=1000&v=1000&key=test&p=po,co,ek,emo,empt&co=1&d=10days&bo=m&sv=ko,op&pk=50&pr=25
Будут рассчитаны:
1. Отправления - Посылка Онлайн, Курьер Онлайн, ЕКОМ, EMS Оптимальное (p=po,co,ek,ekp,emo).
2. Тарификация - для юридического лица или ИП, имеющего договор с Почтой России ("Корпоративный клиент") (co=1). Доступны все тарифы, при этом тарифы для ценной посылки, посылки 1 класса и EMS Оптимальное несколько ниже, чем для физлиц.
3. Дата расчета: сегодня +10 дней (d=10days). Это полезная возможность для интернет-магазинов рассчитать тариф на предполагаемую дату отправки товара.
4. Дополнительные опции - проверка комплектности и опись вложения (sv=ko,op).
5. При расчете ЕКОМ и EMS использовать коробку размера "М" (bo=m).
6. Добавить на каждое отправление стоимость упаковки 50 рублей (pk=50).
7. Добавить 25 рублей на оформление заказа (pr=25).
Обратите внимание, что прием и выдача большинства отправлений для корпоративных клиентов возможен только в специальных отделениях связи. Список этих отделений можно посмотреть по ссылке.