README

🇵🇱 Polska wersja dla merchantów: README.pl.md

The VonHalsky module connects Magento 2 stores with InPost marketplace services. It synchronises offers, categories, orders, and related events while giving merchants intuitive admin tools to manage mappings and monitor activity.

✨ Productization — the game-changer. VonHalsky's standout feature reads product data straight from InPost's catalog by EAN (the /hints endpoint) and pre-fills the whole offer for you — category, attributes, brand and more. In practice this removes the need to map categories or attributes by hand: pick a product, review the pre-filled offer, and publish. Creating marketplace offers becomes genuinely fast and effortless.

📦 Distribution. The module is published on Packagist and installed with Composer — see Installation.

Resource Menu

User Guide (Quick Start)
Installation
Scheduled Cron Jobs
Admin & CLI Operations

Requirements

Magento Open Source / Adobe Commerce 2.4.6–2.4.8
PHP 8.1 or newer
Composer 2.x
Valid VonHalsky OAuth2 credentials (Client ID & Client Secret)
Working Magento cron and access to the Magento CLI (bin/magento)

Installation

The module is published on Packagist as inpost-vonhalsky/module-magento, together with its InPost PHP SDK. Installation is a standard composer require — no repositories configuration is needed.

📚 Separate SDK repository. The InPost PHP SDK is maintained in its own repository — InPost-vonHalsky-api-sdk-php (Packagist: inpostapi/inpost-vonhalsky-api-sdk-php). Composer pulls it in automatically as a dependency of the module; you do not install it separately.

1. Require the module

From the Magento root:

composer require inpost-vonhalsky/module-magento

Composer resolves the module and its dependencies (the InPost PHP SDK inpostapi/inpost-vonhalsky-api-sdk-php and league/oauth2-client) automatically from Packagist.

2. Enable the module and run setup

bin/magento module:enable Inpost_VonHalsky
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

bin/magento module:status Inpost_VonHalsky should now list the module as enabled.

3. Upgrading to a new release

composer update inpost-vonhalsky/module-magento
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Documentation

The complete user guide — setup, configuration, daily operations, and troubleshooting — lives in doc/quick-start.md, with accompanying screenshots under doc/screenshots/. New merchants should start there and follow it in sequence.

Highlights

OAuth2 Integration – Secure token handling and automatic refresh via OAuth2Service.
Organization Management – Retrieve and cache available organizations, with manual refresh controls.
Admin Experience – Dedicated Magento menus for Offers, Category Mapping, and Orders; attribute mapping and event tracking are managed within those sections.
Category Search – Search box above the InPost category tree in Category Mapping; partial match, case-insensitive, with breadcrumb path and highlighted results. Backed by a shared cache — zero DB queries after first load.
Bulk Synchronisation – CLI commands for offers, categories, events, and orders, with filtering options (and dry-run where applicable).
Automation Ready – Cron jobs schedule critical synchronisations automatically (see table below).
Robust Architecture – Service-oriented code with comprehensive logging, validation, and error handling (ApiErrorHandler).

Shipping Automation (optional — Smartmage InPost)

VonHalsky integrates with the Smartmage_Inpost module (InPost Paczkomat / Courier shipping methods and ShipX parcel generation). This is a soft dependency — VonHalsky works fully on its own. When Smartmage_Inpost is installed, accepted marketplace orders can be mapped to InPost carriers and their ShipX shipments (waybills / shipping labels) generated automatically — so the entire order-to-shipment flow can run hands-free, with no manual label creation. Configure carrier mapping and automatic shipment creation under Stores → Configuration → VonHalsky → Delivery Method Mapping.

Scheduled Cron Jobs

Job	Default Schedule	Purpose
Categories	`0 2 * * *` (2 AM daily)	Sync InPost categories
Events	`/15 * * *` (every 15 min)	Sync offer/order events
Orders	`/10 * * *` (every 10 min)	Sync orders from InPost
Updated Offers	`/5 * * *` (every 5 min)	Re-send offers flagged for API sync
Pending Commands	`/3 * * *` (every 3 min)	Poll async create-offer commands; finalize/retry

All schedules are configurable in Stores → Configuration → VonHalsky → Cron Settings.

Admin & CLI Operations

Configure credentials under Stores → Configuration → VonHalsky → Configuration. Use the provided action buttons to connect, test, and refresh organizations.
Operate day-to-day workflows from the VonHalsky admin menu (Offers, Category Mapping, Orders).
Run console commands such as bin/magento inpost:categories:sync --clean or bin/magento inpost:offer:send --all for manual control.

See the User Guide for detailed instructions, options, and usage examples.

Support & Maintenance

Logs are stored under var/log, including inpost_debug.log for module-specific diagnostics.
Always clear Magento caches after configuration changes (bin/magento cache:flush).
Consult the User Guide for a troubleshooting checklist before escalating issues.

Need help? If you run into problems, contact InPost API support at apiportal@inpost.pl. Include the module version, your Magento version, and relevant excerpts from var/log/inpost_debug.log.

Module namespace: Inpost_VonHalsky

inpost-vonhalsky / module-magento

Maintainers

Package info

Statistics

Security