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-денний тріал.