Ukrposhta — доставка Укрпоштою для OpenCart 2.3, 3.x & 4.x

Ukrposhta Shipping для OpenCart 4 — модуль доставки Укрпоштою: віджет вибору відділення (область → місто → відділення) у чекауті на базі офіційного Адресного класифікатора та живий розрахунок вартості доставки по Україні через eCom API. Обране покупцем відділення фіксується в замовленні, тож менеджеру не доводиться перепитувати адресу в месенджері.

Модуль безкоштовний. Встановлюється як стандартне розширення OpenCart (ocmod) і не потребує правок теми — віджет підключається через систему подій.

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

1. Адмін встановлює розширення, натискає «Встановити» на сторінці налаштувань — модуль створює свої таблиці, події та cron-завдання, — і синхронізує області одним кліком.
2. Вводяться Bearer eCom та індекс відправника; кнопки «Перевірити з’єднання» і «Тестовий тариф» одразу показують, що ключ прийнято і API відповідає.
3. Покупець у чекауті обирає доставку Укрпоштою — подія footer/after підключає віджет, і він веде по ланцюжку область → місто → відділення.
4. Модуль запитує тариф у eCom API за індексами відправника й отримувача; якщо API недоступний — показується тариф за замовчуванням із налаштувань.
5. Після оформлення подія order.addOrder/after зберігає обране відділення (індекс, місто, назву) разом із замовленням.
6. Раз на тиждень cron OpenCart оновлює кеш класифікатора областей — довідник не застаріває.

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

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

Безкоштовно. Завантажуєте ukrposhta-1.2.0.ocmod.zip зі сторінки модуля і користуєтесь без підписок та платних версій.

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

• OpenCart 4.0.2 – 4.1.x
• PHP 7.4 і новіші
• Договір eCom з Укрпоштою: Bearer-ключ видається в кабінеті eCom після підписання договору — він потрібен для класифікатора адрес і розрахунку тарифу
• Для розрахунку тарифу — поштовий індекс складу відправника

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

• Bearer-ключ шифрується перед записом у базу; у формі налаштувань показується лише маска «збережено», без відкритого значення.
• Класифікатор кешується у власних таблицях (up_regions, up_cities, up_offices) — чекаут читає локальну базу, а не смикає API на кожен запит.
• Інтеграція через події OpenCart (footer inject, order added) — без OCMOD-патчів контролерів і правок шаблонів теми.
• Стандартні для методів доставки OpenCart налаштування: гео-зона, клас податку, порядок сортування.
• Вигляд віджета налаштовується: акцентний колір, радіус заокруглення, тема (авто/світла/темна).
• Є перемикач sandbox для роботи з тестовим середовищем Укрпошти.

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

1. Завантажте збірку під свою версію та встановіть через «Розширення → Встановлення розширень»: ukrposhta-1.2.0.ocmod.zip для 4.x, ukrposhta-oc3-1.2.0.ocmod.zip для 3.x, ukrposhta-oc2-1.1.0.ocmod.zip для 2.3.
2. У «Розширення → Розширення → Доставка» знайдіть «Укрпошта — доставка» і натисніть Install.
3. Відкрийте налаштування, натисніть «Встановити» — створяться таблиці, події та cron-завдання.
4. Введіть Bearer eCom та індекс відправника, натисніть «Перевірити з’єднання», потім «Синхронізувати області».
5. Увімкніть метод доставки та збережіть — віджет вибору відділення з’явиться в чекауті.

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

1.2.0 (4.x, 3.x) · 1.1.0 (2.3) — 20 серпня 2026

Зʼявився розрахунок міжнародної доставки. Для адрес поза Україною тариф рахується по країні призначення та вазі, відділення обирати не треба: у чекауті зʼявляється перемикач «Інша країна», який повертає звичайну адресну форму. У налаштуваннях задаються спосіб перевезення (авіа чи наземний), тип відправлення, категорія вкладення і валюта тарифу. Якщо Укрпошта не може порахувати напрямок (частина країн закрита під конкретний тип відправлення), покупець бачить причину, а не вигадану суму з запасної ставки. Перевірено наживо: Польща 1 кг — 867 грн, 5 кг — 1500 грн, Канада 3 кг — 1627 грн.

