Shipments

What is this document for?

This document explains how the Operations module in MIDLA Platform supports the daily work of logistics companies, including freight forwarders, cargo agents, courier operators, and transportation companies.

The objective is to understand what the system can do, how information is organized, and how each concept translates into real-world operations.

---

1. The Central Concept: the Shipment

Everything in the Operations module revolves around a central object: the Shipment.

A Shipment represents the complete process of moving goods from a point of origin to a destination. It can be something as simple as an urgent package between two cities or as complex as a 40-foot container crossing three countries with a transshipment at an intermediate port.

Each Shipment has a unique reference number automatically generated by the system. The format includes codes that identify the logistics model, transport mode, and trade direction. For example, FF-O-I-00123 identifies an import ocean freight forwarding operation.

Shipment Statuses

A Shipment moves through the following statuses during its lifecycle:

Draft → Confirmed → Operationally Closed → Accounting Closed

                    ↓

                 Canceled

• Draft: the operation is being entered and has not yet been confirmed.
• Confirmed: the operation is active and can be processed.
• Operationally Closed: the logistics operation has been completed.
• Accounting Closed: all charges have been invoiced or settled.
• Canceled: the operation was not carried out.

---

2. The Four Dimensions of an Operation

To correctly classify an operation, the system uses four dimensions. The combination of these four dimensions fully defines the type of operation and enables the corresponding fields, validations, and behaviors.

2.1 Trade Direction

Indicates the direction of the cargo flow in relation to the country of operation.

Value	Description
Import	The goods enter the country where the customer or logistics operator operates.
Export	The goods leave the country for an international destination.
Domestic	Transportation takes place within the same country without crossing borders.
Drop	An operation between two different countries where the logistics operator coordinates the shipment without being physically located in either country. Also known as Cross Trade.

2.2 Transport Mode

Indicates the main physical means used to move the cargo.

Value	When it is used
Ocean	High-volume international shipments, containers, and bulk cargo.
Air	Urgent shipments, high-value goods, and perishables.
Inland	Transportation within a country or between neighboring countries by road.

What about multimodal transportation?

An operation that combines several transport modes, for example, a truck carrying cargo to the port followed by ocean transportation, is managed through Routing Legs. Each leg has its own transport mode. The system does not require a special "multimodal" type because the combination is naturally built through the route.

2.3 Logistics Model

Describes how the operation is organized and managed from the perspective of the service being offered.

Value	Description
Freight Forwarding	Traditional international transportation model. The operator coordinates the complete chain, including documentation, carriers, agents at origin and destination, and customs.
Courier	Small or urgent shipments managed by specialized operators. The workflow is simpler and more standardized.

2.4 Cargo Model

Indicates how transportation capacity is contracted and how cargo is grouped. This dimension is especially relevant for ocean and inland transportation.

Value	Applies to	Description
FCL (Full Container Load)	Ocean	The customer occupies the entire container.
LCL (Less than Container Load)	Ocean	The customer's cargo is grouped with cargo from other customers in the same container.
FTL (Full Truck Load)	Inland	The customer occupies the entire truck.
LTL (Less than Truck Load)	Inland	The customer's cargo is grouped with cargo from other customers in the same truck.
Parcel	Air / Courier	Individual packages.

---

3. Shipment Structure: Direct, House, and Master

This is one of the system's most powerful features and is essential for understanding the work of a freight forwarder.

Direct Shipment

This is the simplest case: one customer's shipment from an origin to a destination. There is no consolidation.

[Customer A] ──→ [Direct Shipment] ──→ [Destination]

House Shipment

A House is an individual customer shipment that travels as part of a larger consolidation.

The customer sees their cargo as an individual shipment with its own reference number and tracking information, but physically it travels together with cargo from other customers.

Master Shipment

A Master is the parent operation. It groups multiple Houses into a single physical shipment, such as an LCL container, consolidated flight, or consolidated truck.

The Master is the shipment negotiated with the carrier.

[Customer A] ──→ [House A] ──┐
[Customer B] ──→ [House B] ──┼──→ [Master] ──→ [Carrier (vessel/aircraft/truck)]
[Customer C] ──→ [House C] ──┘

Why is this structure important?

• It allows individual documents to be issued for each customer, such as House BL or HAWB, and a consolidated document for the carrier, such as Master BL or MAWB.
• It allows each customer to be invoiced individually for their portion of the cargo.
• It allows separate tracking for each customer even when the cargo travels together.
• Master charges, such as the main freight charge, can be distributed among the Houses automatically.

---

4. Actors in an Operation

A logistics operation may involve multiple companies and people. The system allows all relevant parties to be registered for each shipment.

