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

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

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

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

На шаге доставки покупатель видит группу «Укрпочта за границу» с теми вариантами, которые вы включили и которые Укрпочта принимает в его страну: посылку и мелкий пакет, авиа или наземно. Цена — собственный тариф Укрпочты для его страны, веса корзины и коробки, пересчитанный из гривны в валюту магазина. Вариант, на который Укрпочта не дала цены, покупателю не показывается: например, мелкие пакеты в Польшу Укрпочта не принимает — и там остаётся только посылка. Для адресов в Украине группа не появляется никогда.

Тарифы на все варианты запрашиваются одновременно и кэшируются на 6 часов, так что повторный шаг доставки не ждёт Укрпочту. Если Укрпочта не ответила вовремя, корзина 5 минут не спрашивает её снова и не тормозит оформление.

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

• Варианты доставки: какие типы показывать, название в корзине, лимит веса, порядок; геозона, класс налога и страны, куда не отправляете. С Pro — ещё EMS и мелкий пакет PRIME, наценка в процентах и фиксированная, округление вверх и бесплатная доставка от суммы.
• API Укрпочты: eCom Bearer, токен пользователя, отдельный Bearer для трекинга по желанию, тестовая среда dev.ukrposhta.ua. Токены хранятся зашифрованными и не печатаются в форме.
• «Сохранить и проверить соединение» запрашивает тариф посылки 1 кг в Польшу, затем проверяет токен и отправителя. В вашем кабинете Укрпочты ничего не создаётся.

• Упаковка: вес для товаров без веса, вес упаковки, коробка по умолчанию; если в товарах заполнены размеры, коробка считается из них. Громоздкие посылки и объявленная ценность — переключателями.
• Таможня: категория отправления (отдельно для EMS — Укрпочта не принимает EMS с «Продажей товаров»), поле товара, из которого брать код УКТВЭД (например, MPN), код и страна происхождения по умолчанию, описание товара латиницей — английское название или транслитерация.
• Отправитель создаётся в Укрпочте прямо из настроек (ФЛП, юрлицо или физлицо, адрес латиницей), или вставляете UUID существующего отправителя.

• Отправление со страницы заказа. Панель «Ukrposhta International» собирает черновик: тип и транспорт из выбранного покупателем варианта, вес, коробку, получателя латиницей (транслитерация из заказа, можно исправить), товары для декларации с кодами УКТВЭД и стоимостью. Строки с одинаковым кодом сливаются до лимита Укрпочты — 4 строки, для EMS 5.
• Проверки до отправки: размытые названия (Gift, Souvenir, Accessories…), больше 32 символов, кириллица, длина кода УКТВЭД для США и ЕС — модуль останавливает ещё до запроса к Укрпочте.
• После создания: трек-номер в панели и в истории заказа, PDF всех бланков, CN22 или CN23 и наклейки, «Обновить статус», удаление отправления. С Pro отправление создаётся само на выбранном статусе заказа, а статусы обновляются ежечасно; врученный заказ переходит в выбранный статус.

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

1. Ключи. Вкладка «API Укрпочты»: eCom Bearer и токен пользователя, «Сохранить и проверить соединение».
2. Отправитель. Вкладка «Отправитель»: создайте отправителя в Укрпочте из данных магазина латиницей или вставьте UUID существующего.
3. Варианты. Вкладка «Варианты доставки»: включите статус и нужные типы, выберите геозону.
4. Таможня. Вкладка «Упаковка и таможня»: поле с кодом УКТВЭД, код и страна по умолчанию, описание латиницей.
5. Корзина. Покупатель с адресом за границей видит «Укрпочта за границу» с ценами Укрпочты; в заказе сохраняются метод и стоимость доставки.
6. Отправление. На странице заказа — «Создать отправление», затем бланки PDF и статус. С Pro — автоматически на статусе заказа и с ежечасной синхронизацией.

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

• Тариф — POST /international/delivery-price eCom API Укрпочты для каждого включённого варианта параллельно (curl_multi); ответы кэшируются на 6 часов, отказ «not available» — на 12.
• Отправление — адрес и клиент получателя латиницей, затем отправление типа INTERNATIONAL с таможенными позициями; бланки и наклейки — из сервиса форм Укрпочты, статусы — из трекинга Укрпочты.
• Без патчей ядра. Никаких ocmod-модификаций: события OpenCart и собственные таблицы cc_upintl_shipment (отправления) и cc_upintl_kv (кэш тарифов и копия настроек).
• Токены — AES-256 с HMAC, без XOR.
• Pro-гейт без «кирпича»: когда триал закончился, останавливаются только Pro-функции.
• Удаление (Расширения → Доставка → Удалить) снимает события и задания крона, а таблицы cc_upintl_kv (копия настроек с зашифрованными токенами, отправителем и ключом лицензии) и cc_upintl_shipment (история отправлений) остаются: после повторной установки настройки возвращаются сами, поэтому обновление их не сбрасывает. Чтобы убрать всё, включите во вкладке «API Укрпошти» опцию «Удалять все данные модуля при удалении» (по умолчанию выключена): тогда удаление стирает обе таблицы, настройки и журнал модуля.

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

1. OpenCart 4: Расширения → Установка расширений → загрузите cc_upintl.ocmod.zip и нажмите «Установить». Имя файла не меняйте — это код расширения.
2. OpenCart 3: Расширения → Установка расширений → загрузите cc_upintl-oc3.ocmod.zip.
3. OpenCart 2.3: Расширения → Установка расширений → cc_upintl-oc2.ocmod.zip; без FTP — скопируйте upload/ из архива в корень магазина.
4. Расширения → Доставка → Ukrposhta International → Установить → Редактировать: ключи, отправитель, варианты, таможня.
5. OpenCart 4: включите телефон при оформлении (Настройки → Опции).
6. Если стоит наш модуль «Укрпочта» с включённым «Считать международную доставку» — отключите эту опцию там.
7. Для Pro: вставьте лицензионный ключ из письма после оплаты на вкладке «Лицензия» или запустите 7-дневный триал.