What data does reliable shipment tracking need, and how should it integrate with carriers?
A reliable tracking module stores more than a tracking number and current status. It needs the order-to-package relationship, carrier identity, every event, the source payload, proof of delivery, and exception handling. Prefer official carrier or authorized aggregator webhooks, then use scheduled queries to recover missing events. Signature checks, idempotency, out-of-order handling, and reconciliation make the integration dependable.
When decomposing features, data, and acceptance scenarios, also compare Can a custom system integrate with WeCom, DingTalk, Feishu, ERP, and CRM?; the linked guidance adds context that should be considered in the same decision.
A shipment is an event history, not one status field
Model orders, packages, waybills, and tracking events separately. One order may split into several packages; a package may receive a replacement number or transfer to a last-mile carrier; each waybill produces events at different places and times. Overwriting an order-level value with “in transit” loses history, partial delivery, and evidence for an exception.
| Record | Important fields | Why it matters |
|---|---|---|
| Order-package link | order_id, package_id, sequence, items or quantity |
Supports split, combined, and partial delivery |
| Waybill | tracking_no, stable carrier_code, service, dispatch time |
Identifies the actual carrier service |
| Event | provider event ID, event time, received time, location, code, description | Reconstructs the timeline and handles late events |
| Delivery or exception | recipient, proof, exception code, responsible party, resolution | Supports fulfilment and after-sales work |
| Integration evidence | source, payload hash, raw payload, request ID, schema version | Diagnoses mapping and supplier disputes |
Keep both the business event time and the time your system received it. Offline scans, international transfers, and intermediary delays produce late or out-of-order messages. An older event arriving after delivery must not move the parcel back to “in transit.” Preserve the carrier's original code and map it into a small local vocabulary such as awaiting collection, in transit, out for delivery, delivered, exception, and returned. Send unknown codes to review instead of silently calling them “other.”
The event approach used by GS1 EPCIS is useful even when a project does not implement that standard: append new facts and retain correction relationships rather than rewriting history. Cold-chain or equipment shipments may also need timestamped sensor readings and units, not an unstructured note.
Use webhooks for speed and queries for recovery
Webhooks can be duplicated, delayed, reordered, or missed. Polling can recover gaps but consumes quota and may lag. Aggregators reduce the number of carrier integrations but introduce another supplier dependency. Production systems normally combine these methods.
Verify HTTPS, source signature, timestamp window, and replay protection before accepting a callback. Deduplicate by provider event ID or a stable business key, acknowledge quickly, then parse and notify through an asynchronous queue. Retry transient failures with backoff and supplier rate limits; alert and route exhausted retries to an operator. Store secrets in managed configuration, rotate them, and never log credentials or unnecessary recipient details. The OWASP REST Security Cheat Sheet provides a useful control baseline.
Query waybills that remain non-terminal without a new event beyond the expected window. Reconcile created waybills, first events, terminal states, and exceptions at a business-appropriate cadence. HTTP 200 only confirms that a request was accepted; validate schema, waybill match, event range, and status continuity. Retain sample payloads for contract testing and stage provider schema upgrades.
Acceptance should cover ordinary delivery, split packages, address changes, refusal, returns, cross-border handoff, duplicate callbacks, and reordered events. Monitor signature failures, duplicate and unknown events, ingestion latency, silent waybills, terminal coverage, and manual corrections. Targets derive from the selected carrier's contract and the client's operational tolerance—not the word “real-time.”
Wavesteam first obtains formal documentation and a test account, then proves creation, event return, exceptions, and reconciliation with representative samples. If an ERP or commerce platform already has reliable tracking, reusing and synchronizing it is usually better. A separate module becomes worthwhile for multi-carrier mapping, fulfilment analysis, or a cross-system operational loop. Wavesteam's enterprise solution describes the relevant integration scope.