接 Samsara：把车队车辆 GPS 接入在途跟踪
在 Samsara 后台 Settings → API Tokens 里生成 API Token，授予 fleet、vehicles、stats 读权限，粘进 Integration，按区域选美国或欧盟的 Base URL，测试、配 Mapping、激活——车辆 GPS 随即供 TMS 在途跟踪使用。
Samsara 连接器读取您 Samsara 车队的车辆 GPS——每辆车的 GPS 时间、经纬度、朝向、速度，以及该位置反查到的地名——把这些位置转成 TMS 里的在途跟踪事件，在途运单可以按车辆跟踪。它只做这一件事：只读车辆位置。不拉订单，不建调度单或装载单，不读司机日志或驾驶时长记录，也不往 Samsara 回写任何数据。一个连接对应一个 Samsara API Token。
前置条件#
- 一个 Samsara 车队账号，车辆已在 Samsara 里建好并在上报 GPS，且您想跟踪的车辆都已在 Samsara 中就绪。
- 在 Samsara 后台有打开 Settings → API Tokens 并生成 token 的权限。生成 token 是管理员侧的操作：若您看不到这个页面，请让 Samsara 管理员替您生成。
- token 必须授予 fleet、vehicles、stats 的读权限。没有 stats 读权限的 token 读不到本连接赖以工作的 GPS stats，测试和读取都会卡在权限上。
- 您清楚 Samsara 账号属于哪个区域。美国账号用 https://api.samsara.com；欧盟账号用 https://api.eu.samsara.com。区域决定 base_url，选错区域，接口对您的车队不会应答。
拿凭证#
- 用能管理 API token 的账号登录 Samsara 后台，打开 Settings → API Tokens。
- 为本集成生成一个新的 API Token。生成时授予 fleet、vehicles、stats 三者的读权限——三者都要，因为本连接是从车队 stats 里读车辆 GPS。
- 把 Samsara 显示的 token 完整复制下来。它以 samsara_api_ 开头，后面跟一长串字符。在生成当下就复制好、准备粘贴——从这一刻起把它当密码对待。
- 同时再确认一次区域：账号在美国侧就是 US，在欧盟侧就是 EU。下一步的 base_url 就按这个答案填。
填进 Integration#
- 打开 Integration → 连接器市场 → Samsara → 新建连接。
- api_token——必填，API 令牌：粘贴在 Samsara 后台 Settings → API Tokens 里生成的完整 token，以 samsara_api_ 开头。这是密码类型字段，作为秘密保存。
- base_url——选填，Base URL：这个字段就是区域开关。美国账号留空，或填 https://api.samsara.com。欧盟客户必须改填 https://api.eu.samsara.com——用美国地址，欧盟车队不会应答。
测试连接#
点测试连接。填了 token 后，测试会发一次真实的只读请求：GET {base_url}/fleet/vehicles/stats?types=gps，用您的 token 作 Bearer 凭证，超时 12 秒。测通时结果会用文字确认：Bearer token 认证通过，车辆位置端点可达。回 401 或 403 表示 token 被拒——填错、已失效，或缺少该端点需要的读权限。请求超时未应答会报超时。修好原因后重新测试：测试不会改动 Samsara 里的任何数据。
配 Mapping / 选模板#
选 Samsara 标准 Mapping。它把每条车辆 GPS 记录——时间、经纬度、朝向、速度和位置对应的地名——转成该车辆的 TMS 跟踪事件，位置就能与您在 TMS 里跟踪的车辆和运单对上。测试通过后先读一次，挑一辆您确定在路上的车，把这里的最新位置、朝向和速度和 Samsara 里同一辆车对一遍。对得上，Mapping 就没问题，可以激活。
激活#
激活后，连接通过您的 token 从 Samsara 读取车辆 GPS，用最新车队位置、朝向和速度更新 TMS 跟踪。先在 运行监控 / 日志里盯头几次读取、拿几辆车和 Samsara 对照无误，再放手跑。
这个连接不做的事：不从 Samsara 拉订单或装载单，不新建或修改调度，不读司机日志、驾驶时长、摄像头或传感器记录，也不把位置或其他数据回传 Samsara。这些事请继续在 Samsara 里处理，或在实际作业的系统里处理。
常见问题#
测试报 401——token 被拒
Samsara 没有接受 api_token 里的值。常见原因都在值本身：粘贴时只粘了一部分、粘的是已失效的旧 token，或粘进字段的根本不是 Samsara API Token。
去 Samsara 后台 → Settings → API Tokens，重新生成一个带 fleet、vehicles、stats 读权限的 token，完整复制——以 samsara_api_ 开头——粘进 api_token，保存后重新测试。
测试报 403——token 缺读权限
token 到达了 Samsara，但它无权读测试要的东西。本连接从车队 stats 里读车辆 GPS，所以生成时没给 fleet、vehicles、stats 读权限的 token，哪怕 token 本身存在，也会在这个端点被拒。
在 Samsara 后台 → Settings → API Tokens 重新生成 token，这次在复制前先授予 fleet、vehicles、stats 读权限。把新 token 粘进 api_token，保存后重新测试——旧 token 改不了，它的权限在生成时就定死了。
测试超时，一直不应答
GPS stats 请求在 12 秒内没有应答。这是去 Samsara API 路上的可达性问题——最常见是 base_url 指向了与车队不符的区域，或 Samsara API 临时变慢——不能据此断定 token 错。
先按区域查 base_url：美国是 https://api.samsara.com，欧盟是 https://api.eu.samsara.com。若指向了另一个区域，改对后重新测试。若区域正确仍反复超时，等一小段时间再重试，求助时附上 运行监控 / 日志里的失败时间。
欧盟车队：每项看着都对，测试还是失败
连接还指着美国的 API 地址。base_url 默认是 https://api.samsara.com，欧盟账号在那个地址不应答——token 和权限再完美，欧盟车队也不会在美国地址上响应。
把 base_url 改成 https://api.eu.samsara.com，保存后用同一个 token 重新测试同一个连接——先不要生成新 token，也不要改其他任何值。
连接成功，但有一辆车没有 GPS
连接返回的是 Samsara 里有的车队 GPS：如果 Samsara 本身就没有那辆车的当前 GPS——车辆熄火、不在覆盖范围或没有上报——本系统也就无从显示。连接再正常，也变不出 Samsara 没有的位置。
先在 Samsara 里查同一辆车。若 Samsara 有当前位置而本系统没有，手动读一次，在 运行监控 / 日志里对照该车辆，并重新测试连接。若 Samsara 里也没有，先在 Samsara 侧处理那辆车的上报问题。
为什么没有订单或调度单从 Samsara 进来？
因为本连接器只读车辆 GPS 位置。订单、装载单和调度单不在它能从 Samsara 读的范围内，所以这里订单列表为空是正常表现，不是连接坏了。
订单和调度请继续在实际作业的系统里建和管理；本连接用在它擅长的事上：在 TMS 跟踪里跟着运送这些运单的车辆走，连位置、朝向和速度一起看。