接 Motive：把车队车辆位置接入在途跟踪

先在本系统外走完 Motive OAuth 2.0 授权流程，把拿到的 access token 粘进 Integration，API 地址非区域端点就留默认，测试、配 Mapping、激活——车辆位置随即供 TMS 在途跟踪使用。

Motive 连接器读取您 Motive 车队（原 KeepTruckin）的车辆位置，把位置转成 TMS 里的在途跟踪事件，在途运单可以按车辆位置跟踪。它只做这一件事：只读车辆位置。不拉订单，不建调度单或装载单，不读司机日志或驾驶时长记录，也不往 Motive 回写任何数据。一个连接对应一个 Motive access token。

前置条件#

• 一个 Motive 车队账号，车辆已在 Motive 里建好并在上报位置，且您想跟踪的车辆都已在 Motive 中就绪。
• 能在本系统外走完 Motive OAuth 2.0 authorization_code 流程——在 gomotive.com/oauth/authorize 授权、在 gomotive.com/oauth/token 换 token。本连接没有系统内授权按钮：您带来的是换好的 access token，粘贴填入。
• token 必须带车辆位置权限。没有这个权限，测试会回 MISSING_SCOPE，所以测试前先在 Motive Developer Portal 里核对 App 权限。
• 您清楚车队用的是默认 Motive API 地址还是区域端点。多数车队用默认地址，base_url 留空不填。

拿凭证#

1. 在本系统外启动 Motive OAuth 2.0 流程：打开 gomotive.com/oauth/authorize，按您的 Motive App 已配置的 authorization_code 流程批准车队 App 的访问。
2. 在 gomotive.com/oauth/token 用授权码换到 access token。token 是一长串字符，形态见填入步骤，开头类似 eyJraWQiOiIyMDIwXzEi。
3. 把完整 access token 一次复制好，准备粘贴。不要截短，不要加空格或换行——被截断的 token 会回 INVALID_TOKEN。
4. 记住这个 token 会过期。过期后本连接不能替您续期：您要再走一遍同样的 OAuth authorization_code 流程，粘贴新 token。提前安排好这次续期，别等车队位置停了才处理。

填进 Integration#

1. 打开 Integration → 连接器市场 → Motive → 新建连接。
2. token——必填，OAuth2 访问令牌：粘贴在 gomotive.com/oauth/token 换到的完整 access token，例如以 eyJraWQiOiIyMDIwXzEi 开头的一长串字符。这是密码类型字段，作为秘密保存。
3. base_url——选填，API 地址：留空即用默认的 https://api.gomotive.com。只有车队使用 Motive 区域 API 端点时才填，填时按 Motive 给的端点地址原样填。

测试连接#

点测试连接。填了 token 后，测试会发一次真实的只读请求：GET {base_url}/v2/vehicle_locations，用您的 token 作 Bearer 凭证，超时 12 秒。回 200 表示 token 被接受、车辆位置端点可达。回 401 会显示为 INVALID_TOKEN——token 无效或已过期。回 403 会显示为 MISSING_SCOPE——token 缺少车辆位置权限。请求超时未应答会显示为 TIMEOUT。按错误码指明的原因修好后重新测试：测试不会改动 Motive 里的任何数据。

配 Mapping / 选模板#

选 Motive 标准 Mapping。它把车队返回的每条车辆位置转成该车辆的 TMS 跟踪事件，位置就能与您在 TMS 里跟踪的车辆和运单对上。测试通过后先读一次，挑一辆您确定在路上的车，把这里的最新位置和 Motive 里同一辆车对一遍。对得上，Mapping 就没问题，可以激活。

激活#

激活后，连接通过您的 token 从 Motive 读取车辆位置，用最新车队位置更新 TMS 跟踪。先在 运行监控 / 日志里盯头几次读取、拿几辆车和 Motive 对照无误，再放手跑；同时把 token 过期日记下来，及时续期。

这个连接不做的事：不从 Motive 拉订单或装载单，不新建或修改调度，不读司机日志、驾驶时长或油耗记录，也不把位置或其他数据回传 Motive。这些事请继续在 Motive 里处理，或在实际作业的系统里处理。

常见问题#

测试报 INVALID_TOKEN（401）

Motive 拒了这个 token：它无效或已过期。OAuth authorization_code 流程换来的 access token 不是永久有效的，复制时被截断的 token 也会同样被拒——测试分不出是截断还是过期。

再走一遍 Motive OAuth authorization_code 流程——在 gomotive.com/oauth/authorize 授权、在 gomotive.com/oauth/token 换 token——把新 access token 完整复制、粘进 token 字段、保存后重新测试。本连接没有刷新按钮：新 token 只能来自新一轮 OAuth。

测试报 MISSING_SCOPE（403）

token 本身被接受了，但它不带车辆位置权限，Motive 不让它读车辆位置。问题不在您填的值：是发 token 时没有给那个 App 授予这个权限。

打开 Motive Developer Portal，检查 App 权限，确认车辆位置访问已授予，然后再走一遍 OAuth 流程换一个带该权限的 token，粘贴新 token 后重新测试。

测试报 TIMEOUT

车辆位置请求在 12 秒内没有应答。这是去 Motive API 路上的可达性问题——base_url 填错、区域端点对您的车队不应答，或 Motive API 临时变慢——不能据此断定 token 错。

先查 base_url：除非车队真的用区域端点，否则留空用默认的 https://api.gomotive.com。然后重新测试。若默认地址仍反复超时，等一小段时间再重试，求助时附上 运行监控 / 日志里的失败时间。

之前连得上，后来车辆位置不更新了

最常见的原因是 access token 到期了。连接里存的还是旧 token，它自己续不了，于是读取开始失败——日志里通常是 INVALID_TOKEN——而连接的其他设置什么都没变。

再走一遍 OAuth authorization_code 流程，把新 access token 粘进 token 字段，保存并测试。测试通过后位置就恢复更新了。这次记下新的过期日，下次在过期前续期。

连接成功，但有一辆车没有位置

连接返回的是 Motive 里有的车队位置：如果 Motive 本身就没有那辆车的当前位置——车辆熄火、不在覆盖范围或没有上报——本系统也就无从显示。连接再正常，也变不出 Motive 没有的位置。

先在 Motive 里查同一辆车。若 Motive 有当前位置而本系统没有，手动读一次，在 运行监控 / 日志里对照该车辆，并重新测试连接。若 Motive 里也没有，先在 Motive 侧处理那辆车的上报问题。

为什么没有订单或调度单从 Motive 进来？

因为本连接器只读车辆位置。订单、装载单和调度单不在它能从 Motive 读的范围内，所以这里订单列表为空是正常表现，不是连接坏了。

订单和调度请继续在实际作业的系统里建和管理；本连接用在它擅长的事上：在 TMS 跟踪里跟着运送这些运单的车辆走。