Ukrposhta International для WooCommerce — международная доставка Укрпочтой с тарифом в корзине

Ukrposhta International для WooCommerce — международная доставка Укрпочтой с тарифом прямо в корзине. Обычно магазин, который отправляет товары за границу, считает доставку вручную: покупатель оформляет заказ, менеджер открывает калькулятор Укрпочты и пишет ему цену. Плагин спрашивает тариф у Укрпочты сам — для страны покупателя, веса и габаритов корзины — и показывает его как обычный способ доставки. Мелкий пакет, посылка, EMS или Prime, авиа или наземно: то, чего Укрпочта в эту страну не принимает, покупатель просто не видит. Для OpenCart 4, 3 и 2.3 есть отдельная версия — Ukrposhta International для OpenCart.

Что нужно от вас. Договор с Укрпочтой на международные отправления и ключи eCom API с международным доступом: для тарифа — Bearer, для отправлений (Pro) — ещё токен пользователя и отправитель с адресом латиницей. Ключи выдаёт менеджер Укрпочты или api-support; без них метод в корзине не появляется. Честно о проверке: плагин сделан по официальной документации API международных отправлений Укрпочты (редакция 23.07.2026) и прогнан на тестовом магазине с ответами в формате этой документации; на живом договоре Укрпочты его ещё не запускали. Проверьте на своих ключах в 7-дневном триале Pro — если Укрпочта ответит не так, как в документации, исправим оперативно.

Как это выглядит для покупателя

Покупатель вводит адрес за границей — и в способах доставки видит Укрпочту с ценой для своей страны. Тариф считается для всей корзины как одной коробки: суммарный вес, суммарный объём, самый длинный товар как самая длинная сторона, плюс вес упаковки из настроек. Изменил количество товаров или страну — цена пересчитывается. Для адресов в Украине метод не показывается никогда: там работает обычная Укрпочта или Новая Почта.

Не каждый тип отправления идёт в каждую страну. В автоматическом режиме плагин берёт мелкий пакет, пока корзина помещается в его лимиты (2 кг, 60 см), и посылку — когда нет или когда Укрпочта не принимает мелкие пакеты в эту страну. Фиксированный тип (например, только EMS) просто не показывается там, где Укрпочта отказала. Заказы больше 30 кг без Pro метод не получают; с Pro они делятся на несколько отправлений.

Укрпочта принимает международные адреса только латиницей и не принимает отправления без телефона. Поэтому, когда выбран этот метод, чекаут проверяет адрес и телефон и объясняет, какие поля переписать, — на классическом и блочном чекауте. Проверку можно отключить в настройках.

Что получает админ

• Метод в обычных зонах доставки WooCommerce. Добавляете «Ukrposhta International» в зону со странами, куда отправляете. У каждого экземпляра метода свой тип отправления (автоматически, мелкий пакет, посылка, EMS, Prime) и транспорт (авиа или наземно), так что можно поставить рядом, скажем, посылку авиа и EMS.
• Посылка и тариф: вес и габариты для товаров без них, вес упаковки, объявленная ценность для посылок и EMS, поведение при сбое API — скрыть метод или показать фиксированную цену.
• Валюта. Магазин в гривнах или долларах работает сразу. Для другой валюты задаёте курс в настройках; без курса метод не показывается, чтобы не показать выдуманную цену.
• Таможня: категория отправления, код УКТВЭД и страна происхождения по умолчанию. В товаре на вкладке «Доставка» — свой код УКТВЭД, название латиницей и страна происхождения; вариации берут их из родительского товара.
• «Проверить» считает посылку 1 кг в выбранную страну и показывает ответ Укрпочты. Ключи хранятся зашифрованными и не возвращаются в поля формы.
• Журнал каждого запроса к Укрпочте — в журналах WooCommerce, если включить его в настройках.

