{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/zh-Hans/v2/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img","admonition"]},"type":"markdown"},"seo":{"title":"认证"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"认证","__idx":0},"children":["认证"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipSaving 新版 API 采用 OAuth 2.1 框架，相比传统的单一 API Key 认证方式，提供了更高的安全性、标准化的授权机制以及更强的可扩展性。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"该 API 实现了 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Credentials Grant"]}," 授权流程，使后端服务能够使用自身凭证安全地获取访问令牌（Access Token），并与受保护的资源进行交互。"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"主要安全特性","__idx":1},"children":["主要安全特性"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["双因素认证"]},"：结合 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},"（",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]},"）与 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_secret"]},"（",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_secret"]},"）进行双重校验。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["短时有效访问令牌"]},"：访问令牌默认有效期为 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["30分钟"]},"，可降低令牌泄露带来的风险。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["基于 Scope 的访问控制"]},"：API 访问权限依据 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope"]}," 参数进行限制与控制。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["令牌吊销机制"]},"：提供访问令牌吊销接口，用于降低潜在的安全暴露风险。"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"测试模式与正式模式","__idx":2},"children":["测试模式与正式模式"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"类型"},"children":["类型"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"使用场景"},"children":["使用场景"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"注意事项"},"children":["注意事项"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["测试模式"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["在测试和构建 ShipSaving 集成过程中，请使用测试模式及对应的测试密钥。在测试模式下，你可以使用 ShipSaving 提供的所有服务，例如查询运费和创建示例面单，且不会产生任何费用。"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["测试模式下购买的面单均为",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["示例面单"]},"，不可用于实际发货。测试模式下查询的运费可能与正式模式存在差异。测试数据与正式账户数据完全隔离。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["正式模式"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["当你的集成准备好投入生产环境时，请使用正式模式及正式访问令牌。在正式模式下，你可以查询真实运费并购买可用于发货的正式面单。"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["正式模式下购买的面单",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["可用于实际运输"]},"，并会生成真实的交易记录。购买面单将从你的账户中扣费。"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"认证流程","__idx":3},"children":["认证流程"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"创建你的-shipsaving-账户","__idx":4},"children":["创建你的 ShipSaving 账户"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["注册一个 ShipSaving API Portal 账户。"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["完成注册表单并验证你的邮箱地址。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["在完成邮箱验证前你仍可登录账户，但无法创建 API Key。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["邮箱验证完成后，你即可管理密钥并生成 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["测试（test）"]}," 或 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["正式（live）"]}," API Key。"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"生成-api-key","__idx":5},"children":["生成 API Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["登录 ShipSaving API Portal，并按照页面提示步骤（如下方 GIF 所示）创建你的 API Key。"]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/create_new_key.819e629eda4b042cf5f02034b0c1139eb88a2608c3a3b398724b495c330d6411.c5aff763.gif","alt":"Image description","framed":false,"withLightbox":true,"width":"","height":""},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"WARNING"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API Key 一旦生成，请务必妥善保管——该密钥拥有你账户的完整访问权限。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"API Key 仅在创建时显示一次；若窗口关闭，将无法再次查看或找回。"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"获取访问令牌","__idx":6},"children":["获取访问令牌"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["使用你的 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["APP Key"]}," 和 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["APP Secret"]},"，通过 Client Credentials 授权流程获取 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},"。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"完整的参数说明及响应结构请参阅 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," 接口规范。"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"curl","header":{"controls":{"copy":{}}},"source":"curl --location 'https://x-api.shipsaving.com/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--header 'Authorization: Basic U1NfTElWRV9kWG8zT3k5V0VxS1k0ZnB1Q09Nd0N6Q19QanBJRHd1SnNXQ2Y6R1hBeFFkUUZHSWR5TElFVnhPTVY1amc1TjRma19YX3R0Nzc3' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'scope=API'\n","lang":"curl"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"调用请求","__idx":7},"children":["调用请求"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["在调用其他 ShipSaving API 接口时，请将认证类型（Auth Type）设置为 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bearer Token"]},"，并在 Token 字段中提供你的 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]},"。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"只要该访问令牌仍然有效，即可访问对应的受保护资源。"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"注意事项"},"children":[{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["令牌有效期"]},"：访问令牌的有效期为30分钟。使用已过期的令牌将返回 401 Unauthorized。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["每个 appKey 仅允许一个有效令牌"]},"：在任意时间点，同一个 appKey 仅最近一次签发的访问令牌有效。若在短时间内连续请求多个令牌，先前的令牌将被吊销，仅最后一个令牌可用。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["密钥安全管理"]},"：请勿在客户端代码中硬编码 appSecret。应将其安全存储（例如使用服务端密钥管理系统），以避免泄露风险。"]}]}]}]},"headings":[{"value":"认证","id":"认证","depth":2},{"value":"主要安全特性","id":"主要安全特性","depth":3},{"value":"测试模式与正式模式","id":"测试模式与正式模式","depth":3},{"value":"认证流程","id":"认证流程","depth":3},{"value":"创建你的 ShipSaving 账户","id":"创建你的-shipsaving-账户","depth":4},{"value":"生成 API Key","id":"生成-api-key","depth":4},{"value":"获取访问令牌","id":"获取访问令牌","depth":4},{"value":"调用请求","id":"调用请求","depth":4}],"frontmatter":{"seo":{"title":"认证"}},"lastModified":"2026-08-26T18:17:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/zh-hans/v2/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}