Shipment Generation

What It Does

This workflow generates shipping labels through carrier APIs, stores the resulting PDFs, and synchronizes tracking numbers back to Magento and connected marketplaces. It covers the full lifecycle from an order being ready to ship through to the delivery confirmation.

How It Connects

Trigger

Source	Schedule	Purpose
sale:expedition:import	Cron-scheduled	Import expedition data and generate labels
Order status change	Event-driven	Automatic label generation when order reaches shipping-ready state

Components

Component	File Path	Role
sale:expedition:import	src/AppBundle/Command/	Imports expedition data from external sources
DpdService	src/CoreBundle/Services/DpdService.php	DPD label generation via REST API
BrtService	src/CoreBundle/Services/BrtService.php	BRT label generation via SOAP API
ChronopostService	src/CoreBundle/Services/ChronopostService.php	ChronoPost label generation via SOAP API
GlsService	src/CoreBundle/Services/GlsService.php	GLS label generation via REST API
GeodisService	src/CoreBundle/Services/GeodisService.php	Geodis label generation via REST API
ShipmentService	src/CoreBundle/Services/ShipmentService.php	Core shipping logic and orchestration
ShippingService	src/CoreBundle/Services/ShippingService.php	Shipping rate calculations

Shipment Lifecycle

Step-by-Step Flow

Carrier-Specific Details

Carrier	API Type	Label Format	Storage Path
DPD	REST	PDF	/web/pdf_dpd/
BRT	SOAP	PDF	/web/pdf_brt/
ChronoPost	SOAP	PDF	/web/pdf_chronopost/
GLS	REST	PDF	/web/pdf_gls/
Geodis	REST	PDF	/web/pdf_geodis/

:::info Carrier selection The carrier for each shipment is determined by business rules that consider the destination country, package weight/dimensions, and shipping method selected by the customer. ShippingService handles rate calculations when multiple carriers are eligible. :::

Side Effects

Database

• Updates SaleProduct with carrier name, tracking number, and label file path
• Writes shipment status transitions

File System

• Generates PDF label files in the carrier-specific directory under /web/pdf_*/
• Labels are stored permanently for reprinting and audit

External Systems

• Tracking numbers are synchronized to Magento via ShipmentTrackingSynchronizer
• Tracking numbers are propagated to marketplaces on the next sync cycle

Failure Modes

:::warning Carrier API timeout If the carrier API times out during label generation, the order remains in ProcessingNotPrinted state. The next cron cycle will retry. Persistent timeouts may indicate a carrier-side outage. :::

:::warning Invalid address Carriers reject labels for addresses they cannot validate (missing postal code, invalid country code, etc.). These orders are skipped with an alert. The address must be corrected manually in Logidav before the label can be generated. :::

:::danger Duplicate label generation If the expedition import command runs while a previous execution is still in progress (no lock or lock timeout), the same order may receive two labels. This wastes carrier credits and creates confusion with duplicate tracking numbers. LockableTrait should prevent this, but check for lock timeout issues. :::

:::warning Tracking sync delay Tracking numbers are pushed to Magento and marketplaces asynchronously. There is a delay between label generation and the tracking number appearing on the customer-facing order. During this window, customer service may not see the tracking number. :::

Debugging Path

1. Check carrier API response -- inspect logs for the carrier service that was called. Look for HTTP status codes, error messages, and timeout indicators.
2. Verify SaleProduct shipping fields -- query the SaleProduct entity to confirm that carrier, tracking number, and label path are populated.
3. Check PDF storage -- verify that the label PDF exists at the expected path in /web/pdf_{carrier}/. Missing files indicate a storage write failure.
4. Verify tracking sync queue -- check that ShipmentTrackingSynchronizer has processed the tracking number. Look for queued but unprocessed entries.
5. Validate address data -- if the carrier rejected the label, check the order's shipping address fields for completeness and validity.
6. Check for duplicate labels -- search for multiple tracking numbers on the same SaleProduct to identify duplicate generation issues.

Related Commands

Command	Purpose
sale:expedition:import	Primary expedition import and label generation
Carrier-specific commands	Per-carrier label generation (if applicable)
Tracking sync commands	Push tracking numbers to Magento and marketplaces