• Отправление из карточки заказа (Pro). Бокс «Ukrposhta International» собирает черновик из заказа: тип и транспорт из выбранной покупателем ставки, вес, коробку, таможенные позиции с латинскими названиями и кодами УКТВЭД. Менеджер проверяет и нажимает «Создать отправление в Укрпочте» — плагин создаёт адрес и получателя латиницей и само отправление и получает трек-номер.
• Проверки до отправки. Размытые названия вроде «Gift» или «Accessories», которые Укрпочта отклоняет, и запрещённые сочетания (EMS с категорией «Продажа товаров») плагин останавливает ещё до запроса.
• Документы: все бланки, таможенные декларации CN22 и CN23, ярлык — PDF кнопками в том же боксе. Там же «Обновить статусы» и удаление отправления, которое ещё не передали Укрпочте.
• Трек-номер попадает в письма о заказе и в кабинет покупателя.

Как это работает — шаг за шагом

1. Ключи. WooCommerce → Ukrposhta International: вставляете eCom Bearer, сохраняете и нажимаете «Проверить».
2. Зона доставки. В зоне со странами, куда отправляете (например, «Европа»), добавляете метод «Ukrposhta International» и выбираете тип отправления и транспорт.
3. Товары. В товарах, которые продаёте за границу, заполняете код УКТВЭД и название латиницей — или задаёте значения по умолчанию в настройках.
4. Корзина. Покупатель вводит адрес за границей — плагин спрашивает тариф Укрпочты для его страны, веса и коробки и показывает цену. Ответы кэшируются, повторная загрузка корзины не шлёт новый запрос.
5. Чекаут. Адрес должен быть латиницей, телефон — обязателен; иначе покупатель видит, какие поля исправить.
6. Заказ. В заказе сохраняются стоимость доставки, вес и тип отправления.
7. Отправление (Pro). Менеджер создаёт международное отправление из карточки заказа, печатает CN22 или CN23 и ярлык, покупатель получает трек-номер в письме.

Что под капотом

• Тариф — POST /international/delivery-price eCom API Укрпочты: вес в граммах, самая длинная сторона, ширина, высота, страна, тип отправления и транспорт. Для США — ещё категория и товары с кодами УКТВЭД и стоимостью в долларах, как требует Укрпочта.
• Отказ Укрпочты — не ошибка магазина. Страна или тип, которые Укрпочта не принимает, просто не дают метода; автоматический режим сам переходит с мелкого пакета на посылку.
• Кэш тарифов в транзиентах; при сбое API — скрыть метод или показать фиксированную цену. После изменения настроек или лицензии ставки в уже открытой корзине пересчитываются сразу.
• Отправление (Pro) — адрес (/addresses), получатель-нерезидент (/clients) и отправление типа INTERNATIONAL с таможенными позициями (/shipments); бланки — через сервис форм Укрпочты.
• Ключи — AES-256-CBC с HMAC, без XOR.
• Pro-гейт без «кирпича»: когда триал закончился, останавливаются только Pro-функции, тариф в корзине работает дальше.
• Удаление плагина убирает настройки, кэш тарифов, задания крона и методы в зонах доставки. Трек-номера в заказах и коды УКТВЭД в товарах остаются как данные магазина.

Как установить

1. Плагины → Добавить новый → Загрузить плагин: выберите ukrposhta-international-for-woocommerce-1.0.1.zip и активируйте.
2. WooCommerce → Ukrposhta International: вставьте eCom Bearer, сохраните и нажмите «Проверить».
3. WooCommerce → Настройки → Доставка → зона со странами, куда отправляете → Добавить метод доставки → «Ukrposhta International».
4. В товарах, которые продаёте за границу: Данные товара → Доставка — код УКТВЭД и название латиницей.
5. Если стоит наш модуль «Укрпочта» с включёнными международными отправлениями — отключите их там, чтобы покупатель не видел два варианта Укрпочты за границу.
6. Для Pro: вставьте лицензионный ключ из письма после оплаты или запустите 7-дневный триал.