TMS Development for Trips: Statuses, Plan‑Fact, Documents

What a trip TMS should solve

If trips are managed in spreadsheets, chats and email, each participant ends up with their own version of the truth. The dispatcher marks a trip "in transit", the carrier says "loading", the warehouse — "not arrived yet", and accounting only sees the invoice without a clear set of confirmations. A TMS for trips is needed so everyone shares the same view of statuses, times and documents.

The first basic task is a unified trip status system. Without it you cannot quickly answer simple questions: where is the cargo, who’s responsible for the delay, when to expect arrival. Statuses should not be "for show" but tied to events and responsibility: who moves a status, under what conditions, and which fields are mandatory.

The second task is plan‑fact and transparent deviations. The plan often lives in the order, while the fact is in calls and paper. Then disputes arise: "we arrived on time" vs "we were waiting 3 hours at the gate." TMS should store both planned and actual times for key points (vehicle assignment, load start/end, departure, arrival, unloading) and compute deviations by clear rules.

The third task is working with multiple carriers without chaos. When every carrier uses different formats, drivers, phones and names, reference data and reports break. You need unified cards for counterparties, vehicles and drivers, access rules and change history so it’s clear who changed what and why.

The fourth task is control of supporting documents. Unverified documents are risky: payment can be made prematurely, claims cannot be proven, and reconciliations drag on for weeks.

In a minimal TMS for trips you should provide:

• a single trip log with status, responsible person and last event;
• plan‑fact for control points and reasons for deviations;
• assignment of a trip to carriers (primary, subcontractor) and user roles;
• a document registry (TTN/CMR, act, invoice) with verification statuses;
• blockings: you cannot "close a trip" or send it for payment without required confirmations.

Example: a trip is marked "arrived" but in reality the driver is still waiting at the checkpoint. If the fact is taken only from a phone call, the report will show "on time" and the warehouse and client will get a wrong ETA. If TMS requires the event "passed checkpoint" with time and confirmation, the discrepancy appears immediately and the dispute becomes data, not a chain of messages.

When developing a TMS for trips, it's useful to decide in advance which statuses are final and which documents are required for payment and trip closure. This usually saves the most time during launch and initial checks.

Minimal data model: what to store from day one

When you start building a trip TMS, the goal of the data model is simple: at any moment answer three questions — where is the trip now, what exactly is being transported, and which documents confirm the fact.

Core entities

In an MVP don’t try to describe the whole logistics world. A set of objects that don’t conflict and are easy to extend is enough:

• Trip: number, dates, current status, responsible person.
• Order: client, terms, link to trip (one trip — many orders).
• Stop: address, time window, type (load/unload), sequence.
• Cargo: packages/weight/volume, hazards, temperature, linked to an order.
• Vehicle, driver, carrier: identifiers, contacts, access documents.

This framework already allows building routes with multiple points, assigning orders to trips and involving different carriers without chaos in the directories.

Events and documents as separate objects

Facts almost always arrive in pieces: a driver call, GPS, checkpoint stamp, integration from a contractor. So store trip events separately from status. An event is a record with time, location and source (dispatcher, mobile app, telematics). Then status can be recalculated or confirmed without losing history.

Store documents as objects too, not just as "a file attached to the trip." At minimum: type (TTN/CMR/act), number, dates, linked trip/order/stop, files (original/scan) and verification status (pending, accepted, rejected) with reason.

To make work convenient, build roles and permissions at the data level. For example, a dispatcher creates trips, edits stops and records events. Accounting checks documents and closes trips for payment. Security sees driver/vehicle and permits and blocks mismatches. The client views statuses and supporting documents without edit rights.

Example: the driver loaded at 10:05, the dispatcher recorded the event "loading completed," and later accounting accepts the TTN scan. The trip does not go to payment until the document status is "accepted."

Trip statuses: how to design a simple, reliable scheme

Statuses in TMS fail not because of rare cases but because of mixing levels. First rule: trip status and order (or shipment) status are different entities. Trip describes vehicle movement and route execution. Order describes client obligations: what, where and how much should arrive.

If you mix levels, chaos follows: one order can be partially delivered while the trip is still in transit, or the trip is completed while part of the order is recorded as undelivered. Keep only trip‑related fields in the trip card and treat order state separately (based on point facts, scanned documents and exceptions).

A good status scheme must be unambiguous: one action — one status. Don’t create statuses like "In transit/waiting" or "Almost delivered." A user must understand which event has happened and which has not.

Usually a short sequence reflecting real trip stages is enough:

• Planned
• Carrier assigned
• Departed
• Arrived at point
• Completed

