认证

ShipSaving 新版 API 采用 OAuth 2.1 框架，相比传统的单一 API Key 认证方式，提供了更高的安全性、标准化的授权机制以及更强的可扩展性。
该 API 实现了 Client Credentials Grant 授权流程，使后端服务能够使用自身凭证安全地获取访问令牌（Access Token），并与受保护的资源进行交互。

主要安全特性

双因素认证：结合 client_id（app_key）与 client_secret（app_secret）进行双重校验。
短时有效访问令牌：访问令牌默认有效期为 30分钟，可降低令牌泄露带来的风险。
基于 Scope 的访问控制：API 访问权限依据 scope 参数进行限制与控制。
令牌吊销机制：提供访问令牌吊销接口，用于降低潜在的安全暴露风险。

测试模式与正式模式

类型	使用场景	注意事项
测试模式	在测试和构建 ShipSaving 集成过程中，请使用测试模式及对应的测试密钥。在测试模式下，你可以使用 ShipSaving 提供的所有服务，例如查询运费和创建示例面单，且不会产生任何费用。	测试模式下购买的面单均为示例面单，不可用于实际发货。测试模式下查询的运费可能与正式模式存在差异。测试数据与正式账户数据完全隔离。
正式模式	当你的集成准备好投入生产环境时，请使用正式模式及正式访问令牌。在正式模式下，你可以查询真实运费并购买可用于发货的正式面单。	正式模式下购买的面单可用于实际运输，并会生成真实的交易记录。购买面单将从你的账户中扣费。

认证流程

创建你的 ShipSaving 账户

注册一个 ShipSaving API Portal 账户。

完成注册表单并验证你的邮箱地址。
在完成邮箱验证前你仍可登录账户，但无法创建 API Key。
邮箱验证完成后，你即可管理密钥并生成 测试（test） 或 正式（live） API Key。

生成 API Key

WARNING

API Key 一旦生成，请务必妥善保管——该密钥拥有你账户的完整访问权限。
API Key 仅在创建时显示一次；若窗口关闭，将无法再次查看或找回。

获取访问令牌

使用你的 APP Key 和 APP Secret，通过 Client Credentials 授权流程获取 access_token。
完整的参数说明及响应结构请参阅 /oauth2/token 接口规范。

curl --location 'https://x-api.shipsaving.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic U1NfTElWRV9kWG8zT3k5V0VxS1k0ZnB1Q09Nd0N6Q19QanBJRHd1SnNXQ2Y6R1hBeFFkUUZHSWR5TElFVnhPTVY1amc1TjRma19YX3R0Nzc3' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=API'

调用请求

在调用其他 ShipSaving API 接口时，请将认证类型（Auth Type）设置为 Bearer Token，并在 Token 字段中提供你的 access_token。
只要该访问令牌仍然有效，即可访问对应的受保护资源。

注意事项

令牌有效期：访问令牌的有效期为30分钟。使用已过期的令牌将返回 401 Unauthorized。
每个 appKey 仅允许一个有效令牌：在任意时间点，同一个 appKey 仅最近一次签发的访问令牌有效。若在短时间内连续请求多个令牌，先前的令牌将被吊销，仅最后一个令牌可用。
密钥安全管理：请勿在客户端代码中硬编码 appSecret。应将其安全存储（例如使用服务端密钥管理系统），以避免泄露风险。