Carrier-Integration Service Internals

This article explains, for Tai staff, how the standalone carrier-integration service behind the Tai TMS brokers carrier calls — including how tracking and document retrieval actually behave, how callers are authenticated, their limitations, and important operational caveats.

Overview

The carrier-integration service is a separate, standalone service that sits between the Tai TMS and the outside world of freight carriers and third-party logistics providers. Every outbound carrier call the TMS makes — getting a rate, dispatching a load, tracking a shipment, or pulling documents — goes through this one service. Its job is to translate the many different carrier formats into a single, consistent contract for each capability so the rest of the TMS never has to talk to a carrier directly. It is a translation and logging layer, not a system of record: it keeps no database of its own, stores nothing durably, and returns every result synchronously to whoever called it (the TMS back office or scheduled background jobs). Understanding how it handles tracking, documents, authentication, retries, caching, and logging is important when diagnosing "why didn't this update?", "why did the call come back unauthorized?", or "where did the carrier call log go?" questions.

How it works

The service exposes four capabilities — rating, dispatching, tracking, and imaging (documents) — and each capability fans out to the correct carrier-specific implementation based on the carrier identified on the request. The carrier lists differ by capability: roughly 126 carrier/provider types are mapped for rating, 112 for dispatching, 107 for tracking, and 80 for documents. Several carrier types share one underlying implementation, so the number of distinct implementations is lower — about 109 for rating, 95 for dispatching, 95 for tracking, and 66 for documents.

For tracking, a caller sends the carrier selector plus one or more reference numbers (such as the pickup or PRO number), and the service calls that carrier live, then normalizes the carrier's reply into one standard status, milestone dates, location, signed-by, and geocode. For documents, a caller sends the carrier selector, a PRO number, and the list of document types wanted; the service pulls the documents live from the carrier and returns them inline in the response. Every carrier call is wrapped in a decorator that runs the call, classifies any error, and writes an activity-log record when it finishes.

Each call is a single, live round trip to the carrier. There is no stored copy to fall back on and no queue — the caller waits for the carrier, subject to a per-request time limit (by default about 15 seconds, and the request must ask for between 15 and 75 seconds).

Two route sets per capability. Each capability is reachable on two routes that run the identical logic: a legacy route that anyone who can reach the service can call, and a secured twin under a "secure" path prefix that requires an authenticated caller (see the authentication rule below). The TMS back office has a separate setting for the secured address of each capability, and it chooses between the secured and legacy routes according to an application feature setting for authenticated carrier-integration calls. When that setting is on, the TMS fetches an internal access token and sends it as a bearer token with each call; when it is off, the TMS uses the legacy routes with no token.

What the TMS does with a tracking reply. A scheduled background tracking job works through the shipments whose linehaul carrier has an enabled tracking connection, in throttled batches, and spaces out calls to carriers that limit request rates. For each reply the TMS applies the status (some milestones become shipment alerts rather than status changes), the actual and scheduled pickup and delivery dates, the PRO and pickup numbers, and the signer's name, and it adds an in-transit location point labeled as coming from the carrier connection. On the TMS side, an HTTP 401 from the service is logged and shown as an authentication failure, a server error body is surfaced as the error message, and a validation failure (HTTP 400) is shown as the validation message; an empty result simply means no update.

Business rules & limits

