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. Покупець оформлює замовлення — обраний поштовий індекс відділення зберігається в замовленні й доступний адміну для відправлення.

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

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

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

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