Integrations cookbook: carriers and tracking

Tracking quality depends on carrier integrations. This cookbook covers the common providers: what to configure, how to test, what to watch.

Project44 (ocean + road)

• Credentials from your Project44 account manager.
• Enter in /app/admin/integrations/project44.
• Select which carriers to subscribe to (pay-per-carrier typically).
• Coverage: major ocean carriers, major road LTL (US) + freight-forwarding shippers.

Testing

• Book a real shipment with a valid BL / container number.
• Within 1–2 hours, vessel + container events should appear on the shipment timeline.
• No events after 24 hours → check mapping: P44 requires the carrier code + BL in their format.

Known pitfalls

• BL format: some carriers expect uppercase, no dashes. P44 is forgiving but the carrier isn't.
• Missing empty-return events: not all carriers publish empty-return; supplement with terminal APIs if needed.

CargoAi (air)

• API key from CargoAi.
• Configure in /app/admin/integrations/cargoai.
• Coverage: most major airlines via Cargo iQ.

Testing

• MAWB with a valid carrier prefix.
• Events populate within minutes for live shipments; historical shipments may be empty (most airlines only publish live).

Known pitfalls

• Carrier coverage gaps: smaller regional carriers may not publish. Fallback to website scraping.
• Event translation: airline codes ("RCS", "DEP") map to our plain-language milestones. Custom carriers may need mapping additions.

Carrier-direct (major ocean)

For Maersk, CMA CGM, Hapag-Lloyd, ONE, MSC:

• Each carrier has its own T&T API.
• Onboarding with the carrier's developer portal.
• Credentials + container list subscription.

When to use direct vs aggregator

• Aggregator (P44) — preferred for multi-carrier. Single integration, single vendor.
• Direct — use when you ship > 500 TEU/year with one carrier; better SLA, sometimes lower cost, sometimes more event granularity.

Telematics (road)

Supported: Geotab, Samsara, Webfleet, Fleetio.

Setup

• OAuth or API key per provider.
• Vehicle-id mapping — match telematics vehicle id to platform vehicle id.
• Event subscription: ignition, position, geofence.

Why it matters

• Fills live GPS between driver-app stop events.
• Drives accurate ETA for in-transit trips.
• Powers detention / waiting computation via arrival / departure timestamps.

Pitfalls

• Vehicle mapping drift: when a telematics device moves between vehicles, the mapping needs updating. Alert at /app/admin/integrations/health.

Integration health monitoring

/app/admin/integrations/health shows:

• Last successful event per provider.
• Error rate.
• Rate-limit consumption.
• Auth expiry warnings (reauth needed in X days).

Alerts wire to email / Slack.

API + webhooks pattern

For custom carriers or one-off integrations:

• Custom inbound webhook at /api/inbound/{provider} — we map the payload into our event schema.
• Bring-your-own pull adapter — we call your endpoint on a schedule.

Data volume

Tracking integrations can generate millions of events per year. Data retained hot for 12 months, archived thereafter, queryable via API with latency.