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