Actor	Role in the operation
Customer	Company that hires the logistics service from the operator. This is the party that pays.
Shipper	Company or person dispatching the goods, such as the seller or supplier.
Consignee	Company or person receiving the goods, such as the buyer or final recipient.
Agent	Logistics representative in the origin or destination country who collaborates in the operation.
Carrier	Transportation company physically moving the cargo, such as a shipping line, airline, or trucking company. It is registered per Routing Leg.
Broker	Customs specialist responsible for import or export procedures.
Warehouse	Company or facility where the goods are stored before or after transportation.
Operator	Internal team member responsible for managing the operation.
Salesperson	Internal sales representative responsible for the customer.
Account Manager	Internal person responsible for the customer account.

---

5. Route: Routing Legs

A logistics operation is rarely a simple movement from point A to point B. In practice, cargo passes through several locations and may be transported by different carriers.

The system manages this through Routing Legs.

Types of Legs

Type	Description
Pre-Carriage	Transportation from the origin to the departure point, for example, factory → origin port.
Main Carriage	Main transportation between the origin and destination port or airport.
On-Carriage	Transportation from the arrival point to the final destination, for example, destination port → customer warehouse.

Information per Leg

Each Routing Leg records:

• Origin and destination of the leg.
• Transport Mode for that specific leg.
• Responsible Carrier.
• Carrier reference number, such as booking number, AWB, BL, or tracking reference.
• Vessel or flight for ocean or air legs.
• ETD / ETA dates for estimated departure and arrival.
• ATD / ATA dates for actual departure and arrival.
• Cut-off date for cargo delivery to the carrier.
• Pickup and delivery addresses associated with the leg.

This provides a complete view of the route and its dates at each point, making it possible to identify delays leg by leg.

---

6. Cargo: Packages and Items

The goods within each operation can be recorded with the level of detail required by the business.

Information per Package / Cargo Unit

Field	Description
Package Type	Box, pallet, container, drum, coil, etc.
Commodity	Classification of the type of cargo, such as electronics, textiles, food, etc.
Number of Pieces	Number of packages or units.
Description	Description of the contents.
Dimensions	Length × Width × Height with a unit of measure.
Gross Weight	With a unit of measure such as kg or lb.
HS Code	Harmonized System tariff code.
Declared Value	Used for insurance and customs documents.
Insured Value	Used when arranging cargo insurance.
Custom References	Customer or system reference numbers.
Dangerous Goods	Indicator and description for hazardous materials or DG cargo.
SSCC / LPN	Logistics barcode identifiers used for WMS integration.

Automatic Calculations

The system automatically calculates:

• Volume in CBM based on the package dimensions.
• Volumetric Weight for air and ocean transportation using standard industry conversion factors.
• Number of TEUs for ocean operations involving containers.

These calculations form the basis for freight settlement because many charges are calculated using whichever is greater between actual weight and volumetric weight.

---

7. Charges: Operation Revenue and Costs

One of the most important functionalities of the module is managing the charges associated with each operation.

Charge Types

Each charge has a direction:

• Receivable: what the operator charges the customer.
• Payable: what the operator pays to a supplier, such as a carrier, agent, broker, or other provider.

Charge Measurement

Charges can be calculated using different measurement bases:

Basis	Description
Per Container	Fixed amount for each container in the operation.
Per TEU	Based on twenty-foot equivalent units. A 40-foot container equals 2 TEUs.
By Weight	Price × chargeable weight, using the greater of actual and volumetric weight.
Per CBM	Price × volume in cubic meters.
By Gross Weight	Price × actual gross weight.
By Quantity	Price × number of pieces or packages.
Fixed	Fixed amount regardless of quantity.
Per Product	Unit price per item.

Configurable Charge Types

The system includes a catalog of charge types such as Freight, Surcharge, Local Charges, and Customs, which operators can configure according to their needs.

Each charge type has:

• Associated accounting product for integration with the Accounting module.
• Charge group.
• Default measurement basis.
• Applicability to specific logistics models, transport modes, and trade directions.
• Display order.

From Charge to Invoice

Once all charges for an operation have been completed, the system can automatically generate invoices by grouping charges by customer or supplier and currency.

This integrates directly with the Accounting module and eliminates the need to enter the same information again.

---

8. Tariffs and Quotations

The module includes a tariff engine for managing the operator's pricing structure.

What is a Tariff?

A Tariff is a set of prices for a specific service that is valid for a defined period.

It may include:

• A freight tariff, representing what the carrier charges.
• Surcharges, such as BAF, CAF, or THC.
• Local charges, such as origin or destination handling.
• Customs charges.

Tariff Versioning

Tariffs have versions.

This allows the system to preserve pricing history and manage tariff changes without losing historical information. Only one version is active at a time.

Tariff Lines

Within each version, lines define prices according to combinations of:

• Origin and destination, with the option to apply to all origins or all destinations.
• Route via, used to specify transshipment ports.
• Shipment type, such as FCL 20', FCL 40', LCL, etc.
• Specific Carrier, when applicable.
• Validity period for each line.
• Price, minimum charge, and transit time.

Break Pricing

Tariff lines support tiered pricing, where the unit price changes according to quantity.