More important than adding words is locking transition rules. For example, you cannot move "Departed" back to "Carrier assigned" without a dedicated "Rollback with reason" operation. You shouldn’t be able to set "Completed" while required route points are still open, if that is the company rule. Also provide a clear path for exceptions: cancel trip, change vehicle, postpone time.

To avoid status disputes, implement a strict change history. Each transition must record:

• who changed the status (user or integration);
• when it was changed (exact time);
• where the fact came from (manual, GPS, EDI, document scan);
• reason if it’s not a standard transition (e.g., "rescheduled due to weather").

Example: a two‑point trip (warehouse and store). Dispatcher created the trip and assigned the carrier — status "Carrier assigned." The driver marked start in the mobile app — "Departed" with source "mobile app." At the store, the receiver scanned the TTN — the trip becomes "Completed," while the order inside the trip may become "Delivered" or "Partially delivered" depending on item fulfillment. This way you don't argue about words: you see the action, source and time.

If you develop TMS as an internal product or order it from an integrator, align the status scheme with logistics, accounting and security. It's cheaper than later explaining why "Completed" doesn't match what’s needed for closing documents.

Plan‑fact: how to calculate deviations and avoid fights over numbers

Plan‑fact in TMS often causes disputes not because of bad drivers but because of different calculation rules. So fix in advance what counts as plan, what is fact and which events affect KPIs.

Store the plan not as a single date but as parameters for each route point: time window (from/to), estimated travel time to the point, estimated mileage, and expected durations at the point (load/unload norms). Then deviations are computed the same for everyone: compare the fact against a specific norm rather than a dispatcher’s expectation.

Facts are built from events. It’s important to separate "arrived" from "started work" and "departed," otherwise you’ll mix lateness and idle time. A short set of facts that can be obtained from GPS, mobile app or manually helps in practice: arrival at point, start work, end work, departure from point and reason for waiting (if any).

A separate issue is repeat visits. Allow multiple sets of facts for one route point (e.g., "visit 1", "visit 2") but define a rule to pick the "primary" set for KPI. A common approach: the primary is the one that led to closing the point, while others are marked as additional and do not affect penalties if a justified reason is provided.

To avoid disputes, calculate KPIs by clear formulas and show the breakdown. For example: "lateness" = max(0, arrival_time - window_end), "idle" = max(0, (start_work - arrival) - allowed_wait), "on‑time" = yes if arrival is inside the window.

Example: planned acceptance is 10:00–12:00, allowed waiting 20 minutes. The vehicle arrived at 11:50, work started at 12:40. The report should show: lateness 0 minutes (inside window), idle 30 minutes (50 minutes wait minus 20 allowed). When users see event breakdown, disputes decrease.

And: facts must have a source and change history (who and when edited), otherwise any KPI will be seen as "made up."

Multiple carriers: rules, rights and unified directories

When different carriers participate in trips, disputes usually start with data, not price: one has "tent 13.6", another "euro truck", regions are named inconsistently, a driver is recorded as "Sergey" without documents. So when building a TMS for trips, agree on a common language and rules for who can change what.

Unified carrier card

Create one clear carrier card and store everything that affects assignment and payment there. Don’t split this across modules from day one. Dispatcher should quickly see whether a carrier can be assigned to a specific trip.

Typically the card needs: contract and status (active, paused, blocked), rates and conditions (by route, vehicle type, extra services), restrictions (regions, cargo types, temperature regimes, permits), contacts and roles (dispatcher, accounting, manager), document requirements and delivery deadlines.

Plan scenarios for own fleet, permanent 3PL and one‑off contractors. For own fleet rates can be internal, for 3PL — tariff grids, and for one‑offs fast onboarding and strict blockings when documents are missing.

Unified reference data and mapping

If carriers get access to the system, don’t force them to translate their data into your names each time. Maintain internal reference lists (body types, regions, units, vehicle and driver statuses) and a mapping table: "our term" ↔ "carrier term." Then reports and plan‑fact calculations remain consistent even if partners send their own codes.

Access rights are critical: a carrier may add vehicles and drivers but should not change reference data, rates or acceptance rules. A practical approach: new vehicles, drivers and details go into "under review" status and become assignable only after confirmation.

Quality control without manual chasing

Track carrier quality with system‑calculated metrics rather than notes. A basic set is enough: punctuality (lateness at load/unload), incidents (damage, shortages, fines), timeliness of returning documents, cancellations and failures, and share of trips without remarks.

If rating drops or documents are chronically late, TMS should suggest clear actions: restrict access to new trips, tighten conditions or send the carrier for additional checks — according to company rules.

