入门指南

ShipSage 允许您使用 RESTful API 构建应用程序和其他集成。借助这些 API，您可以创建在仓库运营的每个阶段提供功能的应用程序，包括 店铺、仓库、产品、库存、订单、包裹、发货计划、转运、增值服务、退货、文件上传 。

沙盒 & 生产

BASE URL

名称	地址
`沙盒`	`https://app-sandbox.shipsage.com`
`生产`	`https://api.shipsage.com`

请注意，生产环境中的所有数据均为真实数据。如果您需要在生产环境中进行测试，请联系 ShipSage IT，并确保测试后清理所有测试数据。

获取访问令牌方法 :

方法 1. 集成电商平台，例如：亚马逊、Shopify、Wayfair、沃尔玛等；

方法 2. 集成第三方平台，例如ERP。

方法 1:

步骤1：联系我们的客服获取授权信息

例子

名称	值
`client_id`	`1780`
`client_secret`	`SyGIQzIvXYiLAL0HGeq49vJF5babOqPiQZLWxvxt`
`username`	`demo4173.vip`
`password`	`demo4173.vip`

步骤2：使用认证信息请求访问令牌

端点 `POST /oauth/token`

请求

名称	值
`grant_type`	`password`
`client_id`	`1780`
`client_secret`	`SyGIQzIvXYiLAL0HGeq49vJF5babOqPiQZLWxvxt`
`username`	`demo4173.vip`
`password`	`demo4173.vip`

名称	值
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

示例

方法 2:

步骤1: 联系我们的客服获取授权信息

您应该向我们的客户服务提供一些信息

redirect_uri: 授权成功后自动跳转到该uri，通过该uri可以拿到获取access token所需的code

我们的客服将为您提供启动授权流程所需的信息

client_id: 整数类型，例如 100

client_secret: 字符类型，例如 'jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs'

步骤2：联系您的客户访问此url，授权给您，完成此步骤后，您可以访问重定向uri中的code，并且您应该存储此code以获取access_token

端点 `BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=`

名称	值
`client_id`	`our customer service provided`
`scope`	`leave this field empty`
`state`	`this field is optional, which if input will remain in the redirect uri after the authorization.you can also leave this field empty`

步骤3：使用授权信息请求访问令牌

端点 `POST /oauth/token`

请求

名称	值
`grant_type`	`authorization_code`
`client_id`	`1502`
`client_secret`	`jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs`
`code`
`redirect_uri`

名称	值
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

示例

使用 refresh_token 请求访问令牌

端点 `POST /oauth/token`

请求

