Shipto

一、使用指南

  • 请确保您已成功开通API账号并获得 API地址 和 accessKey；
  • 每个代理商的API地址是独立的，开发前务必向您的销售顾问索取API地址和沙箱环境的 accessKey;
  • 沙箱测试无数量限制，除了非正式运单号外，所有行为和正式环境一致；
  • 沙箱测试完成后可以向您的销售顾问索取一定数量的消费额度，具体以沟通结果为准；
  • 方便开发，所有请求使用POST

二、请求说明

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    --data '{}' \
    http://API地址/接口名称

响应结果

{
  "code": 200,
  "data": {},
  "message": "success"
}

2.1 响应状态码

  • 标准的 HTTP 状态码，描述请求的情况。
名称描述
200请求得到正常处理，具体的处理结果需要检查返回数据。
401请求未经授权、密钥错误、访问 IP 不在白名单内或者账号被禁用。
404请求的 URL 地址错误。
422数据验证失败。
429访问频率超出限制。
500服务器错误。
503服务临时不可用。

2.2 公共错误代码

  • 接口返回不成功时对应的标识，通过在响应报文的 data 节点。
名称描述
200成功。(get 状态码)
201成功。(post、put 状态码)
-11001assessKey 无效或无权限访问。
-1801你尚未开设资金账户，请联系销售顾问。
-1802你没有可支付的余额。
-1803你的余额不足以支付当前交易。
-601无效的产品或服务。
-602超出配送区域。
-603无可用商户号。
-604匹配模板失败。
-605生成序列号失败。
-606运单号添加失败。
-607获取运单号失败。

三、下单 (单笔)

  • POST http://API地址/api/order/add
  • 该接口每次提交一个订单
  • 为保证服务质量，该接口限速限流，请保证访问间隔超过 200 毫秒，建议使用队列。
  • 因为关联第三方服务，提交订单后无法实时获取到订单信息，建议使用 webhook，我们会在订单处理成功后把结果推送到你指定的url，请参阅管理后台-webhook 获取通过获取订单信息获取( 不推荐)。
  • 约定：请求字段全为小驼峰，响应所有字段均为下划线

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    --data '{
        "isTest": true,
        "merchant": 'zhangsan',
        "orderId": "U1986",
        "productId": "usps_priority",
        "stockKeepUnit": "SKU668",
        "freightName": "Google Mobile",
        "freightPrice": 580,
        "freightCount": 1,
        "freightWeight": 1,
        "freightLength": 5,
        "freightWidth": 5,
        "freightHeight": 5,
        "fromName": "David",
        "fromPhone": "2134421463",
        "fromCompany": "David Company",
        "fromStreet": "1339 Cardigan Bay Cir Spring",
        "fromStreet2": "Cir Spring",
        "fromCity": "Spring",
        "fromState": "TX",
        "fromPostalCode": "77379",
        "toName": "Paul Johnson",
        "toCompany": "Paul Johnson Co.",
        "toPhone": "8134421463",
        "toCity": "Hephzibah",
        "toState": "GA",
        "toStreet": "2925 Old Tobacco Rd",
        "toStreet2": "Unit B",
        "toPostalCode": "30815",
        "reference1": "test",
        "reference2": "Thank you"
    }' \
    http://API地址/api/order/add

3.1 请求参数说明

--data 字段说明

名称
是否必选
默认值
类型
描述
isTest否falseboolean开发测试期间请开启此项
merchant否--字符串商户名（大部分ERP系统接入多个上家，传入上家标识方便订单管理）
permitNo否--字符串许可证（不熟悉该字段不要设置）
orderId是--字符串你的订单号（对应店铺/ERP系统订单号，避免重复下单）
productId是--字符串产品类型，参考 获取产品列表Api
stockKeepUnit否--字符串SKU
lengthUnit否in字符串长度单位
weightUnit否lb字符串质量单位
freightName否--字符串货品名称
freightPrice否1数值货品价值 (单位：$)
freightCount否1数值货品数量
freightWeight是--数值货品重量（默认为塝）
freightLengthUPS 必填--数值货品长度（默认为英寸）
freightWidthUPS 必填--数值货品宽度（默认为英寸）
freightHeightUPS 必填--数值货品高度（默认为英寸）
fromName是--字符串发货人名字
fromPhone否--字符串发货人电话
fromCompany否--字符串发货人公司
fromStreet是--字符串发货街道地址
fromStreet2否--字符串发货街道地址2
fromCity是--字符串发货城市
fromState是--字符串发货州名
fromCountry否USA字符串发货国家 可选: (USA、CAN)
fromPostalCode是--字符串发货人邮编
toName是--字符串收货人名称
toCompany否--字符串收货人公司
toPhone否--字符串收货人电话
toStreet是--字符串收货地址
toStreet2否--字符串收货地址2
toCity是--字符串收货城市
toState是--字符串收货州名
toPostalCode是--字符串收货人邮编
toCountry否USA字符串收货国家 可选: (USA、CAN)
reference1否--字符串备注一
reference2否--字符串备注二

