—крыть меню * ¬ерси€ дл€ печати

ѕереход на API 2.0

ѕереход на API 2.0 с 01 июн€ 2020 года - рекомендации

ƒорогие друзь€!

— 01 июн€ 2020 года Postcalc.RU переходит на новую "большую версию" API - версию 2.0. –азница с текущей версией 1.2 минимальна, однако может потребовать дополнительных настроек запросов и/или программировани€ с вашей стороны.

ќсновное отличие

¬ насто€щее врем€ API отдает за один запрос 21 внутреннее или 16 международных отправлений. Ёто слишком много и не имеет практического смысла.

— 01 июн€ 2020 года Postcalc.RU будет отдавать не более 5 внутренних и 5 международных отправлений за один запрос на бесплатном доступе. Ќа платном доступе число отправлений дл€ одного запроса не ограничено, как и в текущей версии.

ѕо каким именно отправлени€м отдаютс€ расчеты, определ€ет переменна€ запроса p=[список_кодов_отправлений].

≈сли эта переменна€ не указана, то на бесплатном доступе отдаютс€ следующие отправлени€:

ƒл€ внутренних:
1. ÷енна€ бандероль
2. ÷енна€ посылка
3. ÷енна€ бандероль 1 класса
4. ÷енна€ посылка 1 класса
5. EMS

ƒл€ международных:
1. ћелкий пакет наземный заказной
2. ћелкий пакет авиа заказной
3. ѕосылка наземна€
4. ѕосылка авиа
5. EMS с товарным вложением

Ќа платном доступе при отсутствии переменной p= в запросе будут по-прежнему отдаватьс€ все возможные отправлени€. ќднако насто€тельно рекомендуетс€ использовать эту переменную, чтобы получать расчеты только по тем отправлени€м, которые вы реально используете в своем интернет-магазине.

ƒл€ пользователей

¬ам не нужно предпринимать дополнительные действи€, если выполн€етс€ хот€ бы одно из условий:

1. ¬ы уже находитесь на платном доступе.
2. ¬ы используете в расчетах: дл€ внутренних отправлений - только ценную бандероль/посылку, ценную бандероль/посылку 1 класса, EMS; дл€ международных - мелкий пакет заказной наземный/авиа, посылку наземную/авиа, EMS с товарным вложением.

¬о всех остальных случа€х вам необходимо обратитьс€ за обновлением к программисту или к разработчику плагина, которым ваш интернет-магазин подключен к Postcalc.RU. Ќекоторые разработчики обновление уже выпустили.

ѕрошу обратить внимание: € разработкой плагинов не занимаюсь, лично разработчиков не знаю (только переписывалс€ с некоторыми), сам модули не тестировал, техническую поддержку осуществл€ют только их разработчики!

ƒл€ программистов

— окт€бр€ 2019 года в API проекта был внесен р€д изменений. ќсновна€ цель - максимально приблизить расчеты на Postcalc.RU к расчетам на официальных тарификаторах ѕочты –оссии.

¬ насто€щее врем€ активна€ работа завершена, нынешнее API 1.2 полностью совпадает с API 2.0, за исключением установок по умолчанию дл€ переменных p (Parcels) и ib (InsuranceBase). “о есть вы можете пр€мо сейчас внести изменени€ в ваш плагин, проверить его и быть уверенными, что с 01 июн€ 2020 года плагин будет работать корректно.