Tracking is pull-only; there is no carrier push receiver. The only way status enters through this service is by the service actively asking the carrier. There is no webhook, callback, or inbound push endpoint for carriers to report status on their own. If a carrier offers push notifications, this service does not receive them — every status you see came from a live pull.
Documents are returned inline, not stored. Retrieved documents (proof of delivery, bill of lading, and the other supported types) are returned inside the response as encoded (base64) content. Nothing is written to disk, and there is no cloud object storage or file-store behind this service — the documents flow straight through to the caller, and it is the TMS that saves them as shipment attachments. Payloads can therefore be large, and there is no size cap or storage/URL indirection at this layer.
Document types retrieved. The document taxonomy this service can return includes proof of delivery (POD), bill of lading (BOL), corrected bill of lading, carrier invoice, carrier bill, inspection certificate, carrier confirmation, and a generic document type. Only the document types the caller requests are returned, and only those the carrier actually has for that shipment; a request must include at least one document type the chosen carrier supports, and each carrier has its own supported set (most carriers: POD and BOL; some add the carrier bill and the inspection certificate).
Which lookup number is used for documents. The TMS sends the shipment's PRO number for most carriers; for a few carriers and shipping platforms it sends the secondary bill of lading number in the PRO slot instead. A document request must carry a PRO value of at least two characters.
Authentication applies to the secured route set only. Only the secured twins of the capability endpoints (and a small test endpoint) check the caller. A caller must present a bearer token issued by the company's Azure AD tenant for this service's audience, and the token's group membership must include at least one group on the approved list kept in the service's per-environment settings. An empty or missing approved list denies every caller. A failure returns HTTP 401 with a short generic reason (missing or malformed header, not in an allowed group, or token validation failed); the detail is recorded only in telemetry, not returned to the caller. The legacy routes, the per-capability ping health checks, the warm-up route, and a TLS diagnostics page carry no authentication check, so the legacy routes remain open to anyone who can reach the service — protection for them still depends on how and where the service is deployed. Outbound carrier authentication is separate and is handled per carrier using that carrier's own credentials supplied on each request.
No response caching. Every request hits the live carrier. The service does not cache carrier responses, so two identical requests made back to back both make real carrier calls.
No automatic retry. Each call reaches the carrier exactly once. If it times out or the carrier errors, the service does not retry on its own; a fresh attempt is a new caller request. Retry logic, if any, lives with the caller (for example the scheduled tracking jobs), not here.
Empty/no-data results are expected, not errors. For tracking, benign outcomes — nothing available, a safe-to-ignore carrier condition, a timeout, or a transport error — come back as an empty (null) result with a successful response, not as a failure. For documents, a "no documents available" or safe-to-ignore condition returns an empty document set with a successful response. Genuinely unexpected errors, by contrast, are allowed to surface as a server error and are recorded in Application Insights. Callers must be written to treat an empty result as normal.
"Not found" is decided per carrier. There is no single rule: some carriers report "no tracking data" as a safe-to-ignore condition (which becomes an empty result), while others report it as an error that comes back as a server error with the carrier's message. Central Transport tracking treats a "bad request" response, or a reply that reads just "Not found", as safe to ignore, so those lookups return an empty result rather than a server error. A carrier whose reply is not valid structured data (for example a Central Transport reply that is not parseable) now has the raw carrier text preserved as the error message instead of a parsing failure, but it is still returned as a server error, not an empty result.
Carrier status codes are normalized to the TMS status set. Each carrier's own status vocabulary — including standardized EDI-214 status codes for carriers that use them — is mapped into the single normalized set of 20 tracking statuses the service returns. For example, a delivery-refused code maps to the refused status; a broad group of movement codes collapse to "in transit"; an out-for-delivery (including attempted-delivery) code maps to "out for delivery"; a delivered code maps to "delivered"; and a delay code maps to "shipment delayed." Some carrier codes intentionally map to nothing (no base status), meaning that milestone does not change the normalized status. This is why a raw carrier update can occasionally arrive without moving the TMS status. The TMS then applies the normalized status to the shipment: several statuses (customs hold or release, second and third rescheduled pickup attempts, on-hand at origin or destination, a requested delivery appointment) keep the shipment in transit and add an alert; a delay adds an alert without changing the status; and a carrier-reported "complete" is recorded as delivered.
Reference numbers can be corrected by the carrier. After a successful tracking call, the reference numbers from the request and from the carrier's result are merged, and non-empty values from the carrier win. A carrier-corrected PRO therefore replaces the value the caller supplied.
Supported reference types. A tracking request can identify the shipment by shipment id, customer reference, tracking reference, secondary BOL number, pickup number, PRO number, purchase order number, shipper reference, or quote number, but each carrier supports only some of them, and the request is rejected (HTTP 400) if none of the references supplied is supported by the chosen carrier or a required carrier setting is missing. The scheduled tracking job supplies every one of these that the shipment has on file except the quote number.
FedEx Freight (LTL) is a routing variant of the shared FedEx integration. The FedEx REST implementation is shared across capabilities (rating, tracking, and imaging). When a request carries the FedEx Freight source-parameter toggle, those services swap to FedEx's LTL Freight platform: a different authentication host (the FedEx Freight identity endpoint, with a freight-specific scope) and freight-specific tracking and document endpoints, instead of the legacy FedEx Express/Ground REST endpoints. The same carrier selector is used either way; the toggle is what decides which FedEx backend is called. This matters when diagnosing a FedEx account that works for one platform but not the other — a missing FedEx username or password still surfaces as a customer-facing error.
Multi-page documents are page-indexed by file name. When several returned pages share the same file name and document type, the service inserts a page suffix so pages are not overwritten. Carriers that already return distinct file names per page are left as-is.
Document log truncation is failure-only. When a document call fails and the error is rethrown, very long unbroken text in the logged response (a base64 blob) is cut short in the log copy only; the returned document content is never truncated, and successful calls log carrier text responses in full.
Activity logging is buffered and best-effort — records can be lost. Every carrier call is meant to produce one activity-log record, but logging is deliberately buffered and asynchronous. Records accumulate in an in-memory buffer and are only flushed after a short time threshold (about every 10 seconds) or once the buffer reaches a batch size (around 200 records). On flush, batches are sent to the back office in a fire-and-forget manner with no retry. The consequences staff should know: any records still sitting in the buffer when the service process recycles or restarts are lost, and a batch send that fails is not retried. Missing activity-log entries do not necessarily mean a carrier call did not happen. When a request does not say who made it, the log attributes it to the background job scheduler.
An unmapped carrier type is a server error, not a clean "unsupported" message. If a request names a carrier type that has no implementation for that capability, the call fails with a server error rather than a friendly message (documents raise an explicit "not supported" error; the other capabilities fail when the service tries to be built).
Dispatching skips the up-front request validation that rating, tracking, and documents perform, so a malformed dispatch request is not rejected before it reaches the carrier-specific check.
No system of record here. The service persists nothing durably and has no database, queue, or cache. Results — including document content — exist only in the live response. Anything that needs to be kept is the caller's responsibility to store on the TMS side.

