Rental 场景：应用、API 与 Webhook

先明确：谁创建什么？

你的租赁系统负责预订、价格、支付和商业决策。TrakarIA负责车辆实物检查：交车、还车、原始凭证、状况对比和报告。同一车辆可以经历多个连续的租赁周期。

访问方式	使用者	用途
分组 API 密钥	租赁软件的后端	同步车辆和档案、准备检查并读取结果。不得发送到操作人员的浏览器。
TrakarIA 账号	执行检查的人员	登录应用、拍照并验证。API 密钥不能替代个人账号。

根据业务目的选择场景

场景	使用时机	API 行为
提前预订	取车前已知预订	在实际交车前同步计划和可选客户上下文
现场交车	客户到达时预订信息还不完整	仅用稳定 ID 创建 Rental，之后用新版本补充信息
带变化的还车	需要验证完整生命周期	保留交车基准，验证还车并读取对比报告
取消	检查开始前取消预订	取消 Rental 并释放计划占用，但保留审计历史

同步是明确的后端操作：分别发送 PUT /v1/vehicles/by-external/{external_id} 和 PUT /v1/rentals/by-external/{external_id}。Rental 会立即出现在 TrakarIA 计划中。创建时只需路由外部 ID 和 vehicle_external_id；日期、业务编号、地点、联系人和驾驶人可以提前、现场交车时或之后用更新版本补充。未提供交车时间时使用创建时间，未提供还车时间时计划保持开放。更新同一资源必须复用相同外部 ID。没有这些调用，预订不会自动同步。

要让公开 API 中的 Rental 具备可执行检查，后端还要调用 POST /v1/rentals/{rental_id}/inspections，先准备 departure，再准备 return。返回的 launch_url 只负责打开正确流程，人员仍使用自己的账号登录。

验证后最多有两种官方报告：交车后的 departure 和还车后的 comparison。两者均提供 JSON 和 PDF，PDF 可能晚于 JSON。报告索引返回当前 ID。

**Webhook 是可选的。**如果需要自动通知，请为密钥配置目标，并订阅 rental.departure.completed、rental.return.completed 和可选的 rental.report.pdf_ready。后端验证签名，再从 API 获取报告；事件中不包含完整报告。未配置目标时，使用 GET /v1/events 和报告路由。不要把后端向外发送的 API 请求误认为传入的 Webhook。

验证完成后的处理顺序是：

公开检查状态变为 completed；
签名事件到达，或通过 GET /v1/events 恢复；
后端读取报告索引并归档不可变 JSON；
请求 PDF；收到 202 时遵守 Retry-After 或跟踪返回的 job。

场景 1：租赁软件已连接，并提供“打开检查”按钮

后端同步车辆和预订，保存 Rental id、planning.entry_id，后续变更使用严格递增的源版本。
交车时，用 {"type":"departure"} 和 Idempotency-Key 调用检查路由，保存检查 ID，并提供 launch_url 按钮。
工作人员打开链接、用自己的账号登录、采集照片并验证。链接本身不授予权限。
收到 rental.departure.completed 或轮询到结果后，后端归档 departure JSON，并在 PDF 就绪时下载。
还车时对同一路由发送 {"type":"return"}，并使用新的幂等键。
rental.return.completed 表示 comparison 已就绪。费用决策仍由租赁系统完成。

场景 2：租赁软件已连接，但不提供按钮

仍然需要 API 密钥。后端负责同步和准备检查，但可以忽略 launch_url。工作人员从 TrakarIA 应用中找到并恢复已经准备好的检查，不要为同一预订创建第二个租赁周期。报告和事件处理与场景 1 相同。

场景 3：全部在 TrakarIA 中完成，不使用 API

此时没有合作方 API 密钥，也没有与租赁系统同步。工作人员在应用中选择或创建车辆，在同一周期中完成交车和还车，并在 TrakarIA 中查看结果。外部租赁系统不会通过公开 API 收到事件或报告。仅在应用中创建的周期，之后也不会自动与 /v1/rentals 档案关联。

场景 4：预订或报告信息发生变化

**第一次检查前：**使用 upsert 或 PATCH 以及更新的源版本修改允许字段。收到 409 后，先读取当前档案。
交车前取消：/cancel 同时取消档案和计划条目。
**检查开始后：**车辆分配锁定；交车验证后，计划时间和地点也锁定。允许的更正会生成新的不可变报告版本。
**更正后：**归档每个新的 report_id 和版本；如已配置目标，rental.report.corrected 可发送通知。

场景 5：Webhook 接收端离线

验证每个签名，按 webhook-id 去重，再读取当前资源。恢复后使用带 cursor 或 created_after 的 GET /v1/events；处理成功后才推进 cursor。事件保留 30 天。

场景 6：检查链接已过期

先读取检查。若仍未结束，使用新的 Idempotency-Key 调用 /launch 并打开新链接。这会恢复同一个检查；工作人员仍需登录并具备权限。

集成系统应保存的数据

数据	原因
分组以及车辆、预订外部 ID	在重试或人员变化后仍能精确对账同一记录
公开 Rental 与检查 ID	无需私有 Kernel ID 即可打开和查询目标流程
计划条目 ID	确认哪个日历占用代表同步的预订
每个命令一把幂等键	响应丢失时安全重放
事件 cursor 和已处理事件 ID	恢复并去重通知
报告 ID、类型、版本和内容哈希	分别归档交车与对比版本

API 密钥和 Webhook 签名密钥必须保存在后端。不要把 launch_url 当作长期标识符；需要时重新生成。参阅快速开始和 Rental API 参考。