For example, an air freight tariff may define one price per kg for the first 45 kg and another price for excess weight.

This is particularly important for air freight tariffs.

---

9. Warehouse Operations: Receipts

The module also manages merchandise movements within warehouses associated with the operation.

What is a Receipt?

A Receipt is a record of merchandise movement within a warehouse.

It can be:

• Incoming: the goods enter the warehouse.
• Outgoing: the goods leave the warehouse.
• Internal: transfer within the same warehouse.
• Dropship: goods that do not physically pass through the warehouse.

Receipt Statuses

Draft → Confirmed → Goods Arrived → Allocated → Completed

                                              ↓

                                           Canceled

Linking a Receipt to a Shipment

Receipts can be linked to a Shipment, connecting the logistics operation with the physical movement of goods in the warehouse.

Movement History

Every Receipt status change is recorded as a Movement, including the exact date and the user who performed the action.

This provides complete traceability throughout the merchandise lifecycle inside the warehouse.

---

10. System Configuration

The module includes a set of configurable catalogs that allow the system to be adapted to each company's operations.

Catalog	Description
Package Types	Box, pallet, container, drum, etc., including indicators for whether they apply to air, ocean, or inland transportation.
Container Types	20', 40', 40' HC, Reefer, Open Top, etc.
Commodities	Classification of cargo types.
Vessels	Vessel registry including IMO code.
Customs Offices	Authorized customs offices by country.
Charge Types	Configuration of available charges such as freight, surcharges, local charges, etc.
Movement Types	Move Types used to classify services such as Port-to-Port or Door-to-Door.
Service Modes	Service Modes according to the scope of the service offered.
Warehouse Operation Groups and Types	Configuration of WMS operation types and their capabilities.

---

11. Integration with Other Modules

The Operations module does not work in isolation. It is integrated with the rest of the platform.

Module	Integration
Accounting	Shipment charges automatically generate accounting entries and invoices.
Partners	All actors, including customers, carriers, agents, brokers, and warehouses, are managed in the Partners module and reused across operations.
Products	Charge types are associated with accounting products for proper allocation.
Places	Origins, destinations, and routes use the system's Places catalog, including ports, airports, cities, and warehouses.
Projects	An operation can be linked to a Project to group related operations.
PDF / Documents	The system can generate PDF documents for the different parties involved in the operation.

---

12. How Does the System Support Operations?

For the Operations Team

• Each operation centralizes all relevant information, including route, cargo, parties, documents, and dates.
• ETD, ETA, ATD, and ATA dates per leg make it possible to track delays in real time.
• Automatic reference generation helps prevent numbering errors.
• The priority system from 1 to 3 stars allows critical operations to be quickly identified.
• Internal notes and customer notes keep internal and external communication separate.

For the Sales Team

• Versioned tariffs make it possible to quote using current prices while maintaining a history of previously offered rates.
• Linking operations to customers makes commercial tracking by account easier.

For the Finance Team

• Managing Receivable and Payable charges within the operation provides visibility into the operating margin before invoicing.
• Automatic invoice generation from charges eliminates duplicate data entry.
• Accounting closure allows teams to identify operations that still have outstanding charges to settle.

For the Warehouse

• Receipts linked to operations make it possible to track the physical status of the goods.
• Movement history provides complete traceability of every step inside the warehouse.
• Weight, dimensions, and contents management supports physical warehouse operations and inventory control.

For Audit and Control

• All operations include creation and modification records with user and date information.
• Status changes are audited.
• Linking charges to invoices makes it possible to trace the origin of each accounting movement.
• Reports and exports allow operations to be analyzed using external tools.

---

Summary: The Complete Lifecycle of an Operation

1. QUOTATION
   └─ Current tariffs are consulted according to the route and cargo type.

2. SHIPMENT CREATION
   └─ The Shipment is created as Direct, House, or Master with all required information.
   └─ Trade Direction, Transport Mode, Logistics Model, and Cargo Model are defined.
   └─ All parties involved in the operation are registered.

3. ROUTE AND LEGS
   └─ Routing Legs are defined with carrier, ETD/ETA dates, and references.

4. CARGO
   └─ Packages are registered with weight, dimensions, commodity, and references.

5. CHARGES
   └─ Customer charges are entered as Receivables and supplier costs as Payables.
   └─ The system automatically calculates amounts according to the measurement basis.

6. WAREHOUSE, IF APPLICABLE
   └─ Receipts linked to the Shipment are created to manage physical movements.

7. OPERATIONAL TRACKING
   └─ Actual dates, ATD and ATA, are updated for each leg.
   └─ The Shipment status is updated as the operation progresses.

8. OPERATIONAL CLOSURE
   └─ The operation is marked as operationally closed.

9. INVOICING
   └─ Customer invoices and supplier settlements are generated from the charges.

10. ACCOUNTING CLOSURE
    └─ The operation is marked as accounting closed.