Интеграция с Почтой России: расчёт доставки и трек-номера

Интеграцию с Почтой России настраиваю в интернет-магазинах на Tilda и WooCommerce примерно раз в квартал: клиенты просят автоматический расчёт стоимости доставки на этапе оформления заказа и статус посылки в личном кабинете, а не ручное копирование трек-номера из таблицы. С Почтой России возни объективно больше, чем с СДЭК или Boxberry, потому что нужен договор, доступ к личному кабинету Отправка и своя логика на бэкенде: фронтенд напрямую с их API работать не может. Дальше разложу по шагам то, с чем реально сталкиваюсь на проектах, от получения токена до обработки трек-номеров и типичных ошибок при подключении.

Зачем магазину API Почты России, а не готовый виджет

У Почты России фактически два разных API, и их часто путают. Tracking API отдаёт статус посылки по трек-номеру и подходит для страницы «отследить заказ». Отправка API считает тариф, создаёт заказ, резервирует штрихкоды и печатает этикетку, и именно он нужен для расчёта стоимости доставки в корзине.

Готовый iframe-виджет с сайта pochta.ru для расчёта тарифа работает, но живёт отдельно от корзины: он не знает вес и габариты конкретного заказа, не пишет цену обратно в форму и не может выставить пользователю правильный итог с учётом наложенного платежа. Как только нужно, чтобы стоимость доставки автоматически попадала в заказ и в CRM, без прямого запроса к Отправка API не обойтись.

Доступ к API: договор, личный кабинет и токены

Чтобы дёргать Отправка API боевыми запросами, нужен договор возмездного оказания услуг с Почтой России на юрлицо или ИП. Оформляется он через личный кабинет otpravka.pochta.ru, и на согласование у меня обычно уходит 3-5 рабочих дней, если реквизиты и адрес подачи заполнены без ошибок.

После договора выдают доступ к личному кабинету и токен приложения. Авторизация в запросах строится на двух заголовках: X‑User-Authorization с Base64 от логина и пароля личного кабинета, и отдельный токен приложения в заголовке Authorization. Есть песочница для тестовых запросов, но часть проверок, например реальные индексы отделений, там работает не так, как в проде, поэтому финальную проверку тарифов всегда делаю на боевом контуре с небольшими тестовыми заказами.

Логин, пароль и токен храню только на сервере, в переменных окружения. Даже если фронтенд собран на Tilda, секреты туда не попадают в принципе, запрос идёт через прокси-бэкенд.

Расчёт стоимости доставки через Tariff API

Тариф считается методом POST на /1.0/tariff. В запрос передаю индекс отправителя и получателя, тип отправления (посылка, посылка онлайн, бандероль), вес в граммах, габариты в сантиметрах, объявленную ценность и признак наложенного платежа.

curl -X POST "https://otpravka-api.pochta.ru/1.0/tariff" \
  -H "Authorization: AccessToken $POCHTA_TOKEN" \
  -H "X-User-Authorization: Basic $POCHTA_USER_AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "index-from": 101000,
    "index-to": 630000,
    "mail-category": "ORDINARY",
    "mail-type": "POSTAL_PARCEL",
    "mass": 1000,
    "dimension-type": "BOX",
    "length": 20,
    "width": 15,
    "height": 10,
    "fragile": false
  }'

В ответе приходят итоговая сумма, срок доставки в днях и разбивка по НДС. По опыту, посылка весом около килограмма из Москвы в Новосибирск обходится в районе 350-450 рублей в зависимости от объявленной ценности, а тот же вес до соседней области заметно дешевле. Тариф зависит от связки индексов, а не только от города, поэтому без точного шестизначного индекса получателя запрос либо падает, либо считает сумму неверно.

Трек-номера: резервирование и статусы отправлений

Штрихкоды, будущие трек-номера, можно зарезервировать заранее пачкой через методы работы с backlog в Отправка API, либо получить их сразу при создании заказа. Формат стандартный, 14 цифр, и его можно отдать клиенту сразу после оформления, до фактической сдачи посылки на почте.

На практике трек появляется в системе отслеживания не мгновенно, обычно через 1-2 дня после того, как посылку физически приняли в отделении и отсканировали штрихкод. Если показывать клиенту статус раньше этого момента, на странице заказа лучше выводить «трек-номер присвоен, ожидает приёма в отделении», а не пытаться сразу дёргать Tracking API и получать пустой ответ.

Для самого отслеживания использую Tracking API: можно запросить статус по одному номеру или пакетно, до нескольких тысяч штрихкодов за раз. Опрашивать эндпоинт при каждом заходе клиента на страницу заказа не стоит, у Почты есть лимиты по частоте запросов, и при агрессивном polling можно словить троттлинг. Обычно ставлю фоновое обновление статусов раз в 3-4 часа через cron-задачу в n8n, которая тянет пачку активных трек-номеров и обновляет статусы в базе, а фронтенд уже читает готовые данные.

Подключение к Tilda и WooCommerce на практике