Ќиже список переменных, затронутых изменени€ми.
ћнемо-ника ѕеремен-на€ ѕо умолчанию ќписание
Key key нет  люч доступа. — 19 окт€бр€ 2019 года.  люч необходимо получить в Ћичном кабинете. ¬озможно использование тестового ключа key=test (не более 50 запросов в сутки с одного IP).
Parcels p ƒл€ бесплатного доступа -
bv,pv,b1v,p1,em,
isr,isar,ip,ipa,iem
ƒл€ платного доступа - все возможные отправлени€
—писок кодов отправлений через зап€тую. — 16 марта 2020 года. ƒл€ бесплатного доступа - не более 5 внутренних отправлений и не более 5 международных.  оды дл€ международных отправлений начинаютс€ с i. ѕо умолчанию в ответе будут: дл€ расчетов внутренних отправлений - ценна€ бандероль, посылка, ценна€ бандероль 1 класса, посылка 1 класса, EMS; дл€ международных - мелкий пакет заказной наземный/авиа, посылка, авиапосылка, EMS с товарным вложением.  оды отправлений см. в документации ниже.
ќпциональное поле с 16 марта 2020 года, с 01 июн€ 2020 года - об€зательное.
Corp co 1 ≈сли 1, расчет идет по тарифам дл€ клиентов, имеющих договор с ѕочтой –оссии ("корпоративные клиенты"), если 0 - расчет по тарифам дл€ "обычных" клиентов: физических лиц и индивидуальных предпринимателей без договора. — 25 окт€бр€ 2019 года.
— 23 марта 2020 года по умолчанию - 1, до этого - 0.
ѕо состо€нию на март 2020 года касаетс€: 1. расчета ценных посылок. 2. расчета "EMS ќптимальное". 3. Ќекоторых дополнительных услуг. ƒл€ "корпоративных клиентов" тарифы несколько ниже.
Box bo s “ип коробки, определ€ет т.н. объемный вес. ≈сли объемный вес больше реального, то при расчете тарифа примен€етс€ именно он. — 14 марта 2020 года.
ѕо состо€нию на март 2020 года касаетс€ только расчета "≈ ќћ".
«начени€: 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 ќтправление €вл€етс€ делимым (можно распределить на несколько). — 30 марта 2020 года.
≈сли 0 (по умолчанию), используетс€ логика официальных калькул€торов ѕочты –оссии: отправление может быть только одно, при превышении допустимого веса и/или ценности расчет не производитс€.
≈сли 1, используетс€ логика Postcalc.RU: отправление делитс€ на несколько, контроль ценности не производитс€.
Ќапример, дл€ веса 20 кг при pa=0 расчет бандероли не производитс€, при pa=1 возвращаетс€ расчет дл€ 4-х бандеролей весом по 5 кг кажда€.
јналогично: дл€ ценности 100 тыс. рублей при pa=0 расчет ценной бандероли и EMS не производитс€ (ограничение 10 тыс. и 50 тыс. рублей соответственно), при pa=1 - производитс€
¬нимание! ƒл€ внутренних писем ограничение по весу действует в любом случае (так было в расчетах Postcalc.RU с самого начала): простое, заказное, ценное письмо рассчитываютс€ при весе не более 100 г, заказное и ценное письмо 1 класса - не более 500 г.
IBase ib f, с 01 июн€ 2020 года - p. Ѕаза дл€ расчета страховки (только при оценке товарного вложени€ больше 0!).

≈сли IBase=p или Partial, то страхуетс€ только товарное вложение. Ќапример, посылка с оценкой 1000 рублей будет застрахована на 1000 * 4% = 40 рублей независимо от стоимости доставки.
¬ случае пропажи отправлени€ почта возместит только стоимость товара, а расходы на доставку и страховку придетс€ списать в убыток.
 роме того, при отправке наложенным платежом возникает проблема расчета суммы, которую адресат должен выплатить при получении отправлени€: ведь эта сумма больше оценки товара и должна покрывать расходы интернет-магазина на доставку и страховку

≈сли IBase=f или Full, базой страховки будет ќценка “овара + “ариф + —траховка, и в случае пропажи отправлени€ почта полностью возместит ущерб. Ёто самый оптимальный вариант дл€ отправки наложенным платежом, а конечна€ сумма, которую должен заплатить адресат - это столбец "÷енность" на веб-странице или поле ќценкаѕолна€ в ответе по API.
÷енность вычисл€етс€ по формуле: ÷енность = “ариф + ќценка вложени€ + —траховка
–азмер страхового сбора вычисл€етс€ по формуле: —траховка = ( “ариф + ќценка ) * —тавка—бора / (1 - —тавка—бора)

