README

NovaDigital_NovaPostShipping integrates Nova Post delivery services into Magento 2 checkout and Magento Admin order management.

The module is built as an MVP-first Magento-native integration:

• standard Magento carrier collectRates;
• standard checkout shipping address/rate flows;
• Magento Admin Order Grid and Order View extensions;
• Nova Post API communication delegated to novadigital/novapost-api-sdk;
• no native Magento Shipment entity creation;
• no Nova Post API calls during Admin Grid/View rendering;
• shipment state is stored in module-owned read model tables.

Features

Checkout delivery methods

The module provides Nova Post shipping methods for checkout:

• Nova Post Delivery — delivery to Nova Post branch/division.
• Nova Post Address — delivery to customer address.

Both methods are exposed under the Nova Post carrier.

Nova Post Delivery widget

For branch/division selection, the frontend uses the Nova Post widget SDK.

Widget country/city prefill follows checkout context:

• for an existing saved customer address, selected quote.shippingAddress() is the source of truth;
• for a new/edit address form, live checkout form fields are used;
• fallback values are used only when the primary source is empty.

This avoids using stale Magento default country values when the customer selected a saved address.

Division-selection lifecycle follows checkout address context:

• changing checkout country, region, city, postcode, or street clears the previously selected Nova Post division;
• switching between Nova Post delivery methods clears stale division state as well;
• the widget is updated in place where the SDK supports it, with full reinitialization kept only as a fallback.

Unavailable checkout rows follow Magento carrier visibility:

• if carrier config hides not-applicable methods, Nova Post unavailable rows are not rendered;
• if showmethod is enabled, unavailable Nova Post rows remain visible and are rendered as informational notices instead of hard checkout errors.

Delivery rate calculation

Nova Post Delivery does not use a temporary $0.00 placeholder.

Expected behavior:

• if a customer already selected a division, the rate is calculated for that selected division;
• if no division is selected yet, but checkout address has city or postcode, the module performs a preliminary division lookup and calculates a rate for display only;
• the preliminary division is not persisted as the customer's selected branch;
• if city/postcode is not available and no division is selected, the method is not returned as a zero-price rate;
• $0.00 is valid only for configured Free Delivery override.

Address rate calculation

Nova Post Address can be calculated immediately because address delivery can use the current checkout address context.

Supported calculation branches:

1. Free Delivery override.
2. Flat Rate.
3. Nova Post carrier calculation API.

Currency conversion

Nova Post shipment calculation remains the source of truth for delivery amount.

If the currency returned by Nova Post matches Magento Base Currency, no conversion is performed.

If currencies differ:

1. Nova Post exchange-rates conversion API is used first.
2. If Nova Post conversion is unavailable or does not return the requested target currency, Magento configured currency rates are used as fallback.
3. If neither source can convert the amount, a LocalizedException is raised and the Nova Post method is not returned for that rate request.

The fallback is limited to currency conversion only. It does not replace Nova Post shipment calculation.

Admin order management

Admin settings pages

The module exposes two Magento Admin System Config sections:

• Nova Post > Base
• Nova Post > Settings

ACL access is split as follows:

• NovaDigital_NovaPostShipping::base_view — Base section access;
• NovaDigital_NovaPostShipping::settings_view — Settings section access.

Order Grid

The module adds Nova Post shipment information to the Magento Sales Order Grid.

The grid displays:

• Nova Post shipment number;
• shipment status;
• method label;
• latest shipment action errors.

The Order Grid uses local database/read-model data only. It does not call Nova Post API while rendering the grid.

Order View

The module adds a Nova Post section to the Magento Admin Order View.

The section displays:

• Nova Post shipping method;
• shipment number;
• shipment status;
• latest action errors.

The Order View also uses local database/read-model data only. It does not call Nova Post API during rendering.

Shipment actions

Supported Admin shipment actions:

• create shipment;
• print documents;
• delete shipment;
• mass create;
• mass print.

Supported print document types:

• marking (Label printing);
• international (Customs declaration);
• invoice (Invoice printing).

Print request mapping:

Document type	Nova Post type	printSizeType
marking	marking	size_100_100
international	international	A4
invoice	invoice	A4

Print UX behavior:

• single-order print opens a PDF preview modal before download;
• mass print opens a bulk PDF preview modal before download;
• PDF download is triggered from the preview modal.

Shipment type and invoice payload rules

Shipment type is resolved from:

• sender country from Nova Post configuration;
• recipient country from the order shipping address.

Supported shipment types:

• domestic — sender and recipient are in the same country;
• eu — sender and recipient are in different countries, but both belong to the EU;
• cross-border — sender and recipient belong to different customs zones.