Встроенная интеграция с Почтой России у Tilda есть: расчёт стоимости по тарифам Почты с учётом габаритов, выбор отделения или постамата на карте в корзине, но одна категория отправления на интеграцию. Когда расчёт нужен в своей форме заказа, а не в штатной корзине, или со своей логикой тарифа, напрямую с фронтенда её API не вызвать: секреты личного кабинета туда попадать не должны, да и CORS не пропустит запрос к otpravka-api.pochta.ru. Рабочая схема, которую я обычно ставлю: скрипт на странице оформления заказа дёргает свой вебхук на n8n или отдельном сервере, тот в свою очередь ходит в Tariff API и возвращает цену обратно в поле формы. На проекте с handmade-товарами на Tilda такая связка считала стоимость доставки за 1-2 секунды после ввода индекса, без перезагрузки страницы.

Для несложных сценариев, когда точный расчёт по API не обязателен и достаточно разбить город на зоны с фиксированной ценой, у меня в библиотеке есть готовый скрипт ограничения доставки по зонам на карте для Tilda, который сверяет адрес с полигонами на Яндекс.Карте и подставляет цену зоны без обращения к внешнему API вообще, это быстрее и не зависит от лимитов Почты.

В WooCommerce есть сторонние плагины для расчёта через Почту России, но на практике часть из них не поддерживает актуальную версию API или неверно считает объём при нескольких товарах в одной посылке, просто суммируя вес без пересчёта габаритов коробки. Из-за этого чаще пишу свой shipping method: PHP-класс дёргает Tariff API через wp_remote_post в момент расчёта корзины и кэширует ответ на час по ключу «индекс плюс вес», чтобы не слать лишние запросы при каждом обновлении товаров в корзине.

Отдельно по оплате: наложенный платёж Почта поддерживает, но по моей статистике с ним заметно выше процент отказов при получении, чем при предоплате. Для WooCommerce и Tilda обычно ставлю предоплату через эквайринг, у клиентов на T‑Bank это настраивается быстро, а Почту оставляю только как способ доставки.

Почта России или СДЭК: что выбрать для магазина

Для магазина с широкой географией, включая малые города и посёлки, Почта закрывает доставку туда, где у СДЭК просто нет точки выдачи. Если основная аудитория в городах-миллионниках и важна скорость, СДЭК почти всегда выигрывает по срокам. На части проектов ставлю оба варианта одновременно и даю клиенту выбор на чекауте, тогда расчёт тарифа идёт параллельно в оба API, а на странице показывается более быстрый ответ.

Частые ошибки при интеграции

• Считают вес заказа простым сложением товаров, забывая про объёмный вес коробки, из-за чего тариф с сайта расходится с тем, что выставят в отделении при приёме.
• Передают в запросе только город получателя вместо точного шестизначного индекса, и тариф считается по среднему значению для региона, а не для конкретного адреса.
• Хранят логин и пароль от личного кабинета Отправка в коде фронтенда или в публичном репозитории, хотя это данные для входа в реальный кабинет с деньгами компании.
• Опрашивают Tracking API при каждом открытии страницы заказа вместо периодического фонового обновления и упираются в лимиты Почты на количество запросов.
• Не проверяют тарифные пороги по весу: 100 грамм разницы могут перевести посылку в следующую весовую категорию и изменить итоговую сумму заметнее, чем ожидает клиент.

Если расчёт доставки и трек-номера нужно завести не только на Почту, а сразу на несколько служб с единой логикой в CRM или Telegram-боте на aiogram, проще один раз спроектировать бэкенд-прослойку под все API сразу, чем городить отдельный костыль под каждую службу.

Частые вопросы

Нужен ли договор с Почтой России для расчёта доставки на сайте?

Для автоматических запросов к Tariff API через Отправка API договор обязателен, без него личный кабинет не выдаст токен и авторизационные заголовки. Если нужен только приблизительный расчёт по весовым порогам без обращения к API, можно обойтись собственной таблицей зон и обновлять её вручную раз в несколько месяцев.

Сколько занимает подключение к API Отправка от старта до боевых запросов?

Согласование договора у меня обычно занимает 3-5 рабочих дней при условии, что реквизиты компании и адрес подачи заполнены верно. После этого выдают доступ к личному кабинету и токен, и разработку прокси-эндпоинта для расчёта тарифа и статусов делаю за несколько дней в зависимости от того, встраивается ли она в готовую CRM или пишется с нуля.

Можно ли использовать один и тот же трек-номер для наложенного платежа и для предоплаченного заказа?

Да, формат трек-номера не зависит от способа оплаты, различается только параметр типа оплаты при создании заказа в Отправка API. Наложенный платёж просто добавляет к посылке денежный перевод, который получатель вносит при получении, а трек и логика отслеживания остаются такими же.

Почему тариф из API не совпадает с суммой на сайте pochta.ru?

Обычно причина в неточном индексе получателя или в неверно переданном весе и типе отправления: сайт может показывать тариф по среднему для города, а API считает по точным параметрам конкретной посылки. Второй частый случай, когда в запросе не учли объёмный вес коробки и передали только фактический вес товаров.