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

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

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

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

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

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

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

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

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

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

1.0.0 — липень 2026

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