Document availability follows shipment type:

• domestic / eu — Label only;
• cross-border — Label, Customs declaration, and Invoice.

Invoice payload rules:

• invoice is included only for cross-border shipments;
• invoice remains null for domestic and eu shipments;
• invoice currency follows Magento order/quote display currency;
• invoice total and item commercial values are converted into that same invoice currency before payload submission.

Shipment idempotency

The MVP assumes one Nova Post shipment per Magento order.

The shipment read-model table enforces this with a unique constraint on:

nova_post_order_shipment.order_id

Create shipment flow also checks existing shipment state and prevents creating another Nova Post shipment for the same order.

No native Magento Shipment entity

The module does not create Magento native Shipment entities.

Nova Post shipment state is stored in the module table:

nova_post_order_shipment

This keeps the MVP integration isolated from Magento native fulfillment flows.

Shipment action errors

Shipment action errors are persisted for Admin visibility.

Current behavior:

• only the latest failure is stored per order_id + action_type;
• repeated failures for the same action replace the previous stored error;
• read path also deduplicates older duplicate rows by latest created_at/entity_id.

Success cleanup rules:

Successful action	Errors cleared
create	create, mass_create
print	print_<documentType>, mass_print_<documentType>
delete	all errors for the order

Error persistence is intentionally non-blocking. If recording or clearing an error fails, the module logs a warning and does not break the shipment business flow.

Logs must not include customer PII. Only operational metadata should be logged.

Tracking links

Shipment numbers are rendered as tracking links where applicable.

Admin tracking links

In Admin Order Grid and Admin Order View, tracking URL localization uses the Store View locale.

Examples:

Store View locale	Tracking prefix
uk_UA	uk-ua
pl_PL	pl-pl
de_DE	de-de
cs_CZ	cs-cz

If the locale is not supported by Nova Post URL prefixes, the module falls back to:

en-gb

Example:

https://novapost.com/pl-pl/tracking/SHPL1234567890

Localization

The module includes built-in translation files for the following locales:

• en_US
• cs_CZ
• de_DE
• uk_UA

These translations are used together with the corresponding Magento Store View locale configuration.

Customer tracking email

Customer shipment tracking email uses the shipping address country.

Examples:

Shipping country	Tracking prefix
UA	uk-ua
PL	pl-pl
DE	de-de
CZ	cs-cz

Customer tracking email send-state is tracked by tracking_email_sent_shipping_number. The email is sent once per created shipping_number and is sent again only when a new shipment is created with a different shipping number.

Product attributes

The module adds Nova Post product attributes under the Nova Post product attribute group.

Attributes:

• hs_code;
• product_title_en;
• length;
• width;
• height.

Validation:

HS code

Optional. If filled, it must contain 8–10 digits.

Valid examples:

12345678
1234567890

Invalid examples:

1234567
12345678901
ABC12345

Default HS code shipment fallback

Admin UI uses manual HS code entry with backend validation. Async HS code lookup is not part of the current Magento module UI flow.

Shipment invoice HS code resolution order:

1. product attribute hs_code;
2. module default_hs_code;
3. Nova Post classifier lookup through GetHscodeService;
4. empty value if no classifier match is returned.

Dimensions

Optional numeric positive values.

Rules:

Attribute	Minimum	Maximum
length	0.1	300.0
width	0.1	170.0
height	0.1	170.0

Values are normalized to one decimal place.

Invalid examples:

0.05
-5
abc
1,2

The data patch is idempotent and does not remove existing merchant values.

Departure division search in Admin settings

The Admin departure division search displays branch results in two lines:

1. Accent/title line:

   City Name/Number (max weight: Xkg)
   

2. Address line:

   postcode, country/region/city/street/building
   

Missing address parts are skipped without producing empty commas. UPS PUDO points are excluded from seller departure selection. Displayed weight is normalized from raw API grams to kilograms for admin readability. If the Nova Post API already returns a complete division title, the UI does not prefix the city again after selection.

Logging

The module uses Magento logging infrastructure.

Expected log behavior:

• debug — diagnostic payload/rate details after sensitive data sanitization;
• info — successful operational events;
• warning — recoverable non-blocking issues;
• error — failed business/API operations.

Do not log PII. Logs should include operational identifiers only, for example:

• order id;
• quote id;
• store id;
• action type;
• exception class;
• currency pair;
• non-sensitive status metadata.

Installation / upgrade

From the Magento application root:

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

If frontend/admin static assets need cleanup:

