更新日志

本文件记录了该项目的所有重要变更。

更新日志格式遵循 Keep a Changelog， 版本号管理遵循 语义化版本规范（Semantic Versioning）。

版本：2.1.0

• POST /api/scan_form/create_scan_form：新增接口，为一组已购买的 USPS 运单创建 USPS SCAN Form（PS Form 5630），并在 scan_form_image 中返回 SCAN Form PDF 的 URL。

• POST /api/shipment/submit_pod：新增接口，为 USPS 运单提交 Proof of Delivery 请求，并将 POD 信件发送给 1–3 位收件人。返回 transaction_message，如 Your Proof of Delivery record is complete and will be processed shortly.
• GET /api/shipment/direct/tracking_by_tracking_no：响应新增字段 recipient_name，为签收人姓名（如 Alice）。

• 运单请求 options.signature：新增两个枚举值 —— usps_signature_restricted（限制投递的签名确认）和 usps_adult_signature_restricted（限制投递的成人签名，需 21 岁及以上）。原有值 signature 和 adult_signature 保持不变。

• GET /api/shipment/direct/tracking_by_tracking_no：响应新增字段 status_summary，为物流状态的可读摘要（如 Your item has been delivered and is available at a PO Box at 9:34 am on June 22, 2026 in GRANITEVILLE, SC 29829.）。该字段可空，无摘要时返回 null。
• POST /api/shipment/create_and_pay：响应新增两个字段 —— label_data，为每个面单 PNG 的 base64 内容，与 label_urls 一一对应（如 iVBORw0KGgoAAAANSUhEUgAA...AElFTkSuQmCC）；label_qr_code_data，为每个二维码面单 PNG 的 base64 内容，与 qrcode_urls 一一对应。label_qr_code_data 仅在 USPS 二维码面单场景下返回。
• POST /api/shipment/direct_buy：响应同样新增 label_data 和 label_qr_code_data 两个字段。

• 新增西班牙语文档支持，用户可在西班牙语下浏览 ShipSaving API 文档。

• 为 POST /api/shipment/pickup/add 接口中的 pickup_location 参数补充了字段级说明（长度限制、格式规则及必填要求），并为 package_location_ext 字段新增最大长度限制（255 字符）。
• 为 POST /api/shipment/pickup/add 和 POST /api/shipment/pickup/cancel 接口新增 400 响应示例。
• 在附录中新增「预约取件错误码（Pickup Error Codes）」章节，列出 POST /api/shipment/pickup/add 和 POST /api/shipment/pickup/cancel 接口可能返回的全部错误码。

• 在「集成指南」章节新增可下载的 Postman 合集（ZIP），包含 API 合集及环境文件（Sandbox 和 Production），方便快速测试。

• 新增文档页面 错误与限流（Errors & Rate Limits），涵盖错误响应格式、HTTP 状态码、错误码命名规则、限流机制及错误处理建议。
• 在附录（Appendix）中新增 错误码参考表。

• 在以下接口的响应中新增了 return_to_sender 字段：

  • GET /api/shipment/tracking_by_platform_uk_id

  该字段为布尔类型，用于表示运单是否已被退回给发件人。

• 在以下接口中新增对 USPS Returns 服务类型的支持：

  • POST /api/shipment/direct_buy

  当前支持的 USPS Returns 服务级别包括：

  • USPS_GROUND_ADVANTAGE_RETURN
  • USPS_PRIORITY_MAIL_RETURN
  • USPS_PRIORITY_MAIL_EXPRESS_RETURN

  具体的服务级别枚举定义请参考附录（Appendix）。

• 在以下接口的请求体中新增 return_address_data 对象：

  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

  该字段 仅支持 USPS，用于指定当包裹无法投递或被退回给发件人时的退回地址。

• 为新 API（v2）新增了版本专属的 Appendix，用于说明仅适用于 v2 的枚举定义和参考表。
• 已弃用顶层 Appendix 页面，并保留其作为向后兼容的入口，引导用户访问新 API（v2）的 Appendix。

• 新增中英文双语文档支持，支持在 ShipSaving API 文档中进行语言切换。

• 新增物流追踪接口 GET /api/shipment/direct/tracking_by_tracking_no，该接口返回包含UTC偏移量的ISO 8601格式物流事件时间戳，支持在不同时区环境下准确解析和还原事件发生的本地时间。

