# ShipSaving New API

Version: v2
License: Apache 2.0

## Servers

[object Object]
```
https://x-api.shipsaving.com
```

## Security

### BearerAuth

[object Object]

Type: http
Scheme: bearer
Bearer Format: JWT

### basicAuth

[object Object]

Type: http
Scheme: basic

## Download OpenAPI description

 - [ShipSaving New API](https://docs.shipsaving.com/_bundle/@l10n/zh-Hans/v2/openapi.yaml)

## 认证与授权

 - [POST /oauth2/token](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%AE%A4%E8%AF%81%E4%B8%8E%E6%8E%88%E6%9D%83/getaccesstoken.md): 使用 OAuth 2.1 **Client Credentials** 授权模式签发一个**短期有效的访问令牌**。 请在请求中提供以下信息： - `Authorization: Basic base64(AppKey:AppSecret)` - `Content-Type: application/x-www-form-urlencoded`
## 运单

 - [POST /api/shipment/batch/quick_rate](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/batchquickrate.md): 该接口允许通过提供 `from_address_data`、`to_address_data`、`package_data` 和 `ship_date` 快速获取运单运费报价。 **每次 API 调用最多可包含10个独立的运费报价请求。** 此前，该接口仅返回USPS Ground Advantage的运费报价。现在，你可以通过 `shipment_rate_carrier_data` 字段可选地
 - [POST /api/shipment/get_rates](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/getrates.md): 获取你账户下所有启用的承运商及服务等级的运费报价，并可按指定的承运商和服务等级进行可选筛选。返回结果将按照最快、最便宜等条件进行排序，同时包含适用的错误信息（如有）。
 - [POST /api/shipment/create_and_pay](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/createandpay.md): 使用先前 `get_rates` 接口返回的 `rate_id` 创建并支付运单面单。该接口还支持在同一次请求中购买运单保险（保险不可单独购买）。 为防止因网络波动或重试导致的重复购买，API会检查在指定的 `platform_uk_id` 下是否已存在对应的运单。 - 若发现已存在相关运单，则直接返回该运单信息，并将响应中的 `duplicate_label` 字段设置为 `true`。 - 若
 - [POST /api/shipment/direct_buy](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/directbuy.md): 无需单独调用 `get_rates` 接口，即可一步完成运单面单的创建与购买。 该接口当前支持 USPS Returns 服务类型，完整的支持列表请参阅附录（Appendix）。 为防止因网络波动或重试导致的重复购买，API会检查在指定的 `platform_uk_id` 下是否已存在对应的运单。 - 若发现已存在相关运单，则直接返回该运单信息，并将响应中的 `duplicate_label` 字
 - [POST /api/shipment/void_label](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/voidlabel.md): 该接口支持通过 **以下任一方式** 作废运单面单：`shipment_no` 或 `platform_uk_id`。仅需提供其中一个参数即可唯一标识一条运单。
 - [GET /api/shipment/insurance/rate](https://docs.shipsaving.com/zh-hans/v2/openapi/%E8%BF%90%E5%8D%95/paths/~1api~1shipment~1insurance~1rate/get.md)
## 物流轨迹

 - [GET /api/shipment/direct/tracking_by_tracking_no](https://docs.shipsaving.com/zh-hans/v2/openapi/%E7%89%A9%E6%B5%81%E8%BD%A8%E8%BF%B9/getshipmenttrackingwithutcoffset.md): 获取承运商上报的当前运单追踪事件、首次扫描事件以及完整的物流追踪事件历史。 该接口返回的所有物流事件时间戳均采用包含UTC偏移量的ISO 8601格式， 以便客户端在不同时区环境下准确解析和还原事件发生的本地时间。
 - [POST /api/shipment/submit_pod](https://docs.shipsaving.com/zh-hans/v2/openapi/%E7%89%A9%E6%B5%81%E8%BD%A8%E8%BF%B9/submitpod.md): 为已送达的运单提交 Proof of Delivery（签收凭证）请求。目前仅支持 USPS（`carrier_code = USPS`），其他承运商会返回业务错误。
## 预约取件

 - [POST /api/shipment/pickup/add](https://docs.shipsaving.com/zh-hans/v2/openapi/%E9%A2%84%E7%BA%A6%E5%8F%96%E4%BB%B6/addpickupbyshipment.md): 使用已有的发货信息创建 USPS 承运商取件请求。该接口会安排 USPS 快递员在**下一个 USPS 投递日**上门取走符合条件的包裹。 该接口可能返回的全部错误码，请参见[附录 — 预约取件错误码](https://docs.shipsaving.com/zh-hans/v2/appendix#post-apishipmentpickupadd)。
 - [POST /api/shipment/pickup/cancel](https://docs.shipsaving.com/zh-hans/v2/openapi/%E9%A2%84%E7%BA%A6%E5%8F%96%E4%BB%B6/cancelpickup.md): 取消先前已预约的承运商取件。取件一旦被取消，将无法再次更新或取消。该接口除 `pickup_no` 外不需要提供任何其他参数。取消成功后，取件状态将变更为 `CANCELED`。 该接口可能返回的全部错误码，请参见[附录 — 预约取件错误码](https://docs.shipsaving.com/zh-hans/v2/appendix#post-apishipmentpickupcancel)。
 - [GET /api/shipment/pickup/list](https://docs.shipsaving.com/zh-hans/v2/openapi/%E9%A2%84%E7%BA%A6%E5%8F%96%E4%BB%B6/getpickuplist.md): 获取系统中已创建的取件记录分页列表。该接口支持按USPS确认号、取件状态以及承运商代码等条件进行可选筛选。分页参数（`page`和`page_size`）用于控制返回数据集的大小，`order_by`参数用于指定结果的排序方式。
 - [GET /api/shipment/pickup/package/location/list](https://docs.shipsaving.com/zh-hans/v2/openapi/%E9%A2%84%E7%BA%A6%E5%8F%96%E4%BB%B6/getpackagelocation.md): 返回有效的包裹放置位置枚举值列表。这些枚举值用于指示在预约取件时，包裹将被放置在取件地址的具体位置，供USPS邮政投递员上门取件。
## 地址验证

 - [POST /api/address/validate](https://docs.shipsaving.com/zh-hans/v2/openapi/%E5%9C%B0%E5%9D%80%E9%AA%8C%E8%AF%81/validateaddress.md): 地址校验接口用于校验**美国国内地址**的有效性，并按照 **USPS® 地址规范**返回标准化后的地址组成部分。该API有助于提升投递准确率、减少无法投递的包裹，并为物流与运费计算提供一致且可靠的地址基础。
## SCAN Form

 - [POST /api/scan_form/create_scan_form](https://docs.shipsaving.com/zh-hans/v2/openapi/scan-form/createscanform.md): 为一组已购买的运单创建 USPS SCAN Form（PS Form 5630），并返回生成的清单 PDF 的 URL。SCAN Form 是一张把多个运单合并到一起的清单条码，承运商在揽收时扫描这一张即可一次性接收整批运单。