rm -rf pub/static/adminhtml/Magento/backend/*/NovaDigital_NovaPostShipping
rm -rf pub/static/frontend/*/*/*/NovaDigital_NovaPostShipping
rm -rf var/view_preprocessed/pub/static/adminhtml/Magento/backend/*/NovaDigital_NovaPostShipping
rm -rf var/view_preprocessed/pub/static/frontend/*/*/*/NovaDigital_NovaPostShipping

php bin/magento cache:clean

If static content deployment is required:

php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Development checks

PHP lint

Run PHP lint for changed files, for example:

php -l src/Model/Shipment/CreateShipmentService.php
php -l src/Model/Carrier/Rate/Resolver/DeliveryRateResolver.php
php -l src/Block/Adminhtml/Order/View/NovaPostSection.php
php -l src/Ui/Component/Listing/Column/NovaPostShipmentInfo.php

Dependency injection compile

php bin/magento setup:di:compile

JavaScript syntax checks

Run from the module repository:

find src/view -type f -name '*.js' -print0 | xargs -0 -n1 node --check

Manual smoke checklist

Checkout

• Saved customer address with country UA opens the Nova Post widget with Ukraine context.
• New/edit address form country switch updates widget country.
• Changing country, region, city, postcode, or street clears stale Nova Post division selection.
• Switching Nova Post Delivery → Nova Post Address or back clears stale division selection.
• Nova Post Address method calculates successfully.
• Nova Post Delivery with city/postcode does not show temporary $0.00.
• Nova Post Delivery after selected branch recalculates using selected division.
• Nova Post Delivery without selected branch is blocked by backend validation when placing order.
• Switching Delivery → Address/non-NovaPost does not use stale division payload.
• If showmethod is enabled, unavailable Nova Post methods render as checkout notices instead of hard errors.
• Cart quantity/item changes trigger shipping rate recalculation.
• Currency conversion works through Nova Post exchange API.
• Magento currency rate fallback works when Nova Post exchange conversion is unavailable.
• If conversion cannot be performed, checkout does not fail globally.

Admin Order Grid

• Nova Post column displays shipment state.
• Shipment number link opens in a new browser tab.
• Tracking link locale follows Store View locale.
• Grid render does not call Nova Post API.
• No duplicate rows are introduced.
• Latest action errors are visible.

Admin Order View

• Nova Post section is visible for Nova Post orders.
• Shipment method, number and status are displayed.
• Shipment number link opens in a new browser tab.
• Tracking link locale follows Store View locale.
• Order View render does not call Nova Post API.
• Latest action errors are visible.
• Create shipment refreshes the Nova Post section without full page reload.
• Delete shipment refreshes the Nova Post section without full page reload.

Shipment actions

• Create shipment succeeds for a valid Nova Post order.
• domestic / eu shipments expose only Label print action.
• cross-border shipments expose Label, Customs declaration, and Invoice print actions.
• Create shipment preview shows Sender / Recipient / Parcels / Items / Totals / Note sections.
• Address-delivery preview shows address fields instead of Division / Division Address.
• Cross-border invoice payload uses order/quote display currency for invoice.currency, invoice.cost, and invoice.items[*].cost.
• Repeated create after successful shipment is blocked.
• Only one shipment row exists per order.
• Repeated create failures store only the latest error.
• Successful create clears create-related errors.
• Single print opens PDF preview modal.
• Single print modal renders preview PDF.
• Single print modal download works.
• Print marking works.
• Print international works where applicable.
• Print invoice works where applicable.
• Mass print opens bulk PDF preview modal.
• Mass print modal renders preview PDF.
• Mass print modal download works.
• Mass print works.
• Successful print clears relevant print errors.
• Delete shipment works.
• Delete shipment from Order Grid preserves filters and pagination.
• Successful delete clears all shipment action errors.

Product attributes

• Attributes exist under product edit group Nova Post.
• Empty HS code is allowed.
• HS code with 8–10 digits is allowed.
• Invalid HS code values are rejected.
• Shipment flow uses classifier fallback when product/default HS code is missing.
• Empty dimensions are allowed.
• Valid dimensions are normalized to one decimal place.
• Invalid dimension values are rejected.

Admin departure division search

• Departure-division selection does not duplicate the city if the returned division title already contains the settlement/branch title.

Known MVP boundaries

The following items are intentionally not part of the current MVP unless explicitly required by QA or follow-up scope:

• native Magento Shipment entity creation;
• storing tracking_email_sent_at as a dedicated timestamp field;
• full custom shippingMethodMessages UI mechanism for every hidden-rate scenario;
• custom settings-page flash behavior beyond Magento-native messages.