Ukrposhta — вибір відділення + тариф для WooCommerce

Ukrposhta Shipping for WooCommerce — плагін доставки Укрпоштою для магазинів на WooCommerce. Покупець обирає відділення прямо в чекауті за ланцюжком область → місто → відділення, а вартість доставки рахується наживо через офіційний eCom API Укрпошти. Дані беруться з офіційного Адресного класифікатора, тож список відділень завжди актуальний, а обраний поштовий індекс зберігається в замовленні.

Плагін повністю безкоштовний. Код відкритий — репозиторій на GitHub (catcodestudio/woocommerce-ukrposhta-shipping), ліцензія GPLv2.

Як це виглядає для покупця

Після вибору методу «Укрпошта» в чекауті з’являється віджет: покупець обирає область, потім місто, потім конкретне відділення. Щойно відділення обрано — плагін запитує тариф у eCom API (з урахуванням ваги кошика й індексів відправника та отримувача) і показує реальну вартість доставки. Акцентний колір віджета налаштовується під дизайн теми.

Що отримує адмін

Метод додається у зону доставки WooCommerce, а креденшели глобальні — один Bearer на весь магазин, незалежно від кількості зон. В налаштуваннях: тестове середовище (sandbox dev.ukrposhta.ua), тип послуги (Стандарт або Express), тариф за замовчуванням на випадок недоступності API та поріг безкоштовної доставки від суми замовлення. Обране покупцем відділення видно прямо в замовленні — окремий блок «Укрпошта» з містом, відділенням та індексом, а також рядком у листах і на сторінці подяки.

Як це працює — крок за кроком

1. Адмін вводить Bearer eCom та індекс відправника, додає метод «Укрпошта» у зону доставки.
2. Покупець у чекауті обирає доставку Укрпоштою — з’являється пікер область → місто → відділення на базі офіційного Адресного класифікатора.
3. Плагін рахує вагу кошика й запитує тариф через ендпоінт /domestic/delivery-price; якщо API недоступний — підставляється фіксована ставка з налаштувань.
4. Якщо покупець обрав післяплату, у тариф додається комісія Укрпошти за неї — і зникає, щойно він перемкнеться на передоплату.
5. Якщо сума замовлення перевищує заданий поріг — доставка стає безкоштовною.
6. Покупець оформлює замовлення — обраний поштовий індекс відділення зберігається в замовленні й доступний адміну для відправлення.

Скільки коштує

Безкоштовно. Плагін розповсюджується під ліцензією GPLv2, код відкритий на GitHub. Платних версій чи підписок немає.

Технічні вимоги

• WordPress 5.6+ (протестовано до 6.7)
• WooCommerce 6.0+ (протестовано до 10.7)
• PHP 7.4+
• Договір eCom з Укрпоштою: Bearer-ключ видає ваш менеджер Укрпошти після підписання договору — він потрібен і для класифікатора адрес, і для тарифу

Що під капотом

• Bearer-ключ зберігається зашифрованим (at-rest), у формі налаштувань назад у відкритому вигляді не показується.
• Довідник відділень кешується в окремій таблиці upwc_offices, список областей — у транзієнті: чекаут не смикає API Укрпошти на кожне відкриття.
• Сумісність з HPOS (custom order tables) задекларована офіційно; мета замовлення знімається і на класичному чекауті, і на Store API (блоковому) шляху.
• Тариф враховує вагу товарів у кошику, оголошену цінність (за бажанням) і комісію за післяплату — але лише для тих способів оплати, які ви позначили як післяплату.
• Обране відділення входить у пакет доставки WooCommerce, тож зміна відділення чи способу оплати перераховує тариф, а не показує закешований.
• Пошук міста розуміє латиницю: «Drohobych» знаходить Дрогобич.
• Translation-ready: текстовий домен і всі рядки готові до перекладу.

Як встановити

1. Завантажте ukrposhta-shipping-for-woocommerce-1.2.0.zip і встановіть через «Плагіни → Додати новий → Завантажити плагін».
2. Активуйте плагін — таблиця кеша відділень створиться автоматично.
3. Перейдіть у WooCommerce → Налаштування → Доставка та додайте метод «Укрпошта» у потрібну зону.
4. Введіть Bearer eCom та індекс відправника, збережіть.
5. Увімкніть метод — пікер відділення з’явиться в чекауті.

Історія версій

1.2.0 — 20 серпня 2026

Зʼявився розрахунок міжнародної доставки: для адрес поза Україною тариф рахується по країні призначення та вазі, відділення для цього не потрібне. Метод достатньо додати в зону доставки з потрібними країнами. У налаштуваннях задаються спосіб перевезення (авіа чи наземний), тип відправлення, категорія вкладення і валюта тарифу. Якщо Укрпошта не рахує напрямок, метод не показується з вигаданою ціною: причина пишеться у «WooCommerce → Статус → Журнали». Перевірено наживо: Польща 1,5 кг — 945 грн.

1.1.1 — серпень 2026

Вихідні рядки переведені на англійську, українська поїхала окремим перекладом у складі плагіна — тепер модуль можна перекласти будь-якою мовою, а українською він виглядає так само. Підписи віджета в чекауті теж стали перекладними. Підготовлена збірка для каталогу wordpress.org.

1.1.0 — серпень 2026

Живий тариф Укрпошти нарешті рахується: вимірювання треба слати в parcels, а індекс відправника — рядком (01001 перетворювався на 1001, і API відхиляв запит). До цього в чекауті завжди показувалась фіксована ставка. Комісія за післяплату більше не додається до передоплачених замовлень. Обране відділення видно в замовленні, в листах і на сторінці подяки. Чекаут не пропускає замовлення без обраного відділення. Оголошена цінність стала опційною. Пошук міста розуміє латиницю. Віджет ховається, доки не обрано Укрпошту, і не зʼявляється на сторінці подяки.

1.0.1 — липень 2026

Робота на хостингах без mbstring: пошук міст і опис посилки більше не мовчали. Планку вимог знижено до WordPress 5.6 / WooCommerce 6.0 / PHP 7.4.

1.0.0 — липень 2026

Перший публічний реліз: пікер відділення (область → місто → відділення) у чекауті та живий розрахунок тарифу через eCom API з фолбеком на фіксовану ставку.