名称	值
`grant_type`	`refresh_token`
`client_id`	`1502`
`refresh_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`client_secret`	`jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs`

名称	值
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

示例

oauth-use refresh token-request-token.jpg

在头部 “Authorization: Bearer xxxx.access-token.xxxx”中设置访问令牌以请求 API

端点 `GET /api/developer/examples`

头部

名称	值
`Authorization`	`Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...`

Name	Value
`errcode`	`0`
`errmsg`	`ok`
`data`	`[...]`

示例

“next_token”的含义

next_token 是用于获取下一页50条数据的加密字符串，ShipSage API 最多返回50条数据，如果超过50条，则在最后一条数据后会有一个 next_token。将此 next_token 填入请求参数中，再次调用此 API 即可返回下一页50条数据，并返回下一页的 next_token，以此类推。

错误码

ShipSage API 的所有接口都返回统一的 JSON 响应结构。请以 errcode 作为判断请求成功或失败的唯一依据,HTTP 状态码本身不足以表达业务结果。

响应结构

无论成功或失败,响应结构保持一致:

{
    "errcode": 0,
    "errmsg":  "ok",
    "data":    { ... }
}

字段	类型	说明
`errcode`	integer	`0` 表示成功,非 `0` 均为错误。
`errmsg`	string	可读的消息文案。业务错误(`99999`)的文案可直接展示给终端用户;其他错误码返回的是通用提示。
`data`	object / array / null	响应数据。错误时为空或缺省。

错误码一览

errcode	HTTP	分类	含义
0	200	成功	请求处理成功。
99999	200	业务校验错误	预期内的业务规则校验失败——缺少必填字段、状态非法、资源不存在等。`errmsg` 描述了具体原因,可以直接展示给终端用户。
50000	200	服务端异常	预期之外的服务端异常。`errmsg` 为通用提示,并带有一个方括号包裹的 trace id 作为前缀。
40000	200	无权限	令牌有效但没有访问目标公司/资源的权限(例如 `No Company Access`、`No Access`)。
401	401	未认证	Access Token 缺失、无效或已过期。此时响应使用字段 `message`,而非 `errmsg`。
429	429	限流	请求过于频繁。`errmsg` 中包含被限流的接口路径。

响应示例

成功

{
    "errcode": 0,
    "errmsg":  "ok",
    "data": {
        "transfer_id": 108220,
        "status":      "OPEN"
    }
}

99999 — 业务校验错误

此类错误由业务规则触发,errmsg 的内容是确定且可直接展示给终端用户的。

{
    "errcode": 99999,
    "errmsg":  "shipments is required when is_dc_packing_list is 0",
    "data":    null
}

{
    "errcode": 99999,
    "errmsg":  "Transfer 108220 not found",
    "data":    null
}

{
    "errcode": 99999,
    "errmsg":  "VAS 55123 is already cancelled",
    "data":    null
}

50000 — 服务端异常

真实的异常堆栈由我方记录在服务端日志中。errmsg 是通用提示,前缀中带有 trace id——请将此 trace id 提供给 ShipSage 支持人员,便于定位完整日志。

{
    "errcode": 50000,
    "errmsg":  "[abc123def456][2026-10-16T10:12:34+00:00] Sorry, the operation failed, please contact the administrator.",
    "data":    null
}

40000 — 无权限

{
    "errcode": 40000,
    "errmsg":  "No Company Access",
    "data":    []
}

401 — 未认证

注意:此响应使用字段 message,而非 errmsg。

{
    "message": "Unauthenticated."
}

429 — 限流

{
    "errcode": 429,
    "errmsg":  "Too Many Requests api/v202608/transfers"
}

对接指引

对接方只需按以下两条规则处理响应:

errcode == 0 —— 成功,读取 data。

errcode != 0 —— 失败,按错误码分支处理:

错误码	处理方式
`99999`	业务校验错误,`errmsg` 可直接展示给终端用户,也可映射到自己的 UI 文案。不要重试——相同入参会再次失败。
`50000`	服务端异常。请从 `errmsg` 中提取开头的 `[trace_id]` 并反馈给 ShipSage 支持人员。可在短暂退避后重试,但多次失败需及时上报。
`40000`	当前令牌不具备所需权限或公司上下文不匹配。请核对凭证及请求上下文。
`401`	重新获取 Access Token 后再发起请求。
`429`	退避重试;如响应中包含 `Retry-After` header,请遵循该头部的时间。

问题上报

反馈异常时,请一并提供以下信息,便于我方快速定位:

完整的响应体(需包含 errcode、errmsg 和 trace id)。

请求的 Method、URL 及完整请求参数。

请求发生的大致时间(UTC)。

有了 trace id 我们才能检索到完整的服务端日志,进而更快排查并给出结论。

沙盒 & 生产#

BASE URL#

获取访问令牌方法 :#

方法 1:#

步骤1：联系我们的客服获取授权信息#

例子#

步骤2：使用认证信息请求访问令牌#

端点 POST /oauth/token#

请求#

返回#

示例#

方法 2:#

步骤1: 联系我们的客服获取授权信息#

步骤2：联系您的客户访问此url，授权给您，完成此步骤后，您可以访问重定向uri中的code，并且您应该存储此code以获取access_token#

端点 BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=#

步骤3：使用授权信息请求访问令牌#

端点 POST /oauth/token#

请求#

返回#

示例#

使用 refresh_token 请求访问令牌#

端点 POST /oauth/token#

请求#

返回#

示例#

在头部 “Authorization: Bearer xxxx.access-token.xxxx”中设置访问令牌以请求 API#

端点 GET /api/developer/examples#

头部#

返回#

示例#

“next_token”的含义#

错误码#

响应结构#

错误码一览#

响应示例#

成功#

99999 — 业务校验错误#

50000 — 服务端异常#

40000 — 无权限#

401 — 未认证#

429 — 限流#

对接指引#

问题上报#

沙盒 & 生产

BASE URL

获取访问令牌方法 :

方法 1:

步骤1：联系我们的客服获取授权信息

例子

步骤2：使用认证信息请求访问令牌

端点 `POST /oauth/token`

请求

返回

示例

方法 2:

步骤1: 联系我们的客服获取授权信息

步骤2：联系您的客户访问此url，授权给您，完成此步骤后，您可以访问重定向uri中的code，并且您应该存储此code以获取access_token

端点 `BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=`

步骤3：使用授权信息请求访问令牌

端点 `POST /oauth/token`

请求

返回

示例

使用 refresh_token 请求访问令牌

端点 `POST /oauth/token`

请求

返回

示例

在头部 “Authorization: Bearer xxxx.access-token.xxxx”中设置访问令牌以请求 API

端点 `GET /api/developer/examples`

头部

返回

示例

“next_token”的含义

错误码

响应结构

错误码一览

响应示例

成功

99999 — 业务校验错误

50000 — 服务端异常

40000 — 无权限

401 — 未认证

429 — 限流

对接指引

问题上报