ќбратите внимание, что в API 2.0 использовать мнемонику вместо переменной не допускаетс€ (например, нельз€ From вместо f).

 лючи переменной p (Parcels) дл€ внутренних отправлений.
ѕараметр переменной p јнглийский ключ ответа –усский ключ ответа ќписание
ls LetterSimple ѕростоеѕисьмо ѕростое письмо
lr LetterReg «аказноеѕисьмо «аказное письмо
lv LetterValued ÷енноеѕисьмо ÷енное письмо
l1r Letter1ClassReg «аказноеѕисьмо1 ласс «аказное письмо 1 класса
l1v Letter1ClassValued ÷енноеѕисьмо1 ласс ÷енное письмо 1 класса
bs BookpostSimple ѕроста€Ѕандероль ѕроста€ бандероль
br BookpostReg «аказна€Ѕандероль

«аказна€ бандероль

b1r Bookpost1ClassReg «аказна€Ѕандероль1 ласс «аказна€ бандероль 1 класс
bv BookpostValued ÷енна€Ѕандероль ÷енна€ бандероль
pv ParcelValued ÷енна€ѕосылка ÷енна€ посылка
b1v Bookpost1ClassValued ÷енна€Ѕандероль1 ласс ÷енна€ бандероль 1 класс
p1 Parcel1Class ѕосылка1 ласс ѕосылка 1 класса
em EMS EMS  урьерска€ доставка EMS
po ParcelOnline ѕосылкаќнлайн ”слуга "ѕосылка ќнлайн" дл€ корпоративных клиентов
co CourierOnline  урьерќнлайн ”слуга " урьер ќнлайн" дл€ корпоративных клиентов
ek EKOM ≈ ќћ ”слуга "≈ ќћ" дл€ корпоративных клиентов (ключ пишетс€ кириллицей!) с доставкой в ѕ¬«/јѕ— ѕочты –оссии.
ekp EKOMPartner ≈ ќћѕартнер ”слуга "≈ ќћ" дл€ корпоративных клиентов (ключ пишетс€ кириллицей!) с доставкой в ѕ¬«/јѕ— партнеров ѕочты –оссии.
emo EMSOptimal EMSќптимальное ”слуга "EMS ќптимальное" с доставкой до ÷¬ѕѕ. ¬ ключе EMS пишетс€ латиницей, "ќптимальное" - кириллицей.
emoc EMSOptimalCourier EMSќптимальное урьер ”слуга "EMS ќптимальное" с доставкой клиенту курьером. ¬ ключе EMS пишетс€ латиницей, "ќптимальное" - кириллицей.
bc BusinessCourier Ѕизнес урьер ”слуга "Ѕизнес- урьер" дл€ корпоративных клиентов ѕочты –оссии.
bce BusinessCourierExpress Ѕизнес урьерЁкспресс ”слуга "Ѕизнес- урьер экспресс" дл€ корпоративных клиентов ѕочты –оссии.


 лючи переменной p (Parcels) дл€ международных отправлений.
ѕараметр переменной p јнглийский ключ ответа  люч ответа ќписание
im IntParcelM ћждћешокћ ћеждународный мешок ћ
ima IntParcelMAvia ћждћешокћјвиа

ћеждународный мешок ћ авиа

imr IntParcelMReg ћждћешокћ«аказной ћеждународный мешок ћ заказной
imar IntParcelMAviaReg ћждћешокћјвиа«аказной ћеждународный мешок ћ авиа заказной
ib IntBookpost ћждЅандероль ћеждународна€ бандероль
iba IntBookpostAvia ћждЅандерольјвиа ћеждународна€ авиабандероль
ibr IntBookpostReg ћждЅандероль«аказна€ ћеждународна€ бандероль заказна€
ibar IntBookpostAviaReg ћждЅандерольјвиа«аказна€ ћеждународна€ авиабандероль заказна€
is IntSmallPacket ћждћелкийѕакет ћеждународный мелкий пакет
isa IntSmallPacketAvia ћждћелкийѕакетјвиа ћеждународный мелкий пакет авиа
isr IntSmallPacketReg ћждћелкийѕакет«аказной ћеждународный мелкий пакет заказной
isar IntSmallPacketAviaReg ћждћелкийѕакетјвиа«аказной ћеждународный мелкий пакет авиа заказной
ied IntEMSDocs EMS_ћждƒокументы ≈MS международное - документы
iem IntEMSMerchandise EMS_ћжд“овары ≈MS международное - товары
ip IntParcel ћждѕосылка ћеждународна€ посылка *
ipa IntParcelAvia ћждѕосылкајвиа ћеждународна€ авиапосылка *