Supporting documents: collection, verification, blockings

In trips documents often matter more than words. If TMS can’t collect and verify confirmations on time, disputes about delivery occur, invoices are delayed and trips "hang." So define rules from the start: which documents are needed, when, who uploads them and what happens if a document is not accepted.

Which documents and when

The set depends on transport type, but the logic by stages is almost always the same. Before departure you usually need contractual and permissive items (request, route, power of attorney, vehicle and driver details). During transit you need event confirmations (loading stamps, idle time acts, photos of seals). After delivery you need closing documents: proof of receipt, act of completed works, transport documents with stamps.

To avoid manual control, TMS should store a mandatory matrix: whether a document is required or optional, for which trip type, at which stage and what it confirms (loading, delivery, extra service).

Statuses and verification

Every file must have a status understood by all participants. Practical minimum:

• Requested: the system expects the document by a certain date.
• Received: file uploaded but not verified.
• Under review: document is being checked by the responsible person.
• Accepted: passed checks and can be used in calculations.
• Rejected: mismatch found, new file or correction required.

Checks are easier in two layers. First — automatic: required fields filled, file readable (not blank or a black scan), dates consistent with the trip (no delivery act dated before departure), amounts and currency match agreed rates and extras. Second — selective manual: a person reviews disputed cases and confirms exceptions with a comment.

Example: a carrier uploaded a photo of the consignment note after delivery but the trip number in the stamp didn't match. TMS sets "Rejected," requests reupload, and the trip cannot be closed until the document is "Accepted."

Blockings: link to payment and trip closure

Main rule: money and trip closure depend on document statuses. Define in advance what blocks:

• invoicing (no accepted proof of delivery);
• extra service charges (no accepted idle time act);
• trip closure (key document set not accepted).

This removes "handshake agreements." Even if documents are uploaded from different places — office, warehouse terminal or a touchscreen kiosk — everyone follows one logic: until the document is accepted the process is not complete.

Integrations and events: where facts come from and who needs them

A trip fact rarely appears in a single system. Agree early which sources are trusted, how they are normalized and who resolves disputes. Without this, plan‑fact will constantly drift and investigations will take more time than the transport itself.

Sources of facts

Typically support several event capture methods because carriers vary in digital maturity:

• GPS/telematics: coordinates, speed, geofences (arrival/departure when crossing a zone).
• Manual events: dispatcher or driver marks "arrived", "loading completed" with comment.
• Carrier confirmation: status and time from partner via portal or file/message.
• Warehouse/production events: "ready for shipment", "accepted on ramp", if those systems exist.
• Document scans: creation/upload time of a confirmation as an indirect fact.

For each event record: source, exact timestamp (with timezone), user/system and a trust level (e.g., telematics > manual). When values conflict, keep both but choose one as the calculated value according to predefined rules.

Documents, notifications and audit

Document exchange should be convenient for carriers: file upload in trip card, accept attachments via e‑mail gateway, and EDI only if volume and requirements justify complexity. Channel is less important than control: required document types, readability, matching dates and numbers, and clear blockings (e.g., cannot close trip without proof of delivery).

Notifications should go to specific roles, not "everyone." Typically notify only on exceptions: missed loading/delivery window, route deviation or excess idle time, missing mandatory document by deadline, mismatch in weight/places or address in a document, attempt to close the trip with empty required fields.

A full action log is essential: who changed status, who edited time, who replaced a file and what was before. Field and document versioning saves disputes and audits. For example, if a carrier uploaded POD then replaced the file, you must see both versions, replacement time and reason. Otherwise the "fact" is hard to defend internally and with a counterparty.

Step‑by‑step development plan: from MVP to rollout

TMS projects often fail not because of code but because of trying to solve everything at once. A better approach is short iterations and verifying that users actually live in the system instead of continuing in spreadsheets and messengers.

How not to scatter requirements

Start with real cases. Take 10–15 typical trips and the same number of "awkward" situations: rescheduled loading, partial delivery, vehicle replacement, lateness, recipient refusal, extra point. These stories become tests for the status model, plan‑fact and document handling.

Then move in steps with clear readiness criteria:

• Fix scenarios and exceptions so they can be played step by step (who, when, which fact appears and where it’s confirmed).
• Approve the trip status model and transition rules, including who has the right and how to handle rollbacks and corrections.
• Describe plan‑fact: which times and distances are planned, what counts as fact, and which 3–5 reports logistics and accounting actually use.
• Launch MVP on one route and one carrier with clear rules and motivation to use the system.
• Connect supporting documents: what is mandatory, what is optional, how we verify (visually or by data) and when payment is blocked.

