Ukrposhta — Ukrposhta shipping for OpenCart 2.3, 3.x & 4.x

Ukrposhta Shipping for OpenCart 2.3, 3.x and 4.x is a Ukrposhta shipping module: a branch-picker widget (region → city → branch) at checkout, based on the official Address Classifier, and live domestic shipping-cost calculation via the eCom API. The branch the customer picked is recorded on the order, so a manager doesn’t have to ask for the address again over messenger.

The module is free. It installs as a standard OpenCart extension (ocmod) and needs no theme edits — the widget hooks in via the event system.

How it works, step by step

1. The admin installs the extension, clicks “Install” on the settings page — the module creates its tables, events and cron tasks — and syncs regions with one click.
2. The eCom Bearer token and sender index are entered; “Test connection” and “Test rate” buttons instantly confirm the key is accepted and the API responds.
3. At checkout, the customer chooses Ukrposhta delivery — the footer/after event loads the widget, which walks through region → city → branch.
4. The module requests a rate from the eCom API using the sender’s and recipient’s postal indices; if the API is unavailable, a default rate from the settings is shown instead.
5. After checkout, the order.addOrder/after event saves the chosen branch (index, city, name) along with the order.
6. Once a week the region classifier cache is refreshed — the directory never goes stale. On OpenCart 4 the built-in cron does it; on 3.x and 2.3, a link for the system crontab shown in the module settings.

Under the hood

• The Bearer key is encrypted before being written to the database; the settings form shows only a “saved” mask, never the plain value.
• The classifier is cached in the module’s own tables (up_regions, up_cities, up_offices) — checkout reads the local database rather than hitting the API on every request.
• Integration is via OpenCart events (footer inject, order added) — no theme template edits; the 4.x and 3.x builds have no OCMOD controller patches, while the 2.3 build adds a small OCMOD patch that saves the address at checkout.
• Standard OpenCart shipping-method settings: geo-zone, tax class, sort order.
• The widget’s look is configurable: accent colour, corner radius, theme (auto/light/dark).
• The OpenCart 4 build has a sandbox toggle for working against Ukrposhta’s test environment.

How to install

1. Download the build for your version and install it via “Extensions → Installer”: ukrposhta.ocmod.zip for 4.x, ukrposhta-oc3-1.2.4.ocmod.zip for 3.x, ukrposhta-oc2-1.1.5.ocmod.zip for 2.3.
2. In “Extensions → Extensions → Shipping” find “Ukrposhta shipping” and click Install.
3. Open the settings and click “Install” — the tables, events and cron tasks are created.
4. Enter the eCom Bearer token and sender index, click “Test connection”, then “Sync regions”.
5. Enable the shipping method and save — the branch-picker widget will appear at checkout.