接 Vizion：用销售发放的 API Key 追踪集装箱里程碑
Vizion API Key 在开户时由 Vizion 销售发放——没有自助注册入口。把 Key 填进 Integration 里唯一的 api_key 字段，测试、配 Mapping、激活，集装箱里程碑随即供拖车追踪使用。
Vizion 连接器只做一件事：拖车业务的集装箱追踪。您用箱号、提单号或订舱号发起一次追踪（一个 reference），连接器带回该票货的里程碑更新：每个里程碑带的时间分两种——计划时间（预计，ETA）和实际时间（ATA）——既能看预期，也能看真实发生了什么。这就是全部范围：不拉订单，不建运单或调度单，不约码头时间，也不往 Vizion 回写任何数据。一个连接对应一个 Vizion API Key。
前置条件#
- 一个通过 Vizion 销售开好的 Vizion 账号，且包含 API 访问。API Key 在开户时由 Vizion 销售发放——没有自助注册页面，所以如果您还没有 Key，先向 Vizion 销售拿到 Key 是第零步，在本系统里做任何事之前。
- API Key 本身，以 Vizion 销售发给您的原样为准。保存好它到达时的原始消息或文档——Key 一旦丢失或被拒，只有 Vizion 销售能重新发放，没法从任何设置页里查出来或重新生成。
- 至少有一个您真正想追踪的箱号、提单号或订舱号，这样能拿一个您熟悉的运单核对头几次里程碑。有该票货的承运商代码（SCAC）时也一并备好——Vizion 能自动识别承运商，但官方建议是能给承运商代码时尽量给。
拿凭证#
- 联系 Vizion 销售，开通带 API 访问的 Vizion 账号（如果还没有）。API Key 会在开户过程中由 Vizion 销售发放。
- 从 Vizion 销售处收到 API Key。没有自助注册入口，也没有能自己建 Key 的开发者页面——如果某个页面或某个人说能在开户流程之外帮您「注册」一个 Vizion Key，那不是这个 Key 的发放方式。
- 把完整 Key 一次复制好，按发放的原样保留——本连接的 Key 以 vizion_ 开头——准备粘贴。不要截短，也不要加任何前缀。
- 凭证只有这一个，要记的 Vizion 地址也只有一个：https://prod.vizionapi.com。没有单独的沙箱地址要配——发放给您的 Key 就在同一个地址上测试和运行。
填进 Integration#
- 打开 Integration → 连接器市场 → Vizion → 新建连接。
- api_key——必填，Vizion API 密钥：粘贴 Vizion 销售发放给您的完整 Key，以 vizion_ 开头。这是本连接唯一的字段。它是密码类型字段，作为秘密保存。只按发放原样粘 Key 本身——X-API-Key 请求头由系统自己加。
- 保存连接后，先跑测试、再动其他设置——只有一个字段，测试不过就是这个 Key 或它背后的账号是否启用的问题，不用在一堆字段里找哪个填错了。
测试连接#
点测试连接。填了 Key 后，测试会发一次真实的只读请求：GET https://prod.vizionapi.com/references?limit=1，Key 以 X-API-Key 请求头发送，超时 12 秒。它只列您已激活的 reference、且只取 1 条，不会改动 Vizion 里的任何东西。测通会回「Vizion 认证通过」。Key 被拒，测试报 HTTP_401；api_key 为空，会以 MISSING_CREDENTIALS 停下；请求没能完成，会报 CONNECTION_FAILED。按结果指明的原因修好后重新测试。
配 Mapping / 选模板#
选 Vizion 标准 Mapping。它把 Vizion 为一个 reference 返回的每条里程碑更新，与您在本系统拖车追踪里看的集装箱记录对齐，并保留 Vizion 本身的时间区分：标为 planned 的里程碑带的是预计时间（ETA），未标 planned 的带的是实际时间（ATA）。测试通过后，先拿一个您熟悉的箱号、提单号或订舱号发起一次追踪，把头几个里程碑——事件、地点、以及每个时间是计划还是实际——与 Vizion 里同一票货显示的内容对照。对得上，Mapping 就没问题，可以激活。
激活#
激活后，您可以用箱号、提单号或订舱号发起追踪，连接会把这些 reference 的里程碑更新持续带进本系统的拖车追踪。发起 reference 时有两条 Vizion 的规则要守：提单号与订舱号二选一、绝不能同时给——同时给的请求会被拒绝；有承运商代码（SCAC）时尽量给上，因为自动识别承运商是兜底、不是首选路径。某个 reference 的更新也可以以推送形式到达，形态与拉取的更新相同，所以两种方式看到的内容一致。先在 运行监控 / 日志里盯头几个 reference、拿几票货与 Vizion 对照无误，再放手跑。
这个连接不做的事：不从任何其他系统拉订单或运单，不建调度单或装载单，不预订或更改码头时间，也不把追踪数据回传 Vizion。另外，它只追踪您发起的 reference——不会把您在别处攒下的运单历史导进来。
常见问题#
测试报 HTTP_401
Vizion 拒了您发过去的 Key。常见原因：复制时被截断、与发放原件差了字符，或这个 Key 已被 Vizion 替换、尚未在您的账号上启用。本连接按官方文档把 Key 以 X-API-Key 请求头发送，发送形态不是变量——问题在 Key 的值本身。
把粘贴的 Key 与 Vizion 销售发放的原件逐字对照，改掉任何差异，保存后重新测试。如果粘贴的 Key 与原件完全一致、测试仍报 HTTP_401，联系 Vizion 销售，请他们确认 Key 在您的账号上是否已启用、或重新发放——这只能由 Vizion 销售做，没有任何页面能让您自己重置。
测试以 MISSING_CREDENTIALS 停下
api_key 字段是空的，没有 Key 可发，测试也就无从校验。本连接只有一个字段，凭证不可能藏在别的地方。
把 Vizion 销售发放给您的完整 Key 粘进 api_key，保存连接后重新测试。如果您还没有 Key，先向 Vizion 销售拿到——没有注册页面能自己建。
找不到注册页——Vizion API Key 从哪里拿？
这是 Vizion 侧的设计：API Key 不是自助发放的。Key 在开通 Vizion 账号时由 Vizion 销售发放，所以确实没有能建 Key 的公开页面，本系统也无法替您生成。
联系 Vizion 销售，开通带 API 访问的账号，从他们那里收到 Key。然后回到本连接，把 Key 粘进 api_key，保存并测试。如果公司已有 Vizion 账号，先问当初开户的同事发放的 Key 记在哪里，不要急着再开第二个账号。
发起追踪报 INVALID_REQUEST——提单号和订舱号同时给了
Vizion 把这两个号码按二选一校验：一次追踪请求可以带提单号或订舱号，但同时带两个会被该校验拒绝。这是 Vizion 侧的规则，不是哪个号码错了——单独给任何一个都可以。
只带两个号码之一重新发起追踪——留提单号或订舱号，去掉另一个。也可以改用箱号作标识。有承运商代码（SCAC）时一并给上。
发起追踪报 INVALID_REQUEST——没有给任何标识
这次 reference 没有给任何标识。Vizion 靠一个标识发起追踪——箱号（container_id）、提单号或订舱号——三者都没有，就没有可建 reference 的对象。
用该票货的三个号码之一重新发起追踪——并记住配对规则：用了提单号，就不要再加订舱号。有承运商代码（SCAC）时给上，这样 Vizion 就不用自动识别承运商。
测试报 CONNECTION_FAILED，或 12 秒后超时
去 prod.vizionapi.com 的只读请求没能按时完成。这是去 Vizion API 路上的可达性问题，或 Vizion 临时变慢——不能据此断定 Key 错，因为只有 API 真正应答后才会判定 Key。
等一小段时间，不要改 Key，直接重新测试。若持续失败，求助时附上 运行监控 / 日志里的失败时间，并告诉 Vizion 支持：请求发往 https://prod.vizionapi.com、Key 在 X-API-Key 请求头里，便于他们对同一时间窗。
里程碑时间看着不对——在未来，或变来变去
那个里程碑多半是计划型的。Vizion 数据里，标 planned=true 的里程碑带的是预计时间（ETA），天然在未来、且会随货的移动而修订；planned=false 的里程碑带的是实际时间（ATA），一旦发生就固定了。预计时间在变，是数据在正常工作，不是追踪错了。
看里程碑时间之前，先看它的 planned 标记：计划安排围绕计划时间（ETA）做，只有实际时间（ATA）才当已发生的历史。若一个标为实际的时间与承运商或码头对同一事件显示的不一致，记下 reference 和事件，再请 Vizion 支持核查。