—татус ответа и ошибки

ќтвет - иерархический массив.  люч Status содержит либо OK, либо код ошибки. ¬ последнем случае также устанавливаетс€ ключ Message с текстом ошибки.
ќшибка возвращаетс€, если невозможно выполнить расчет ни одного тарифа в принципе: неверное значение веса, нет такого почтового индекса и т.п..
≈сли невозможно выполнить только расчет конкретного тарифа, то устанавливаетс€ ключ ответа Ќет–асчета (ќтправлени€->»м€ќтправлени€->Ќет–асчета).
Ќасто€тельно рекомендуетс€ перед отправкой запроса провер€ть данные, чтобы избежать ошибок и отсутстви€ расчета.

ќшибки
Status Message ќписание
OK  орректный ответ
ERROR_NOKEY No domain key found in request. You should get the key in personal cabinet: http://www.postcalc.ru/lk. ¬ запросе имеетс€ ключ домена key=[ключ_домена]. Ёта ошибка не возникает у платных клиентов, подключенных через "белый список" адресов IP.
ERROR_BAD_KEY Domain key [key] is bad. You should get correct key in personal cabinet: http://www.postcalc.ru/lk. ¬ запросе найден ключ домена, но он не найден в списке зарегистрированных ключей.
ERROR_TESTKEY_LIMIT_50 Limit for test key reached: 50 requests in one day from one IP address (IP $RemoteIP, total $i_total). ѕревышен дневной лимит запросов с тестовым ключом key=test: не более 50 с одного IP в календарные сутки по московскому времени.
ERROR_DOMAIN_BANNED_LIMIT_500 Your domain $Domain is banned. You should pay Start Plan in Personal Cabinet: http://www.postcalc.ru/lk. ѕревышен дневной лимит запросов с ключом домена: не более 500 в календарные сутки по московскому времени.  люч блокирован. Ќеобходимо оплатить план "—тартовый" через Ћичный кабинет.
ERROR_NO_VAR_F Every request should contain correct variable f= ќтсутствует переменна€ f (почтовый индекс или населенный пункт отправител€), либо она заведомо неверна.
ERROR_NO_VAR_T Every request should contain correct variable t= ќтсутствует переменна€ t (почтовый индекс или населенный пункт получател€), либо она заведомо неверна. “олько дл€ внутренних отправлений.
ERROR_NO_VAR_W Every request should contain correct variable w= ќтсутствует переменна€ w (вес отправлени€), либо она заведомо неверна (пуста€ строка, буквы и т.п.).
ERROR_WEIGHT_EXCEEDS_LIMITS Parcel weight cannot be less than 0 and more than 31500 g. ¬ес отправлени€ превышает максимально допустимый (31500 г).
BAD_FROM_INDEX
или
BAD_TO_INDEX
Cannot find postal code - почтовый_индекс. Ќе найден почтовый 6-значный индекс отправител€ или получател€. »счерпывающий список ќѕ— онлайн находитс€ по ссылке. ≈го также можно скачать в виде таблицы MySQL.
BAD_FROM_CITY
или
BAD_TO_CITY
Cannot find city - населенный_пункт. Ќе найден почтовый населенный пункт отправител€ или получател€, заданный в переменной f= или t=. »счерпывающий список населенных пунктов онлайн находитс€ по ссылке. “ам же описание принципов, по которым этот список формируетс€. ≈го также можно скачать в виде таблицы MySQL.
BAD_COUNTRY Cannot find country - название_страны. Ќе найден двузначный код страны дл€ международной доставки (переменна€ c=).


