A cold-chain logistics provider built one telemetry API its customers actually integrate with

Representative examplesEvery case study in this library is an illustrative composite of the kind of engagement we deliver — written to show our method and standards, not to name clients.

Where they started

Temperature-controlled freight lives and dies on evidence: when a shipment's temperature drifted, who was told, and what the record shows. This cold-chain provider moves pharma and food loads for dozens of customers, each truck and reefer container streaming readings from vendor devices the provider did not choose. Customers consumed that telemetry three ways — emailed PDF reports, portal logins, and hand-maintained SFTP dumps — each maintained separately by the ops team. A retailer audit had just asked for a data format nobody had ever written down, which turned a chronic annoyance into a project.

What it was costing

Every customer wanted temperature telemetry differently — email reports, portal logins, bespoke SFTP dumps — and the ops team maintained each by hand; one retailer's audit asked for a data format nobody had ever written down.

What they could see

• Every new customer integration began with a negotiation about format and ended with a manual feed someone owned forever.
• Vendor devices arrived speaking different formats; each fleet onboarding meant hand-parsing a new export into whatever that customer wanted.
• Excursion notifications lagged hours behind the reading because they waited for the nightly report cycle.
• The retailer's audit request listed fields nobody had ever stored in one place; assembling evidence meant forensics across systems.
• Two customers received subtly different histories for the same shipment, and the ops team had no way to say which was right.

The constraints we worked inside

• Telemetry devices are heterogeneous across fleets and vendors; ingestion must accept the formats that exist, not the format wished for.
• Customers integrate with varying engineering depth — from a warehouse manager with a spreadsheet to a retailer's EDI team.
• A temperature excursion has legal weight; the record must be complete, ordered, and tamper-evident.

What had been tried before

Bought a fleet-telemetry SaaS and pointed the biggest vendor's devices at it.

It ingested that one vendor cleanly and nothing else, and exporting a complete, ordered history for an audit required the vendor's support queue.

Standardized customer reporting as a weekly PDF generated from the largest vendor's portal.

It covered one fleet's readings at report time, missed the vendors outside it, and still arrived too late to matter for an active excursion.

What we proposed

We proposed ingesting every vendor feed as it exists and normalizing into one shipment-telemetry model stored append-only, so downstream consumers see one honest, ordered timeline per shipment. On top of that model sit three documented integration tiers: portal and scheduled exports for the spreadsheet crowd, a clean REST API for mid-tier customers, and an EDI-shaped feed for the retailer — each documented as a product, not a favor. Excursions become first-class at ingestion: threshold breaches compute immediately, notify, and export as evidence, so an audit is a download rather than a forensic project across devices and inboxes.

Just as important is what we ruled out, and why:

• Replacing all vendor devices with one standard telematics fleet — The devices belong to customers and vendors with multi-year contracts; the integration layer had to accept the installed reality or wait out their procurement cycles.
• Building only the retailer's EDI feed to pass the audit — It would fix the audit and leave every other customer on hand-maintained feeds; the next audit would start the same scramble from scratch.
• A generic IoT platform with a rules engine — It handled device ingestion but not the shipment as the unit of record, and audit-grade evidence needed shipment-scoped ordering no generic rules layer provides.

How the work ran

Delivered by the systems pod — 2 engineers over 11 weeks, with working increments reviewed with the client every week.

The stack, and the reasoning

Node.js

Ingestion is many small parsing paths and few heavy computations; a single runtime with a streaming mindset kept adapters cheap to add and review.

TypeScript

Vendor payloads and the retailer's evidence format are two agreements the provider has to honor; typed models state each one in code, so a payload that breaks its agreement is refused at ingest with a name attached, not absorbed into a shipment's history.

Postgres + TimescaleDB

Telemetry is time-series by nature and audit is relational by nature; TimescaleDB over Postgres serves both without splitting the evidence across two systems.

REST + scheduled feeds

Customers span a warehouse manager with a spreadsheet and a retailer's EDI team; one model behind three tiers serves both without bespoke per-customer code.

Object-storage evidence exports

Audit evidence must be immutable and independently retrievable; signed, versioned exports in object storage keep the record tamper-evident and outside the database's lifecycle.

What went wrong

How we worked together

Cadence

Weekly integration demo where each tier was shown against its real consumer — portal for ops, API for a mid-tier customer, EDI mapping for the retailer's team.

Client side

The ops director owned vendor relationships and the integrations inventory; one dispatcher with an engineering background reviewed the normalized model; the retailer's EDI analyst joined mapping sessions.

Decisions

Format disputes were settled by the audit requirement first, customer commitments second, internal preference last; the order was written down and rarely argued with.

They provided

Sample exports from each vendor device family, access to the existing SFTP drops, the retailer's evidence checklist, and ops time for integration testing.

What changed

The headline: all customer integrations served from the normalized model, with the retailer audit passed from an evidence export — Hand-maintained feeds → one telemetry API, read from Customer integration inventory. A second check: excursion notification lag from sensor reading at Hours → minutes.

Onboarding a new customer is a menu now — portal, API, or feed, each documented, each served from the same timeline. Excursion calls go out while the shipment is still moving, which changed conversations from apology to coordination. The retailer's audit passed from an evidence export the provider generated itself, and the ops team retired the last hand-maintained SFTP drop within a month of launch. Most quietly, the team started trusting its own data — one history ended the doubt that hung over every dispute.

The result was read from Customer integration inventory against the pre-engagement baseline over the stated window, with a guardrail check on excursion notification lag from sensor reading. Where platform-reported numbers and business outcomes differ, this record says which layer it is quoting.

What they own now

• The ingestion pipeline repository with per-vendor adapters and their test fixtures
• API credentials management and the documented three-tier integration guides
• Object-storage evidence archive with retention and access configuration in the provider's account
• The excursion threshold configuration the ops director can retune per customer
• Runbook for onboarding a new vendor device feed end to end