Frequently asked questions

Does the carrier-integration service receive push/webhook tracking updates from carriers?

No. Tracking in the carrier-integration service is pull-only. The service has no inbound webhook or callback endpoint for carriers to report status; it only gets status by actively calling the carrier when a tracking request comes in. If someone expects a carrier's push notifications to update a shipment automatically through this service, that expectation is wrong — every status came from a live pull initiated by the TMS or a scheduled job.

Where are retrieved documents stored?

They are not stored by the carrier-integration service at all. Documents such as the proof of delivery and bill of lading are pulled live from the carrier and returned inline in the response as encoded (base64) content. There is no cloud object storage, file store, or disk persistence behind this service. The TMS saves the document as a shipment attachment; the service itself keeps nothing.

Does the service cache carrier responses or retry failed carrier calls?

No to both. Every request is a single live round trip to the carrier — there is no response cache, so repeated identical requests each hit the carrier, and there is no automatic retry, so a timeout or carrier error is not re-attempted inside the service. Any retry behavior is up to the caller (for example the background tracking jobs). This is why a transient carrier hiccup can produce an empty result that simply needs to be requested again.

A carrier call clearly happened but I can't find its activity-log record — why?

Activity logging is buffered and best-effort, so occasional missing records are expected rather than a sign the call didn't happen. Records are held in an in-memory buffer and only flushed on a time threshold (roughly every 10 seconds) or once a batch fills (around 200 records), and the flush is sent fire-and-forget with no retry. If the service process recycled or restarted while records were still buffered, or if a batch send failed, those records are lost. Treat gaps in the activity log as possible logging loss, not necessarily missing carrier activity.

How do carrier statuses become the standard TMS tracking statuses?

The service maps each carrier's own status vocabulary — including standardized EDI-214 codes where carriers use them — onto the single normalized set of tracking statuses used across the TMS. Broad groups of carrier movement codes collapse to "in transit," specific codes map to milestones like "out for delivery," "delivered," "delivery refused," or "shipment delayed," and some carrier codes are intentionally mapped to no base status. That last case is why a raw carrier update can sometimes arrive without changing the shipment's normalized status. After that, the TMS applies the status to the shipment, turning several milestones (such as a delay, a customs hold, or a refused delivery) into alerts instead of status changes.

Why did a tracking request return an empty result instead of an error?

In the carrier-integration service, benign tracking outcomes are treated as empty results, not failures. If the carrier has no data, returns a safe-to-ignore condition, times out, or has a transport-level hiccup, the service returns an empty (null) result with a successful response. Only genuinely unexpected errors are allowed to surface as a server error and get recorded in Application Insights. So an empty result is the normal signal for "nothing to report yet," and the caller should handle it as such and try again later if needed. Whether a "not found" reply counts as benign or as an error depends on the individual carrier's implementation.

Is the carrier-integration service protected by its own authentication?

Partly. Each capability has a secured route set that requires a bearer token from the company's Azure AD tenant, with the right audience and membership in an approved group; an empty approved-group list rejects everyone, and failures return HTTP 401 with a short reason while the detail goes to telemetry. The original legacy routes, the health pings, the warm-up route, and the TLS diagnostics page have no check of their own, so the legacy routes still depend on network and hosting boundaries for protection. Which route set the TMS uses is controlled by an application feature setting for authenticated carrier-integration calls. Outbound calls to carriers are separately authenticated per carrier using that carrier's own credentials.

Why did the TMS report a "carrier-integration authentication failed" error?

The TMS received an HTTP 401 from the secured route set. Typical causes are that the internal access token was missing, expired, or issued for the wrong audience, or that the identity behind it is not in an approved group for that environment (an empty approved list rejects every caller). The detail of why a token was refused is only in the service's telemetry as a warning, not in the response.

Can a carrier change the reference number on a shipment during tracking?

Yes. After a successful tracking call, the service merges the reference numbers from the request with those the carrier returned, and non-empty values from the carrier take precedence. So if a carrier returns a corrected PRO number, that corrected value replaces what the caller sent and is what the TMS carries forward. This is intended behavior so the TMS stays aligned with the carrier's own record.

Why does one FedEx account track fine but another comes back empty or errors?

FedEx is served by one shared FedEx integration that can talk to two different FedEx backends. A source-parameter toggle for FedEx Freight routes rating, tracking, and document requests to FedEx's LTL Freight platform — a different authentication host and freight-specific endpoints — while the default path uses FedEx's legacy Express/Ground endpoints. An account provisioned for one platform will not authenticate against the other, so a FedEx setup that works for parcel/ground can legitimately fail on freight (and vice versa). Check that the FedEx Freight toggle matches the account type, and that the FedEx credentials are present.