在开始之前，先明确几个前提：假设你是一名专注于 Java Spring Boot 3.2+ 微服务架构的后端工程师。对于 OpenFeign 远程调用、JWT 鉴权、HTTP 状态码等基础能力，你早已熟练掌握。因此，本文不会手把手教你注册应用、申请 token，而是直接聚焦于 /v2/shipment/confirm 接口本身——前提是你已通过正规渠道获取到 access_token，并且采用微服务内部共享密钥校验模式。

需要特别说明的是，自定义错误码 4102 并非通用的 HTTP 状态码衍生值。在你的业务系统语义中，它对应以下场景：“该货运单已处于不可重复确认的状态”。也就是说，当接口返回 error_code=4102 时，你需要追溯该单号在业务状态机中的当前流转环节——是已被“司机接单”锁定，还是已标记为“完成配送”的终态。一旦触发 4102，说明当前确认操作被上游业务规则拦截，不能再通过简单重试来规避。

调用前提与上下文

直接进入核心要点：无需重复赘述 OAuth2 授权流程。当你的应用已持有有效的 access_token 时，按照标准 HTTP 头 Authorization: Bearer {token} 传入即可。我们的接口在鉴权层识别该 token 后，会直接进入业务逻辑处理。如果你的 token 失效，且能触发全局 TokenRefreshFilter 自动续期，那么对接成本将更低。

接口调用上下文

调用 /v2/shipment/confirm 必须绑定一个具体的前置条件：你必须先通过 /v2/shipment/preConfirm 或内部事件接收到一个“待确认”状态的货运单。换句话说，该接口不允许你随意确认任意单号——后端的状态机只允许处于“待确认”状态的单据执行此步骤。如果你们的对接流程跳过了预确认环节，那么 4102 的出现几乎是必然的。

自定义错误码 4102 的业务语义

4102 并不代表服务器崩溃，也不意味着参数格式错误。 它是业务层主动抛出的守门逻辑。常见触发场景有两种：
1. 该单据已被其他系统（如仓储管理系统、配送调度中心）提前确认，导致状态机已向前推进了一步；
2. 该单据因合同过期、车辆调度异常等原因，被业务规则判定为“不可继续确认”。

建议做法：收到 4102 后，先调用 /v2/shipment/query 查询该单据的当前实际状态字段，对照你们约定的状态机流转图，找出冲突点。不要盲目重复重试同一接口，那只会增加无谓的负载和日志噪音。

常见易错点：timestamp 和 signature

这部分可能是对接中最容易踩坑的地方。先看时间戳。

你可能会遇到 timestamp 单位混淆的问题——我们的接口接收的是 秒级时间戳，而非毫秒。如果你在开发时直接将 System.currentTimeMillis() 裸传过去，接口会返回 signature 验签失败。原因在于：服务端在拼接签名串时使用秒级值，而客户端传的是毫秒级，两者拼接出的 hash 天然不匹配。

建议检查项：
• 是否传了毫秒级时间戳（13位数字）？请改为秒级（10位）。
• 是否与服务器时间误差超过 300 秒？如果偏差过大，即使类型正确，签名依然会因时间窗校验失败。

再说 signature 验签。当接口返回 HTTP 500 但 message 值为 'invalid signature' 时，最直接的排查点有两个：
1. 密钥拼接顺序：我们要求的拼接顺序是 secretKey + timestamp + access_token，不能随意调换顺序。顺序错了，即使算法选对也无济于事。
2. 哈希算法版本：当前强制使用 SHA-256 生成加签串。如果你那边混用了 HMAC-SHA1 或 MD5，验签必然失败。

如果在排查过程中反复检查拼接逻辑和算法仍未发现问题，建议将加签前的原始字符串打印到日志中，与服务器端预期的拼接字符串逐字符比对——包括空格、换行符等隐藏字符。90% 的隐性问题都藏在这些细节里。

防御性建议摘要

再强调一遍：调用 /v2/shipment/confirm 时，请先确认 timestamp 是秒级，signature 按照正确顺序使用 SHA-256 拼接，并且 token 有效且字段传对。如果返回 4102，不要盲目重试，先去查询该单据的当前业务状态。说白了，这类对接工作，大部分时间不是在写代码，而是在排查机器之间那些“我以为你懂但我其实没对齐”的细微差异。