1.1.2 (4.x) · 1.1.1 (3.x) · 1.0.1 (2.3) — серпень 2026

Живий тариф Укрпошти нарешті рахується. Виявилось, що запит /domestic/delivery-price не проходив узагалі: вимірювання треба слати в parcels, а індекс відправника — рядком (01001 перетворювався на 1001, і API відхиляв запит). До цього у вітрині завжди показувалась фіксована ставка з налаштувань. Перевірено наживо на всіх трьох платформах: Київ → Дрогобич, 3 кг — 55 грн, з оголошеною цінністю — 67,50, комісія за післяплату — 65.

3.x 1.1.0 — 11 серпня 2026

Збірка для OpenCart 3 підтягнута до рівня 2.3 і 4.x. Віджет тепер ховає в кроці доставки лише ті поля, які сам і заповнює: імʼя та прізвище отримувача лишаються на екрані — раніше вони ховались разом з адресою, і «Продовжити» впиралось у помилку на невидимому полі. Область у нативному списку проставляється надійно: OpenCart перезавантажує перелік областей після зміни країни, тож вибір повторюється кілька секунд, поки список не осяде. Якщо покупець перемикається на іншого перевізника, нативна адресна форма повертається (раніше вона лишалась схованою назавжди). Обране відділення тепер штампується в адресу замовлення на сервері, а чернетка відправлення більше не створюється для замовлень з іншим способом доставки. Без ключа Укрпошти працює офлайн-список областей, місто і 5-значний індекс вводяться вручну. Нульовий тариф підписується «оплата при отриманні», а не «0 ₴». Захист адреси перенесено на події OpenCart 3 — ядрові файли чекауту не патчаться.

1.1.0 — 5 серпня 2026

Полагоджено мертвий поліфіл PHP 7.4: у файл поліфілів був скопійований WordPress-гард ABSPATH, якого в OpenCart не існує ніколи — тож підключення файлу обривало весь запит, функції не оголошувались, і сторінка вмирала порожньою. Тепер модуль реально працює на PHP 7.4. Подія addOrder реєструється одним правилом із * — воно покриває і 4.0.x, і 4.1.x (раніше писалось два рядки, і на 4.0.2 подія дублювалась); старий рядок прибирається при встановленні. В адмінці прибрано другий контейнер сповіщень, через який тости про збереження виводились не туди, а підказка «перший запуск — натисніть Встановити» більше не висить на вже встановленому модулі.

1.0.12 — 24 липня 2026

Віджет підскролюється у видиму зону, щойно обрано Укрпошту — на мобільному він рендериться вище селектора методів доставки, і його легко було не помітити.

1.0.11 — 24 липня 2026

Пошук міста більше не падає мовчки без розширення mbstring: mb_strlen / mb_strtolower під гардом, автодоповнення працює на будь-якому хостингу.

1.0.10 — 23 липня 2026

Збереження контактних даних більше не скидає вже обраний спосіб доставки й оплати.

1.0.8–1.0.9 — 23 липня 2026

Адреса замовлення заповнюється точно тим, що обрав покупець (місто з класифікатора, область кирилицею, реальний індекс відділення), плюс ручне введення індексу.

1.0.4 — 23 липня 2026

Виправлено фатальну помилку у розрахунку способів доставки: getQuote() завантажував неіснуючу в OpenCart 4.x catalog-модель localisation/geo_zone, через що увесь список способів доставки не з’являвся («Потрібна адреса доставки»). Гео-зона тепер перевіряється прямим запитом до zone_to_geo_zone. Плюс: блок область → місто → відділення з’являється лише після вибору методу «Укрпошта» (спочатку метод — потім поля), і має демо-набір областей/міст/відділень для клікабельного тесту без Bearer-ключа eCom.

1.0.0 — липень 2026

Перший публічний реліз: віджет область → місто → відділення в чекауті, живий тариф по Україні через eCom API, шифрування ключа, щотижнева синхронізація класифікатора через cron.