Posta (Slovenská pošta)

Posta connects yStore to Slovenská pošta (the Slovak national postal operator) through its ePodaj API. It registers Slovenská pošta as a shipping method in checkout, and on the admin side it creates shipments, generates shipping labels, and keeps tracking status in sync for orders fulfilled through the carrier.

What it does

• Adds Slovenská pošta as a selectable shipping method in checkout.
• Lets customers choose a Balík na poštu (post office pickup) location during checkout, when pickup points are enabled.
• Creates a shipment with Slovenská pošta for an order -- either manually from the order edit page, or automatically once the order reaches a configured status.
• Generates and stores the shipping label (PDF) for each shipment, downloadable or printable from the admin.
• Polls Slovenská pošta for tracking updates and shows a tracking timeline per shipment.
• Supports the carrier's core service types: home delivery (Balík na adresu), post office pickup (Balík na poštu), EMS international express, express courier, and registered letter.

How it works

1. Checkout. If Slovenská pošta is enabled as a shipping method, it appears alongside the store's other shipping options. If pickup points are turned on in the plugin settings, the customer additionally picks a nearby post office from an in-checkout selector before placing the order.
2. Order fulfilment. Once an order is ready to ship, a shipment can be created for it. This can happen:
   • manually, from the order edit page (a "manage shipment" panel appears for orders that have a shipping weight and haven't hit the label limit), or
   • automatically, when the order transitions into a specific order status you choose in the plugin settings (see Settings).
3. Label and tracking. After a shipment is created, Posta requests a shipping label from Slovenská pošta and stores it. The Shipments admin page shows every shipment with its parcel number, service, linked order, current status, and a tracking timeline built from the carrier's status updates. Tracking can be refreshed on demand, and a shipment can be re-synchronised (which issues a new parcel number) if something needs to be redone.

Example 1: home delivery with automatic label creation

A store ships most orders as a standard Balík na adresu (home delivery) parcel and wants labels created without manual admin work:

1. In the plugin settings, set Default service to BA (Balík na adresu) and configure the sender/pickup address (this is sent as the shipment sender on every label).
2. Set Auto-create shipment on status to the order status used once an order is packed and ready to ship (for example "Ready to ship").
3. When an order reaches that status, Posta automatically creates the shipment and requests the label -- no manual step needed. The label can be opened or printed straight from Posta → Shipments.

Example 2: post office pickup at checkout

A store wants to let customers pick up their parcel at a post office instead of paying for home delivery:

1. Enable Enable Balík na poštu pickup points in the plugin settings.
2. Set Default country for pickup points (e.g. SK).
3. At checkout, once the customer selects the Slovenská pošta shipping method, a "Choose pickup point" selector appears; pickup points are looked up live from Slovenská pošta and cached for an hour per country/ZIP combination.
4. The order is created with the confirmed pickup point; the admin then creates the shipment as usual (manually or automatically), using BP (Balík na poštu) as the service.

Frequently asked questions

Does this replace Slovenská pošta's own shipping portal? No. Posta talks to the same ePodaj API that the carrier's own tools use, so shipments created here appear the same way they would if submitted through Slovenská pošta directly. You don't need to re-enter shipment data anywhere else.

What happens if a label fails to generate? The order edit page and the Shipments list will show the shipment without a stored label. A notification (Label generation failed) is raised so an operator can investigate, and the shipment can be retried/re-synchronised from the Shipments admin.

Can more than one shipment be created for the same order? Only up to the number configured in Max labels per order. Once that limit is reached, both the automatic and the manual "create shipment" action are blocked for that order until an existing shipment is removed or the limit is raised.

Does the pickup point selector work outside Slovakia? The default country is Slovakia (SK), but the pickup point country is configurable. Availability of pickup points for other countries depends on what Slovenská pošta's API returns for that country.

Is there a sandbox/test mode? Yes -- enable Sandbox mode to send all API traffic to Slovenská pošta's test endpoint with separate sandbox credentials, so shipments and labels can be verified before going live.

Admin / Craft CP

See Settings for the full configuration reference. Once configured, the plugin adds three navigation items under Posta in the Craft control panel:

Page	Purpose
Dashboard	Total shipment count, last synchronisation time, and a status breakdown at a glance.
Shipments	Every shipment created with Slovenská pošta: parcel number, service, linked order, status, tracking timeline, label download, CSV export, and per-shipment refresh/re-sync/delete-label actions.
Settings	API credentials (production and sandbox), sender/pickup address, pickup point behaviour, default service, label limits, and the auto-create order status.

An order edit page shows a manage shipment panel for orders with a shipping weight, allowing a shipment to be created for that order directly without visiting the Shipments list.

Developer notes

• Services (available on the plugin instance as Posta::getInstance()->...): shipments, labels, tracking, pickupPoints, client (raw API client), license, dashboard, api.
• Order automation. Posta listens for yStore's order status change event and, when the target status matches the configured syncOrderStatusUid, calls the shipment service to sync the order (respecting the label limit and the plugin's own eligibility check).
• Notification types. Posta registers three notification types with yStore's notification system: shipment.created, shipment.failed, and shipment.status, so shipment events can be routed to admin notification channels like any other store event.
• Site-facing endpoint. posta/api/pickup-points (anonymous, GET) returns a JSON list of pickup points for a given country/ZIP code, used by the checkout pickup point widget. It can also be called directly for a custom storefront integration.
• Data model. Shipments are stored as ShipmentRecord rows (parcel number, parcel ID, service code, linked order ID, status, label type, raw request/response payloads). The raw Slovenská pošta API payload and response are available on the shipment detail page for troubleshooting.

Requirements

• Craft CMS 4 or 5.
• yui/craft-core ^1.
• A Slovenská pošta ePodaj account with API credentials (production and/or sandbox).