Transportial is built on the OTM5 (Open Trip Model 5) standard — an open data model for logistics. This page explains the key entities and how they relate.
The core transport flow is built around four entities:
Platform
└── Business (your company, customers, carriers)
└── TransportOrder (a request to move goods)
└── Consignment (a line-item grouping of goods)
└── Trip (the execution plan)
└── Action (atomic tasks: load, move, unload)A Platform is your workspace — the top-level container for all data. When you register, a platform is created for your organization. Platforms have configurable settings for UI, billing, pricing, translations, and alerts.
Every entity belongs to a platform. Users and businesses are scoped to their platform.
A Business represents a company or organization. You'll create businesses for:
- Your own company
- Your customers (shippers)
- Your carriers and subcontractors
- Receivers and other parties
Businesses have contact details, locations, tax identifiers (VAT, EORI, CoC), and can be organized hierarchically with partOf relationships.
A TransportOrder is the starting point of any transport operation — a request to move goods between locations. It tracks the full lifecycle from initial request through planning, execution, and invoicing.
| Status | Description |
|---|---|
concept | Draft, not yet submitted |
requested | Submitted, awaiting acceptance |
accepted | Confirmed by the carrier |
calculated_trip | Route has been calculated |
partially_planned | Some consignments are planned |
planned | All consignments have trips assigned |
actual | Currently in execution |
realized | Completed successfully |
cancelled | Cancelled before completion |
declined | Rejected by the carrier |
- name — Human-readable identifier
- customer — The business requesting the transport
- consignments — The line items (goods to be moved)
- expectedRevenue / expectedCost — Financial estimates
- administration — Linked invoicing and billing info
A Consignment is a logical grouping of goods within a transport order. A single transport order can have multiple consignments — for example, one pickup going to multiple destinations.
| Status | Description |
|---|---|
draft | Being composed |
requested | Submitted |
confirmed | Accepted and ready for planning |
planned | Trip assigned |
in_transit | Currently moving |
completed | Delivered |
cancelled | Cancelled |
Consignments also support partial statuses: partially_planned, partially_in_transit, partially_completed.
- goods — List of cargo items (pallets, packages, containers, etc.)
- trip — The execution plan assigned to this consignment
- actions — Events that have occurred (loading, unloading, etc.)
Goods represent the physical cargo. They use polymorphism — the two main types are:
- Items — General cargo with quantity, weight, dimensions
- TransportEquipment — Containers, trailers, and other transport equipment
A Trip is the execution plan for moving consignments. It defines the route, assigns a vehicle and chauffeur, and contains an ordered sequence of actions.
Trips support multi-modal transport:
- Road — Route calculation via GraphHopper
- Maritime — Route calculation via SeaRoute
- Rail and Air — Supported in the data model
- vehicle — The assigned vehicle
- chauffeur — The assigned driver(s)
- actions — Ordered list of tasks to execute
- route — Calculated route geometry
An Action is an atomic task within a trip. Actions are polymorphic — each type represents a different operation:
| Type | Description |
|---|---|
load | Load goods onto the vehicle |
unload | Unload goods at destination |
move | Drive between locations |
stop | Scheduled stop |
break | Driver rest break |
wait | Waiting time (at dock, border, etc.) |
handOver | Transfer goods to another party |
customs | Customs clearance |
attachChauffeur | Assign a driver mid-trip |
attachTransportEquipment | Attach trailer or container |
Actions have constraints (time windows, location requirements) and track their lifecycle through events.
Events record what happens during transport execution. They are also polymorphic:
- ArrivalEvent / DepartureEvent — Vehicle arrives or departs a location
- LocationUpdateEvent — GPS position update
- GateInEvent / GateOutEvent — Enters or exits a facility
- SensorUpdateEvent — Temperature, humidity, or other sensor data
- StartMovingEvent / StopMovingEvent — Motion detection
- CapacityChangeEvent — Loading/unloading changes cargo capacity
Geographic points or areas. Locations have addresses, coordinates, and can be linked to businesses (warehouses, offices, etc.).
Vehicles in your fleet. Tracked for planning, GPS monitoring, and compliance. Linked to chauffeurs through activity scheduling.
Drivers with schedules, activity tracking, and availability management. Chauffeurs are linked to users and can be assigned to trips.
Financial documents generated from transport orders. Invoices track charges per consignment line. Quotes provide pricing before acceptance.
The API uses JWT bearer tokens. Each user session carries a set of permissions that control access to specific operations. Common permissions include:
create:transportOrder,get:transportOrders— Transport order managementcreate:business,get:businesses— Business managementbrowse:app-store,install:app— App store accesscreate:chauffeur:activity— Driver scheduling
See the Quickstart for authentication details.