ќтсутствие расчета (ключ Ќет–асчета)
¬ следующих случа€х ключ ответа “ариф равен 0 и устанавливаетс€ ключ Ќет–асчета с объ€снением причины:
1. ¬ес бандероли менее 100 г. Ќе рассчитываютс€ проста€, заказна€ и ценна€ бандероли. Ѕандероль 1 класса может весить и менее 100 г.
2. ¬ес простого, заказного, ценного письма более 100 г, вес письма 1-го класса более 500 г. Ёто ограничение действует вне зависимости от ключа pa.
3. ”становлен ключ pa=0 (неделимое отправление), при этом вес отправлени€ и/или ценность превышает максимально допустимый дл€ данного вида. Ќапример, если вес отправлени€ - 20 кг, не будет расчета дл€ отправки бандеролью. ≈сли ценность - 100 тыс. рублей, не будет расчета дл€ EMS и ценной бандероли.
4. ќѕ— полностью закрыто дл€ доставки в св€зи с сезонными ограничени€ми. Ќе рассчитываетс€ ни одно из отправлений.
5. ќѕ— закрыто дл€ наземной доставки (временно или посто€нно). Ќе рассчитываютс€ отправлени€, которые могут быть доставлены только наземным способом: простое, заказное, ценное письмо/бандероль.
6. ќѕ— не принимает данный тип отправлений. “олько дл€ отправлений ≈ ќћ и EMS ќптимальное.

ѕредварительна€ проверка данных

Ќасто€тельно рекомендуетс€ реализовать предварительную проверку данных до их отправки. ƒл€ этого имеютс€ следующие ресурсы.

1. ѕроверка почтового индекса, населенного пункта, кода страны - по таблицам postcalc_light_cities (населенные пункты и их индексы по умолчанию), postcalc_light_post_indexes (почтовые индексы), postcalc_light_countries (страны):
http://www.postcalc.ru/download/PostcalcLight_SQL.zip

2. ѕроверка списков пунктов приема/выдачи ≈ ќћ, приема ѕосылки ќнлайн, ÷¬ѕѕ - по таблице postcalc_points.
https://www.postcalc.ru/download/dev/tables/postcalc_points.sql.gz

3. ѕроверка допустимого веса и ценности отправлений - по таблице postcalc_parcels.
https://www.postcalc.ru/download/dev/tables/postcalc_parcels.sql.gz

–есурсы в помощь разработчику

1. ѕримеры на €зыке PHP:
https://www.postcalc.ru/download/dev/examples/

2 –абочие таблицы Postcalc.RU:
https://www.postcalc.ru/download/dev/tables/
postcalc_parcels - ѕолный список отправлений и их характеристики (максимальный вес, ценность, габариты, доступные опции и т.п.). ћарт 2020 года.
ekom_delivery_points - —писок пунктов приема и выдачи ≈ ќћ с опци€ми. ћарт 2020 года.
postcalc_points - —писок пунктов приема/выдачи ≈ ќћ, приема ѕосылки ќнлайн, ÷¬ѕѕ. ћарт 2020 года.
PostcalcLight_SQL.zip - “аблицы postcalc_light_cities (населенные пункты и их индексы по умолчанию), postcalc_light_post_indexes (почтовые индексы), postcalc_light_countries (страны). ќбновл€ютс€ 2 раза в мес€ц.

3 Ќекоторые источники с официального сайта ѕочты –оссии:
https://www.postcalc.ru/download/dev/pochta/

ѕо любым вопросам пишите в техподдержку на postcalc@mail.ru.

— уважением -
јлексей –уденко-ƒесн€к,
автор проекта Postcalc.RU,
04 апрел€ 2020 года.

(c) PostCalc.RU 2010-20



яндекс.ћетрика

Time elapsed: 0.00692