• 修正字段拼写错误：API 中字段 additional_handing 更名为 additional_handling。受影响的接口包括：
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• 在 carrier_package_code 枚举中新增 UPS Canada 预定义包裹编码。
• 新增布尔参数 require_saturday_delivery，用于指示在承运商和服务等级支持的情况下是否优先选择周六投递。
  当该参数设置为 true 时，可能会产生承运商附加费或更高的运费报价。受影响的接口包括：
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/direct_buy
  • POST /api/shipment/get_rates

• 以下接口新增对 UPS Canada 运费查询及运单面单购买的支持：
  • POST /api/shipment/batch/quick_rate
  • POST /api/shipment/get_rates
  • POST /api/shipment/direct_buy

• 更新承运商列表，新增对 SwiftX Express 承运商及其服务等级的支持。
• 更新 /api/shipment/batch/quick_rate 和 /api/shipment/get_rates：
  客户端可通过在 shipment_rate_carrier_data 中指定 provider_id="SWIFTX" 且 service_levels="SWIFTX_EXP" 来获取 SwiftX Express 的运费报价。
• 更新 /api/shipment/direct_buy：
  现已支持使用 SwiftX Express 购买运单面单。提交请求时需设置 carrier_code="SWIFTX" 且 service_level="SWIFTX_EXP"。

• 更新 /api/shipment/batch/quick_rate：
  新增可选参数 shipment_rate_carrier_data，允许客户端按指定承运商和服务等级获取运费报价，而非默认的 USPS Ground Advantage。
• 更新 /api/shipment/direct_buy：
  新增 carrier_code 和 service_level 字段，这两个字段共同决定用于购买面单的承运商服务等级。

• 增强 /api/shipment/tracking_by_tracking_no：
  新增 estimate_delivery_date、original_tracking_location 和 destination_tracking_location 字段，以提供更清晰的预计送达时间及更完整的承运商上报的始发地和目的地信息。

• 新增 USPS 承运商取件 API 套件，支持商户预约、取消及查询 USPS 取件请求：
  • POST /api/shipment/pickup/add —— 创建 USPS 取件请求
  • POST /api/shipment/pickup/cancel —— 取消已有取件请求
  • GET /api/shipment/pickup/list —— 获取取件记录分页列表
  • GET /api/shipment/pickup/package/location/list —— 获取可用的 USPS 包裹放置位置枚举值

• 扩展 /api/shipment/tracking_by_tracking_no：
  新增对 Amazon Shipping 物流追踪的支持，包括状态查询及事件历史。

• 新增 /api/shipment/tracking_by_tracking_no：
  支持通过 tracking_no 查询 USPS 和 UPS 的物流信息，返回当前物流状态、最新扫描信息及完整的物流事件历史。

• 更新 /api/shipment/direct_buy 和 /api/shipment/create_and_pay：
  当购买 USPS 服务且设置 "label_print_type": "qrcode" 时，接口将同时返回标准面单和二维码面单。

• 在 /api/shipment/direct_buy 和 /api/shipment/get_rates 接口中引入 is_return_label 参数，
  用于指定面单是否为退货运单，默认值为 false。

• 在 /api/shipment/tracking 和 /api/shipment/tracking_by_platform_uk_id 接口响应中新增字段 tracking_events（数组），
  用于表示完整的运单物流追踪时间线（所有追踪事件）。

• 为 /api/shipment/tracking 和 /api/shipment/tracking_by_platform_uk_id 接口响应中的 data.status 字段补充详细说明，
  并引入带描述的枚举状态值：
  • created、available_for_pickup、in_transit、out_for_delivery、delivered、return_to_sender、voided、error、seized_by_law_enforcement、unknown

• 新增 /api/shipment/batch/quick_rate 接口，支持批量运单运费查询（每次请求最多10条）。
• 在 /api/shipment/direct_buy 和 /api/shipment/create_and_pay 中新增重复创建校验机制。

• 在物流追踪接口中新增响应字段 scanned_time。
• 新增 /api/address/validate 接口，用于校验美国地址、返回标准化地址组件，并提供错误及修正信息。

• 新增 /api/shipment/tracking_by_platform_uk_id 接口，支持通过 platform_uk_id 查询运单物流状态。

• /api/shipment/void_label 接口新增对 platform_uk_id 的支持，用于作废运单面单。

• ShipSaving 新版 API 初始发布，支持运费查询、面单购买、面单作废以及运单物流追踪等核心功能。