接 Terminal49：按箱号、提单号或订舱号追踪集装箱
在 app.terminal49.com/developers/api-keys 自助拿一个免费 Developer Key，把它填进 Integration 里唯一的 api_key 字段，测试、配 Mapping、激活——集装箱里程碑、船舶计划与码头可用性随即供拖车追踪使用。
Terminal49 连接器只做一件事：拖车业务的集装箱追踪。您用箱号、提单号或订舱号发起追踪，连接器带回里程碑、船舶计划与码头可用性——包括码头报的 Last Free Day（最后免费期）、扣放（holds）与费用。这就是全部范围：不拉订单，不建运单或调度单，不约码头时间，也不往 Terminal49 回写任何数据。一个连接对应一个 Terminal49 API Key。
前置条件#
- 一个能登录 app.terminal49.com 的 Terminal49 账号，能自己打开开发者 API Key 页面。Key 是自助获取的：开始接入不需要联系销售、也不用等审批。
- 至少有一个您真正想追踪的箱号、提单号或订舱号，这样能拿一个您熟悉的运单核对头几次追踪结果。
- 正式依赖免费 Key 前先算清追踪量：免费 Developer Key 最多追踪 100 个集装箱。用来评估连接完全够用，但生产上用哪个 Key，要按您同时追踪的箱量来规划。
拿凭证#
- 登录 app.terminal49.com，打开开发者 API Key 页面：app.terminal49.com/developers/api-keys。
- 在该页面新建一个 Key。免费 Developer Key 就够完成连接与评估：可追踪最多 100 个集装箱。
- 把完整 API Key 一次复制好，准备粘贴。不要截短，也不要给它加任何前缀——Key 本身就是全部凭证。
- 凭证只有这一个。没有单独的用户名、密码、沙箱 Key 或第二个 Key 要收，测试与生产用的是同一个 Terminal49 地址——您测试用的就是之后跑生产用的同一个 Key。
填进 Integration#
- 打开 Integration → 连接器市场 → Terminal49 → 新建连接。
- api_key——必填，Terminal49 API 密钥：粘贴从 app.terminal49.com/developers/api-keys 复制的完整 Key。这是本连接唯一的字段。它是密码类型字段，作为秘密保存。只粘 Key 本身，前面不要带 "Token" 或 "Bearer" 字样——请求头形态由系统自己加。
- 保存连接后，先跑测试、再动其他设置——只有一个字段，测试不过就是这个 Key 的问题，不用在一堆字段里找哪个填错了。
测试连接#
点测试连接。填了 Key 后，测试会发一次真实的只读请求：GET https://api.terminal49.com/v2/tracking_requests?page[size]=1，Key 以 "Authorization: Token <API_KEY>" 形态发送，超时 12 秒。它只读您已有追踪请求的第一页，不会改动 Terminal49 里的任何东西。测通会回「Terminal49 认证通过」。Key 被拒，测试报 HTTP_401；api_key 为空，会以 MISSING_CREDENTIALS 停下；请求没能完成，会报 CONNECTION_FAILED。按结果指明的原因修好后重新测试。
配 Mapping / 选模板#
选 Terminal49 标准 Mapping。它把 Terminal49 返回的每条追踪结果——里程碑、船舶计划，以及 Last Free Day、扣放与费用等码头可用性——与您在本系统拖车追踪里看的集装箱记录对齐。测试通过后，先拿一个您熟悉的箱号、提单号或订舱号发起一次追踪，把里程碑和码头日期与 Terminal49 里同一票货显示的内容并排对照。对得上，Mapping 就没问题，可以激活。
激活#
激活后，您可以用箱号、提单号或订舱号发起追踪——三者给其一，有承运商 SCAC 时一并给上——连接会把这些箱子的里程碑、船舶计划与码头可用性持续更新到本系统。Terminal49 侧对追踪请求限流为每分钟 100 次，所以大批量发起时会摊开提交、而不是一瞬间全打出去。先在 运行监控 / 日志里盯头几批追踪结果、拿几个箱子与 Terminal49 对照无误，再放手跑。
这个连接不做的事：不从任何其他系统拉订单或运单，不建调度单或装载单，不预订或更改码头时间，也不把追踪数据回传 Terminal49。另外，它只追踪您发起追踪的箱子——不会把您在 Terminal49 的全部历史运单自动找出来导进来。
常见问题#
测试报 HTTP_401
Terminal49 拒了您发过去的 Key。常见原因：复制时被截断、粘贴时前面多带了一个词，或这个 Key 在您复制之后已被 Terminal49 账号里删除或替换。地址和连接都没问题——这个错误码只和 Key 本身有关。
打开 app.terminal49.com/developers/api-keys，新建一个 Key，完整复制、前面不带任何词，粘进 api_key 字段，保存后重新测试。如果您是手动验 API，记住请求头形态是 "Authorization: Token <API_KEY>"——用 Bearer 的方式验，Key 对了也会失败。
测试以 MISSING_CREDENTIALS 停下
api_key 字段是空的，没有 Key 可发，测试也就无从校验。本连接只有一个字段，凭证不可能藏在别的地方。
把从 app.terminal49.com/developers/api-keys 复制的完整 Key 粘进 api_key，保存连接后重新测试。
测试报 CONNECTION_FAILED，或 12 秒后超时
去 Terminal49 API 的只读请求没能按时完成。这是去 api.terminal49.com 路上的可达性问题，或 Terminal49 临时变慢——不能据此断定 Key 错，因为只有 API 真正应答后才会判定 Key。
等一小段时间，不要改 Key，直接重新测试。若持续失败，求助时附上 运行监控 / 日志里的失败时间，便于和 Terminal49 侧对时间窗。
发起追踪报 INVALID_REQUEST
这次追踪请求没有给任何标识。Terminal49 靠一个标识发起追踪——箱号、提单号或订舱号——三者都没有，就没有可发起的东西。
用该票货的三个号码之一重新发起追踪；有承运商 SCAC 时一并给上——它能帮 Terminal49 把请求对到正确的承运商。
一次发起很多箱子时报 HTTP_429
您撞上了 Terminal49 的限流：追踪请求上限是每分钟 100 次。Key 和失败的那些箱子都没问题——只是发得比 Terminal49 接受的速度快。
把失败的箱子拆成更小的批次、摊到一分钟以上再重新发起，不要整批同时重试。已经发起成功的箱子会照常继续追踪。
追踪到约 100 个箱子后，新箱子不再被追踪
您用的是免费 Developer Key，最多追踪 100 个集装箱。连接和 Key 都是通的——前一百个就是证明——只是免费 Key 同时容不下更多箱子了。
把连接换成箱量额度够您实际业务量的 Terminal49 Key：在您的 Terminal49 账号里新建或取得该 Key，粘进 api_key 替换掉免费 Key，保存并测试。已在免费 Key 下发起的追踪不是本系统里的一个设置——业务量涨上来时，先查 Key 的额度。