响应示例

  • code 为200 时返回的完整订单反馈结果
{
  "data": {
    "order_id": "YH24111731836371933",
    "order_no": "YH24111731836371933",
    "inner_id": "TEST20241117173906210271",
    "order_status": "Created",
    "payment_amount": 0.8,
    "carrier": "USPS",
    "tracking_number": "9300110597202911739209",
    "full_tracking_number": "420442569300110597202911739209",
    "label_url": "http://xxx/pdf/label/YH24111731836371933"
  },
  "code": 200,
  "message": "success"
}
  • code 大于 1000 时返回的订单反馈结果：(需先保存 orderNo 之后通过订单信息接口获取完整订单信息)
{
  "data": {
    "orderNo": "DEV24111731854550027",
    "orderId": "TEST20241117221629926661"
  },
  "code": 3000,
  "message": "资源调配中"
}

3.2 响应结果说明

  • 可通过错误状态码来判断订单创建成功后是否实时返回了订单结果：
  • data.code = 200 订单创建成功，并返回订单结果！
  • data.code 大于 200 并小于 1000 时， 订单创建失败，需重新提交，失败原因请参考错误代码。
  • data.code 大于 1000 时， 订单创建成功，但未能实时返回结果，需通过 webhook 接收或通过 获取订单信息 获取。
名称类型描述
code数值错误代码
-11000错误代码系统异常，详情参考错误信息
-422错误代码输入验证失败，具体请参考返回的错误消息
-3000错误代码加入拉单队列失败(可能是订单未成功创建)
-607错误代码创建订单失败
-200成功代码成功
data订单对象创建订单返回的结果
-inner_id字符串你的订单号 (传入的OrderId)字段
-order_id数值订单ID (通过订单ID查询订单信息)
-order_no字符串订单号 (和订单ID等效使用)
-order_status字符串订单状态 参考 订单状态说明
-carrier字符串承运商
-tracking_number字符串运单号
-full_tracking_number字符串完整运单号
-label_url文件网址PDF标签下载地址(Blob 文件流下载)

3.3 订单状态说明

状态说明
Created创建成功，未支付
Gain向第三方获取面单中
Sync第三方同步订单中
Paid支付成功并获取到面单，等待打印出库
Printed已打单或出库（通过仓库助手成功打单后才有该状态）
Finish已完成（物流状态查询结果为已签收）
Issue问题订单 （物流状态查询结果为异常）
Cancel已取消

四、获取单条订单信息

  • POST http://API地址/api/order/info
  • 提交订单后没有实时返回下单的结果，可以通过该接口获取订单信息。

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    --data '订单ID'
    http://API地址/api/order/info

响应示例


{
  "data": {
    "order_id": "YH24111731836371933",
    "order_no": "YH24111731836371933",
    "inner_id": "TEST20241117173906210271",
    "order_status": "Created",
    "payment_amount": 0.8,
    "carrier": "USPS",
    "tracking_number": "9300110597202911739209",
    "full_tracking_number": "420442569300110597202911739209",
    "label_url": "http://xxx/pdf/label/YH24111731836371933"
  },
  "code": 200,
  "message": "success"
}

4.1 响应结果说明

名称类型描述
code数值错误代码
-11000错误代码系统异常，详情参考错误信息
-422-607错误代码输入验证失败，具体请参考返回的错误消息
-608错误代码找不到订单信息
-200成功代码成功
data订单对象订单对象
-inner_id字符串你的订单号 (传入的OrderId)字段
-order_id数值订单ID (通过该ID查询订单信息)
-order_no字符串订单号 (和订单ID等效使用)
-order_status字符串订单状态 参考 订单状态说明
-carrier字符串承运商
-tracking_number字符串运单号
-full_tracking_number字符串完整运单号
-label_url文件网址PDF标签下载地址(Blob 文件流下载)

五、获取多条订单信息

  • POST http://xxx/api/order/list

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    --data ['订单ID1', '订单ID2']
    http://API地址/api/order/list

响应示例

{
  "data": [
    {
      "order_id": "YH24111731836365706",
      "order_no": "YH24111731836365706",
      "inner_id": "TEST20241117173968999821",
      "order_status": "Success",
      "payment_amount": 0.5,
      "carrier": "USPS",
      "tracking_number": "9300110597203011739199",
      "full_tracking_number": "420442569300110597203011739199",
      "label_url": "http://xxx/label/YH24111731836365706"
    },
    {
      "order_id": "YH24111731836371933",
      "order_no": "YH24111731836371933",
      "inner_id": "TEST20241117173906210271",
      "order_status": "Success",
      "payment_amount": 0.5,
      "carrier": "USPS",
      "tracking_number": "9300110597202911739209",
      "full_tracking_number": "420442569300110597202911739209",
      "label_url": "http://xxx/label/YH24111731836371933"
    }
  ],
  "code": 200,
  "message": "success"
}

