应用程序接口迁移指南
从版本 1 迁移到版本 2
本《API 迁移指南》旨在为您提供更新当前集成以与新的高翼 API v2 兼容所需的具体细节。
📌 重要！
本迁移指南记录了高翼 API v2 与高翼 API v1 之间的差异，后者将于 2024 年 6 月退役。强烈建议用户尽快迁移。请参考高翼 API v2 文档，该文档已移至 Swagger，网址为 https://docs-dev.goricompany.com/api/documentation.
将应用程序接口验证更新为 OAuth 2.0
Gori为所有 API 实施了 OAuth 2.0 安全模型，以提高安全性、减少欺诈并增强 API 功能。作为新安全流程的一部分，Gori将淘汰现有的 API 密钥验证。猩便利将不再分发 API 密钥，2024 年 5 月 31 日之后与猩便利进行的所有 API 交易都将要求客户实施 OAuth 2.0 安全模型，即在每次 API 请求中发送一个不记名令牌。请确保您的集成已尽快迁移到 OAuth 2.0，以防止未来服务中断。
有关如何使用 OAUTH 2.0 进行身份验证的详细说明，请参阅本指南末尾的 API 身份验证。
将端点 URL 从 v1 更新为 v2
高翼 支持两种不同的 API 环境，您可以向其发送 API 请求。不同的环境允许您在将应用程序运行到生产环境之前测试对高翼 API 的调用。您可以使用 API 的基本 URL 来确定要针对的特定环境。
下表列出了高翼 API v2 可用的暂存和生产基础 URL。
| 环境 | 网址 |
|---|---|
|
分期 |
https://staging.api.goricompany.com/v2 |
|
生产 |
https://api.goricompany.com/v2 |
GET https://api.goricompany.com/v1/shipments
对于版本 2，将 URL 更新为以下内容：GET https://api.goricompany.com/v2/shipments
进行必要的更改
除了实施新的 OAUTH 2.0 身份验证方法外，我们还对应用程序接口进行了几处重大修改，详情如下。
📌注！
您只需根据现有高翼 API 的使用情况进行必要的更改即可。如果您要向美国领土、军事地址、外交地址或全球范围发货，则需要在创建发货请求（）中加入新的 HS 税则号和原产国属性。https://docs-dev.goricompany.com/api/documentation#/Shipments/createShipment).
1.新的 OAUTH 2.0 POST /auth/token 端点。有关如何使用新的 OAUTH 2.0 访问令牌端点进行身份验证的详细说明，请参阅以下 "API 身份验证 "部分。
2.POST /shipments 端点新增了名为 ship_date 的属性。USPS 和 FedEx 统一费率货件必须指定该属性。如果未指定，则默认使用货件创建日期。
📌 重要！
指定的日期必须在创建货件日期后 7 天内。如果指定的日期小于货运日期，将返回错误信息，并且不会创建货运。
3.GET /shipments/rates、POST /shipments 和 POST /return_shipments 端点的 packageType 属性已更改为 package_type。
4.如果请求中没有提供 zipcode 属性的值，那么响应中返回的值将为空，而不是空字符串。
5.HS 税则号必须以世界海关组织制定的商品名称及编码协调制度为基础。有关更多信息，请参阅 https://hts.usitc.gov/current.要指定 HS 税则号，请在创建货运请求中包含 hs_tariff_number 属性和 HTS 代码（6 至 14 个字符），如下所示：
{"shipment": {"customs": {"items": [ {"hs_tariff_number": "3926.20"} ] } } }
6.原产国是 ISO 规定的 2 位字母国家代码，是国际地址的必填项。请参阅： https://www.iso.org/obp/ui/#search获取完整的代码列表。要指定原产国，请在创建货件请求中包含 country_of_origin 属性和 ISO Alpha-2 代码（2 个字符），如下所示：
{ "shipment": {"customs": {"items": [ {"country_of_origin" : "US"} ] } } }
7.错误响应现在包含一个名为 "log_id "的新属性。
8.POST /shipments 端点和 POST /return_shipments 端点的 reference1 和 reference2 属性已更改为 reference_1 和 reference_2。
测试
获取帮助
应用程序接口认证
高翼 为每个客户端创建一组唯一的暂存和生产 OAuth 2.0 凭据，称为客户端 ID 和客户端密文。在每个身份验证请求的正文中传递这些凭据，即可从 OAuth 2.0 服务器获取一个新的访问令牌。然后，在后续请求中使用访问令牌作为 API 请求的身份验证。下面将逐一介绍这些步骤。
获取 OAuth 2.0 凭据
📌 重要！
切勿在公共场合使用或披露您的证书。
获取访问令牌
有了一套有效的凭据后（请参阅获取 OAuth 2.0 凭据），就可以使用以下步骤构建并发出验证请求：
1.指定授权 API 端点：
https://staging.api.goricompany.com/auth/token
2.添加 Content-Type 标头，将媒体类型设置为 JSON：
Content-Type: 应用程序/json
3.最后，使用 curl 等工具提出 API 请求：
curl -location'https://staging.api.goricompany.com/v2/auth/token/'
-header'Content-Type:application/json'（内容类型：应用程序/json
-数据 '{
"client_id": "{your-client-id}",
"client_secret": "{your-client-secret}",
"grant_type"（授予类型）："客户凭据"
}'
4.一旦发出 API 请求，OAuth 2.0 服务器就会响应新的令牌，如下例所示：
'{
"token_type"（令牌类型）："承载器"、
"过期失效"：43200,
"access_token": "{access_token}"
}'
📌 重要！
访问令牌的有效期为 12 小时。我们建议在当前访问令牌过期前从授权 API 端点获取新的访问令牌。
有了有效的访问令牌后，就可以向受保护的资源发出 API 请求，如下节所述。
提出请求
要访问受保护的资源，您需要使用 OAuth 2.0 服务器在客户端身份验证过程中返回的访问令牌（获取访问令牌）。在使用承载 HTTP 身份验证方案（称为承载身份验证）的后续 API 请求中，访问令牌将被用作 "承载令牌"。客户端向受保护资源发出请求时，必须在 HTTP 授权标头中发送该承载令牌。以下是授权头和承载令牌（访问令牌）的格式：
Authorization: Bearer {access_token}
The way to do this using a tool like curl is to use the –header flag, which is used to include an extra header in the request when sending HTTP requests to a server. In our case, –header "Authorization: Bearer {access_token}". For example, to authenticate and retrieve all shipments execute:
curl --location'https://staging.api.goricompany.com/v2/shipments?
page_size=100&page=1&id_after=0&reference_1=12345&created_at_before=2021-07-27'\
--header 'Accept: application/json'\
‐‐header 'Authorization: Bearer {access_token)'
Requests with no Authorization header will be rejected with a 401 status code. If this occurs, you need to get a new access token and try the request again
API 迁移指南
从 v1 迁移到 v2
本 API 迁移指南旨在为您提供有关更新当前集成以使⽤新的 Gori API v2 所需执⾏的操作的具体详细信息。
📌 重要的！
本迁移指南记录了 Gori API v2 和将于 2024 年 6 月停⽤的 Gori API v1 之间的差异。
强烈建议⽤⼾尽快迁移。
请参阅已移至 Swagger 的 Gori API v2 ⽂档（⽹址为 https://docs‑dev.goricampany.com/api/documentation ）。
将 API 身份验证更新为 OAuth 2.0
有关如何使⽤ OAUTH 2.0 进⾏身份验证的详细说明，请参阅本指南末尾的 API 身份验证。
将端点 URL 从 v1 更新为 v2
Gori 支持两种不同的 API 环境，您可以向其中发出 API 请求。不同的环境允许您在将应⽤程序转移到生产环境之前测试对 Gori API 的调⽤。您可以使⽤ API 的基 本 URL 来定位要定位的特定环境。
| 环境 | ⽹址 |
|---|---|
|
分期 |
https://api-staging.goricompany.com/v2 |
|
生产 |
https://api.goricompany.com/v2 |
获取 https://api.goricampany.com/v1/shipments
对于 v2，将 URL 更新为以下内容：获取 https://api.goricompany.com/v2/shipments
进⾏必要的更改
除了实施新的 OAUTH 2.0 身份验证方法外，我们还对 API 进行了多项重大更改，如下所述。
📌 注意:
您只需进行与您目前使用的 Gori API 相关的必要更改。如果您要将货物运送到美国领土、军事地址、外交地址或国际地址，则需要开始在创建货件请求 https://docs-dev.goricampany.com/api/documentation#/Shipments/createShipment 中包含新的 HS 关税编号和原产国属性。
1. 新的 OAUTH 2.0 POST /auth/token 端点。请参阅以下 API 身份验证部分，了解有关如何使用新的 OAUTH 2.0 访问令牌端点进行身份验证的详细说明。
2. 一个名为 ship_date 的新属性已添加到 POST /shipments 端点。必须为 USPS 和 FedEx 单一费率货件指定此属性。如果未指定，则将使用货件创建日期作为默认值。
📌 重要的！
指定的日期不得晚于货件创建日期后的 7 天。如果指定的日期早于货件日期，则会返回错误，并且不会创建货件。
3. GET /shipments/rates 的 packageType 属性， POST /shipments 和 POST /return_shipments 端点已更改为 package_type。
4. 如果请求中没有提供 zipcode 属性的值，则响应中返回的值将为 null，而不是空字符串。
5. HS 关税编号必须基于世界海关组织制定的《协调商品描述及编码系统》。有关更多信息，请参阅：https://hts.usitc.gov/current。要指定 HS 关税编号，请在创建货件请求中包含 hs_tariff_number 属性和 HTS 代码（6 到 14 个字符），如下所示：
{"shipment": {"customs": {"items": [ {"hs_tariff_number": "3926.20"} ] } } }
6.原产国是 ISO 定义的 2 位字母国家代码，是国际地址所必需的。请参阅：https://www.iso.org/obp/ui/#search获取完整的代码列表。要指定原产国，请在创建货件请求中包含 country_of_origin 属性和 ISO Alpha-2 代码（2 个字符），如下所示：
{ "shipment": {"customs": {"items": [ {"country_of_origin ": "US"} ] } } }
7.错误响应现在包含一个名为 "log_id "的新属性。
8.POST /shipments 端点和 POST /return_shipments 端点的 reference1 和 reference2 属性已更改为 reference_1 和 reference_2。
测试
寻求帮助
API 身份验证
高翼 为每个客⼾端创建一组唯一的暂存和生产 OAuth 2.0 凭据，称为客⼾端 ID 和客⼾端密钥。您可以在每个身份验证请求的正⽂中传递这些凭据，以从 OAuth 2.0 服务器检 索新的访问令牌。然后，您可以在后续请求中使⽤访问令牌作为 API 请求的身份验证。以下部分描述了每个步骤。
获取 OAuth 2.0 凭据
重要的！ 📌重要的！ 📌重要的
您绝不应该在公开场合使⽤或透露您的凭证。
获取访问令牌
1.指定授权 API 端点：
https://api.goricompany.com/auth/token
2.添加 Content-Type 标头以将媒体类型设置为 JSON：Content-Type: 应用程序/json
3.最后，使⽤ curl 等⼯具发出 API 请求：curl -location 'https://api-staging.goricompany.com/v2/auth/token/'
-header'Content-Type:application/json'（内容类型：应用程序/json
-数据 '{
"client_id": "{你的客⼾端id}",
"client_secret": "{你的客⼾端秘密}",
"grant_type"（授予类型）："客户凭据"
}'
4.API 发送请求后，OAuth 2.0 服务器应使⽤新令牌进⾏响应，如下例所示： 4.'{
"token_type"（令牌类型）："承载器"、
"过期失效"：43200,
"access_token": "{access_token}"
}'
📌重要的！
访问令牌的有效期为 12 小时。我们建议在当前访问令牌过期之前从授权 API 端点获取新的访问令牌。
拥有有效的访问令牌后，您可以向受保护的资源发出 API 请求，如下节所述。
发出请求
要访问受保护的资源，您需要在客⼾端身份验证（获取访问令牌）期间使⽤从 OAuth 2.0 服务器返回的访问令牌。访问令牌将在使⽤
Bearer HTTP 身份验证方案（称为 Bearer 身份验证）的后续 API 请求中⽤作 "承载令牌"。客⼾端在向受保护的资源发出请求时必须在
HTTP 授权标头中发送此承载令牌。以下显示了授权标头以及承载令牌（访问令牌）的格式：。
授权：持有者{access_token}。
使⽤ curl 等⼯具执⾏此操作的方法是使⽤ ‒header ag，它⽤于在向服务器发送 HTTP 请求时在请求中包含额外的标头。在我们的例⼦中，‒header
“Authorization: Bearer {access_token}”。例如，要验证和检索所有货件，请执⾏：
Curl -location https://api-staging.goricompany.com/v2/shipments?
page_size=100&page=1&id_after=0&reference_1=12345&created_at_before=2021-07-27'\
--header 接受：application/json\
‐‐header 授权：承载 {access_token)
没有授权标头的请求将被拒绝，并显示 401 状态代码。如果发生这种情况，您需要获取新的访问令牌并再次尝试请求
