API 2.1 description

Запрос
Примеры запросов
Обязательные переменные запроса
Другие переменные запроса
Отправления: коды, ограничения по весу и ценности
Ответ
Декомпрессия ответа
Глобальные ошибки и предупреждения
Ошибки и предупреждения при расчете отправления
Глобальные переменные ответа
Массив "Отправления" ("Shipments")
Реализация
Полный рабочий пример кода
Библиотека Postcalc Light
Плагины

Другие переменные запроса

У этих переменных есть умолчания, поэтому их можно опустить в запросе. Умолчания следующие:
  1. Корпоративный клиент, имеющий договор с Почтой России (co=1).
  2. Формат выдачи HTML (o=html).
  3. Отправление нельзя разделить на несколько, при превышении веса выдается ошибка (pa=0).
  4. Набор символов UTF-8 (cs=utf-8).
  5. Дата расчета - сегодня (d=now).
  6. НДС включен (vt=1).
  7. Коробка для ЕКОМ и EMS - размер "S" (bo=s).
  8. Дополнительных услуг нет (sv - пустая строка).
  9. Наценка за обработку заказа - нет (pr=0).
  10. Наценка за упаковку - нет (pk=0).
  11. Язык ответа - русский (la=ru).
  12. Валюта ответа - рубли (cu=rub).
Мнемоника
(упрощает запоминание)
Переменная По умолчанию Описание
Output o html Формат выдачи данных. Поддерживаются следующие форматы: php, json, wddx, html, arr, plain. Регистр букв значения не имеет.
1. HTML. Страница html в читабельном виде, кодировка определяется переменной cs, удобно для просмотра ответа сервера прямо из браузера. По умолчанию - UTF-8.
2. PHP. Массив PHP, обработанный функцией serialize(). Кодировка определяется переменной cs, по умолчанию - UTF-8. Удобно для использования напрямую в скриптах PHP, для чего на стороне клиента следует использовать функцию unserialize() - см. пример в конце страницы.
3. ARR. Массив PHP, выведенный функцией var_export(). Кодировка определяется переменной cs, удобно для контроля ответов сервера из браузера. По умолчанию - UTF-8.
4. WDDX (разновидность xml) - массив PHP, обработанный функцией wddx_serialize_value(). Кодировка UTF-8.
5. JSON - массив PHP, обработанный функцией json_encode(). Кодировка UTF-8 + JavaScript Object Notation (JSON). Удобно для использования в JavaScript. Кодировка UTF-8.
Для выдачи в формате JSONP просто добавьте в запрос переменную callback=[Название_функции_обратного_вызова].
6. PLAIN - простой текст; это единственный вариант ответа, который не сжимается gzip. Каждая строчка имеет 3 поля, разделенных пробелом: код отправления, доставка, срок доставки. Формат экспериментальный, может измениться в любой момент.
Callback callback нет Название функции обратного вызова JavaScript, применяется в сочетании с форматом o=json.
Если сервер обнаруживает такую переменную, то возвращает ответ в формате JSONP с заголовком content-type: application/javascript.
В названии функции допускаются: латиница в любом регистре, цифры, знак подчеркивания.
Charset cs utf-8 Кодировка для выходных форматов php, arr, html. В данный момент распознаются utf-8 и windows-1251 (можно задавать как cp1251).
По умолчанию - utf-8.
Внимание! Для форматов json и wddx кодировка - всегда UTF-8! (ограничение функций php)
Date d now Дата, на которую нужно рассчитать отправку, в любом формате, который распознается функцией PHP strtotime(). В частности, распознаются такие варианты: 2021-01-30 (предпочтительный вариант), 30.01.2021, 30-01-2021, now, +10days. По умолчанию - текущий момент времени (now).
VAT vt 1 Если 1, НДС включен в тариф, если 0 - НДС вычитается из тарифа.
Внимание! Следует различать вычитание НДС для целей бухгалтерского учета (возможно для всех отправлений) и отправку по более низким тарифам без НДС (возможно только при оплате марками письменных отправлений).
Corporative co 1 Если 1, расчет идет по тарифам для клиентов, имеющих договор с Почтой России ("корпоративные клиенты").
Eсли 0 - расчет по тарифам для "обычных" клиентов: физических лиц и индивидуальных предпринимателей без договора, при этом не рассчитываются отправления для корпоративных клиентов: Посылка и Курьер Онлайн, ЕКОМ, Бизнес-Курьер, Бизнес-Курьер Экспресс, EMS PT .
По состоянию на конец 2020 года касается:
  • Расчета ценных посылок и ценных посылок 1 класса.
  • Расчета "EMS Оптимальное".
  • Некоторых дополнительных услуг.