A simple MVP example: route Almaty — Astana and one carrier. Enough statuses: "planned", "assigned", "in transit", "delivered", "closed", plus one "issue." Calculate plan‑fact for two points (load and delivery) and close trips only with a basic document set: consignment note and act.

When to scale

Start scaling when the MVP has no manual workarounds: statuses change by rules, plan‑fact converges in reports, documents are actually uploaded, and payment blockings work without "we agreed in chat." Then add other carriers and branches: introduce unified directories (vehicle types, documents, deviation reasons), roles and minimal SLAs for confirmations so different teams don't treat "fact" differently.

Common mistakes in TMS development and how to avoid them

The most costly mistakes are not UI or speed but where people must agree on the meaning of data: what is a fact, who and when can change information, and how a trip is closed.

1) Too many statuses and manual options

When statuses number in dozens and transitions are unrestricted, users choose what "looks right." The same trip lives in different scenarios for different dispatchers and reports stop matching reality.

Keep the scheme short and unambiguous. Good rule: each status answers one question and has clear entry/exit conditions. If you want a new status, check if the issue can be solved by an attribute (e.g., "document pending", "payment dispute") rather than breaking the chain.

2) No source of truth for facts

If it’s unclear where "arrival" or "unloading" fact comes from, disputes will be endless: driver says one thing, warehouse another, accounting a third. Everyone is "right."

Decide in advance the primary source for each fact: carrier event, point staff mark, warehouse system, GPS, document scan. Record not only the value but also who/what set it and when. This reduces conflicts and simplifies incident investigation.

3) Documents stored as unstructured files

When supporting documents are just attached as files, you cannot manage them: you can’t check completeness, versioning, or block payments if a required confirmation is missing.

Make a document an entity with type (TTN/CMR/act/invoice), number, date, party, verification status, who checked, comment, linked trip and stage. The file remains, but control is built around data.

4) No separation of rights and roles

A common issue with multiple carriers: a carrier edits what they should only confirm. For example, changing planned dates, mileage or cost and then claiming "it changed itself."

Separate rights by create/ propose/ approve lifecycle. Use a simple approval mechanism: "change request" instead of direct edits. Always keep history: what changed, by whom and why.

5) No analytics on deviations

Without plan‑fact analytics, TMS turns into an archive: trips closed, documents attached, but you can’t see where the system loses time and money.

Add minimum metrics from day one:

• time deviations (arrival/unloading/closure);
• cost deviations (agreed vs actual);
• distance/route deviations (if applicable);
• share of trips missing full document set;
• reasons for deviations (small reference list).

If you cover these five areas early, your TMS will be more than a tracking table — it will be a trusted tool for dispatchers, carriers and finance.

Quick checklist before start and next steps

Before spending time on screens and integrations, check the foundation. Most TMS project problems start not with code but unclear rules: what is a fact, what closes a trip and which documents are mandatory.

30‑minute checklist

Answer and document the following. This will save weeks on disputed cases and rework:

• Are trip, order and document statuses separated? If everything lives in one status, it’s hard to see what actually "stalled."
• Are required events for trip closure defined (e.g., departure, arrival, start of unloading, finish) and who confirms them?
• Are plan‑fact rules defined: which fields are plan, where the fact comes from, one lateness formula (consider timezones and rounding)?
• Are payment/closure blockings configured when confirmations are missing (scans, EDI, signatures) and who can lift a block with a clear reason?
• Are two sample reports agreed: one for the dispatcher (operational control) and one for accounting (closure and payment)? Without examples requirements will drift.

If you can’t answer at least two items clearly, stop and define rules. Otherwise you’ll build a system where everyone can argue but few can work.

Next steps after the checklist

When rules are ready, move to practical steps with measurable outcomes:

• Collect 10–20 real trips across scenarios: single and multiple carriers, partial delivery, document return, delays. Test statuses, plan‑fact and closure on them.
• Define sources of facts: manual (dispatcher), carrier, GPS, warehouse, EDI. Assign a "data owner" for each source.
• Decide infrastructure: where TMS will run (office, branches), number of users, need for high availability, document storage volume. This affects server and workstation choices.
• Plan support: who is on duty nights and weekends, who fixes integrations, who updates reference data.

If you need help selecting and deploying infrastructure for your load, you can engage an integrator. For example, GSE.kz (gse.kz) as a system integrator can assist with server infrastructure and workstations, and organize support so the TMS doesn’t stop on peak closing days.