5.1 响应结果说明

名称类型描述
code数值错误代码
-11000错误代码系统异常，详情参考错误信息
-500101错误代码输入验证失败，具体请参考返回的错误消息
-500004错误代码找不到订单信息
-200成功代码成功
data订单对象订单对象数组
-inner_id字符串你的订单号 (传入的OrderId)字段
-order_id数值订单ID (通过该ID查询订单信息)
-order_no字符串订单号 (和订单ID等效使用)
-order_status字符串订单状态 参考 订单状态说明
-carrier字符串承运商
-tracking_number字符串运单号
-full_tracking_number字符串完整运单号
-label_url文件网址PDF标签下载地址(Blob 文件流下载)

六、分页获取订单信息

  • POST http://API地址/api/order/page

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    --data '{current: 1, pageSize: 10 }'
    http://API地址/api/order/page

6.1 请求参数说明

--data 字段说明

名称
是否必须
默认值
类型
描述
current否1数值页码
pageSize否10数值每页返回条目数 （最多每页40条）

响应示例

{
  "data": {
    "list": [
      {
        "inner_id": "N88805300925341837226",
        "order_id": 133468,
        "order_no": "64b64d1355a8fd7492922557",
        "order_status": "Paid",
        "payment_amount": 0.3,
        "carrier": "USPS",
        "tracking_number": "92001584684836220102687341",
        "full_tracking_number": "4204425692001584684836220102687341",
        "label_url": "http://API地址/pdf/label/64b64d1355a8fd7492922557"
      },
      {
        "inner_id": "N888053009253241822",
        "order_id": 133460,
        "order_no": "64b5bbb455a8fd74929206bc",
        "order_status": "Paid",
        "payment_amount": 0.3,
        "carrier": "USPS",
        "tracking_number": "92001671924647990520404850",
        "full_tracking_number": "4204425692001671924647990520404850",
        "label_url": "http://API地址/pdf/label/64b5bbb455a8fd74929206bc"
      },
      {
        "inner_id": "N888053009253241816",
        "order_id": 133458,
        "order_no": "64b5b3ed55a8fd749292048b",
        "order_status": "Paid",
        "payment_amount": 0.3,
        "carrier": "USPS",
        "tracking_number": "92001425956713785524031562",
        "full_tracking_number": "4204425692001425956713785524031562",
        "label_url": "http://API地址/pdf/label/64b5b3ed55a8fd749292048b"
      }
    ],
    "pagination": {
      "pageSize": 20,
      "current": 1,
      "total": 3
    }
  },
  "code": 200,
  "message": "success"
}

6.2 响应结果说明

名称类型描述
code数值错误代码
-11000错误代码系统异常，详情参考错误信息
-500101错误代码输入验证失败，具体请参考返回的错误消息
-500004错误代码找不到订单信息
-200成功代码成功
data订单对象订单对象数组
-list订单对象订单对象数组
--inner_id字符串你的订单号 (传入的OrderId)字段
--order_id数值订单ID (通过该ID查询订单信息)
--order_no字符串订单号 (和订单ID等效使用)
--order_status字符串订单状态 参考 订单状态说明
--carrier字符串承运商
--tracking_number字符串运单号
--full_tracking_number字符串完整运单号
--label_url文件网址PDF标签下载地址(Blob 文件流下载)
-pagination分页对象
--pageSize数值每页条数
--current数值当前页码
--total数值条目总数

七、获取产品列表

  • POST http://API地址/api/product

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    http://API地址/api/product

响应示例

{
  "code": 200,
  "data": [
    {
      "ProductId": "usps_first_class",
      "Carrier": "USPS",
      "Name": "USPS First-Class Mail®",
      "SalePrice": 1.50
    },
    {
      "ProductId": "usps_priority",
      "Carrier": "USPS",
      "Name": "USPS Priority Mail®",
      "SalePrice": 2.00
    }
  ]
}

7.1 响应结果说明

名称类型描述
code数值错误代码 (900004 找不到产品)
data数组产品对象数组
-product_id字符串产品ID
-carrier字符串承运商
-name字符串产品报价
-sale_price数值产品价格

八、查询余额

  • POST http://API地址/api/balance

请求示例

curl -X POST \
    --header 'accessKey:密钥' \
    --header 'Content-Type:application/json' \
    http://API地址/api/balance

响应示例

{
  "code": 0,
  "data": 60.00,
  "message": "success"
}

8.1 响应结果说明

名称类型描述
code数值错误代码
data数值余额
Last Updated:
Contributors: leeson