Для "корпоративных клиентов" тарифы несколько ниже.
С 23 марта 2020 года по умолчанию - 1, до этого - 0.
Box bo s Тип коробки, определяет т.н. объемный вес. Если объемный вес больше реального, то при расчете тарифа применяется именно он.
Касается только расчета ЕКОМ и внутренного отправления EMS.
Значения: s (коробка "S", 260*170*80 мм), m (коробка "M", 300*200*150 мм), l (коробка "L", 400*270*180 мм), xl (коробка "XL", 530*360*220 мм), ng (негабаритная коробка, сумма сторон не более 1400 мм, одна сторона не более 600 мм).
Services sv пустая строка Опции отправки и дополнительные услуги . Список кодов через запятую, например: sv=sm,ko,cod.
Следует учитывать, что не все виды отправлений имеют все виды услуг и опций.
КодУслуга
frХрупкая (только для посылок)
ngНегабаритная (только для посылок)
opПроверка соответствия вложения описи
koПроверка комплектности
ppПредпочтовая подготовка
smSMS получателю
sm2SMS отправителю
codОплата в момент доставки (COD)
uvПростое уведомление о вручении
uvrЗаказное уведомление о вручении
uveЭлектронное уведомление о вручении
iuvМеждународное уведомление о вручении
Partible pa 0 Отправление является делимым (можно распределить на несколько).
Если 0 (по умолчанию), используется логика официальных калькуляторов Почты России: отправление может быть только одно, при превышении допустимого веса и/или ценности расчет не производится.
Если 1, используется логика Postcalc.RU: отправление делится на несколько, контроль ценности не производится.
Например, для веса 20 кг при pa=0 расчет бандероли не производится, при pa=1 возвращается расчет для 4-х бандеролей весом по 5 кг каждая.
Аналогично: для ценности 100 тыс. рублей при pa=0 расчет ценной бандероли и EMS не производится (ограничение 10 тыс. и 50 тыс. рублей соответственно), при pa=1 - производится
Внимание! Для внутренних писем ограничение по весу действует в любом случае (так было в расчетах Postcalc.RU с самого начала): простое, заказное, ценное письмо рассчитываются при весе не более 100 г, заказное и ценное письмо 1 класса - не более 500 г.
ProcessingFee pr 0 Пользовательская наценка за обработку заказа в рублях.
PackingFee pk 0 Пользовательская наценка за упаковку одного отправления в рублях.
IBase ib p Устарелый параметр, будет игнорироваться в следующих версиях API.
База для расчета страховки (только при оценке товарного вложения больше 0!).
Если ib=p или Partial, то страхуется только товарное вложение. Например, посылка с оценкой 1000 рублей будет застрахована на 1000 * 4% = 40 рублей независимо от стоимости доставки.
В случае пропажи отправления почта возместит только стоимость товара, а расходы на доставку и страховку придется списать в убыток.
Кроме того, при отправке наложенным платежом возникает проблема расчета суммы, которую адресат должен выплатить при получении отправления: ведь эта сумма больше оценки товара и должна покрывать расходы интернет-магазина на доставку и страховку
Если ib=f или Full, базой страховки будет Оценка Товара + Тариф + Страховка, и в случае пропажи отправления почта полностью возместит ущерб. Это самый оптимальный вариант для отправки наложенным платежом, а конечная сумма, которую должен заплатить адресат - это столбец "Ценность" на веб-странице или поле ОценкаПолная в ответе по API.
Ценность вычисляется по формуле: Ценность = Тариф + Оценка вложения + Страховка
Размер страхового сбора вычисляется по формуле: Страховка = ( Тариф + Оценка ) * СтавкаСбора / (1 - СтавкаСбора)
С 01 июня 2020 года - p, до этого - f.
Language la ru Новый параметр, только в версии 2.1+.
Язык ответа. Если en, то в ответе применяется английский язык. Входные данные на английском языке (ключи населенных пунктов, названия стран) интерпретируются корректно в любом случае, вне зависимости от этого параметра.
Currency cu rub Новый параметр, только в версии 2.1+.
Валюта ответа. Если отличается от rub, то рубли в ответе пересчитываются в соответствующую валюту по курсу Центробанка России. Входные данные (ценность, переменная v=) в любом случае задаются в рублях, вне зависимости от этого параметра.
Software sw нет Необязательный идентификатор плагина. Произвольная строка латиницей (не более 30 символов), подчеркивание, номер версии (например, MyBestPlugin_1.01).
Позволяет разработчикам плагинов получить доступ к списку доменов, которые используют их плагин, статистике обращений, ошибкам и журналам запросов пользователей в реальном времени. При этом никакая личная информация пользователей (включая ключ домена) разработчикам недоступна.
Для доступа к этой информации разработчикам следует написать в произвольной форме в техподдержку Postcalc.RU.