信息接口

域名： http://api.pyl.com.cn

鉴权方式

在接口的 query string 中加入名为 access_token 的字段， token 值须向运维申请

返回格式

所有 response 都固定的格式：{code: 200, msg: "success", data: {"a":1}}

必有 code, msg, data 三个字段

code: 状态码。 200表示成功 40x表示用户端的错误， 50x表示服务端的错误.

msg: 错误信息

data: 返回的具体数据。 data 一定是一个 dict 类型。

下面所列出的接口 response 指 data 字段

商品列表：

GET /api/v1/products

查询一个供应商手中所有的商品信息, 可分页，可限制商品信息更新的时间范围

示例： http://api.pyl.com.cn/api/v1/products?page=1&length=10&access_token=aaa&updated_start=2018-06-23

参数

名称	类型	备注
page	int	(非必填)页码, 默认为1
length	int	(非必填）每页几个，默认为20
skus	string	(非必填) 返回指定的一个或者多个SKU数据，若有多个SKU之间用逗号隔开
category_id	int	(非必填) 按分类id进行过滤
updated_start	string	格式示例： 2018-05-25
updated_end	string	格式示例： 2018-05-30

data

 
xxxxxxxxxx
{
  "pageNo": 1,
  "pageSize": 10,
  "array": [
    "parentSku": "A011",
     "productName": "adapter",
                "features": "",
                "childSkuList": [
                    {
                        "cSku": "AUW152001",
                        "doubleAttribute": [
                            {
                                "attributeKey": "颜色",
                                "attributeValue": "White"
                            },
                            {
                                "attributeKey": "尺码",
                                "attributeValue": "XXL"
                            }
                        ],
                        "length": 20,
                        "width": 12,
                        "height": 4,
                        "weight": 340,
                        "image": "https://image.pyl.com/erp/1531193296346.jpg",
                    }
                ],
                "productImages": "https://image.pyl.com/without/o_1c7b58b9a7av13sdi6c140h1m99a/winit-default.png",
                "descriptions": {
                    "en": "english desc",
                    "zh": "中文描述",
                },
                "text_descriptions":{
                    "en":"english text des",
                    "zh":"中文纯文本描述"
                }
  ]
}

分类列表

查询当前的分类列表

GET /api/v1/categories

示例 http://api.pyl.com.cn/api/v1/categories?access_token=aaa

data

每一个分类中都可能会有0个至多个子分类(children)，多层嵌套。

 
xxxxxxxxxx
{
  "code": 200,
  "msg": "success",
  "data": {
      "id": 69,
      "categoryName": "服装类",
      "children": [
        {
          "id": 70,
          "categoryName": "男装",
          "children": [
            {
              "id": 104,
              "categoryName": "短袖T恤",
              "children": []
            },
            {
              "id": 105,
              "categoryName": "背心",
              "children": [],
            }
          ]
        }
      ]
  }
}

库存列表

查询多个SKU的库存情况

GET /api/v1/stocks

示例： http://api.pyl.com.cn/api/v1/stocks?skus=75601102,720430044&access_token=aaa

参数

名称	属性	备注
skus	string	(必填)多个sku以英文逗号分隔(即 , )

data

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "amounts": [
            {
                "sku": "75601102",
                "amount": 14
            },
            {
                "sku": "720430044",
                "amount": 80
            }
        ]
    }
}

查询多个SKU的专线物流信息

GET /api/v1/shipment-special

示例： http://api.pyl.com.cn/api/v1/shipment-special?skus=75601102,720430044&access_token=aaa

参数

名称	属性	备注
skus	string	(必填)多个sku以英文逗号分隔(即 , ),最多50个

返回参数data

容器／参数	数据类型	是否必定返回	说明
result_list/	Container Array	Y	Y
result_list/sku	String	Y	商品SKU
result_list/operation_status	String	Y	操作执行结果：success：成功，fail：失败
result_list/error_message	String	N	操作失败的原因
result_list/price	Double	Y	商品价格
result_list/price_currency	String	Y	商品价格币种
result_list/weight	Integer	Y	商品重量
result_list/weight_unit	String	Y	商品重量单位
result_list/process_cost	Double	Y	手续费
result_list/process_cost_currency	String	Y	手续费币种
result_list/business_special/	Container Array	Y
result_list/business_special/country	String	Y	物品所在地
result_list/business_special/business	String	Y	邮寄方式
result_list/business_special/shipping_cost	Double	Y	运费
result_list/business_special/shipping_cost_currency	String	Y	运费币种
result_list/business_special/platform	Array	Y	适用平台

返回示例

 
xxxxxxxxxx
{
    "result_list": [
        {
            "sku": "9910933104",
            "operation_status": "success",
            "price": 25.3,
            "price_currency": "CNY",
            "weight": 231,
            "weight_unit": "g",
            "process_cost": 2.65,
            "process_cost_currency": "CNY",
            "business_special": [
                {
                    "country": "美国",
                    "business": "USPS",
                    "shipping_cost": 34.97,
                    "shipping_cost_currency": "CNY",
                    "platform": [
                        "amazon",
                        "ebay",
                        "factoryMarket_api",
                        "JOOM",
                        "Tophatter",
                        "Walmart",
                        "Wish",
                        "wish_api"
                    ]
                }
            ]
        }
    ]
}

订单接口

创建订单

批量创建多个订单，单次请求创建的订单数量不得超过100个。

POST /api/v1/orders?access_token=aaa&account_code=aaa

数据格式：application/json

请求参数

容器／参数	数据类型	是否必填	说明
order_list／	Container Array	Y	最少1个，最多100个
order_list／order_num	String	Y	订单号，经销商自定义，同一经销商不允许重复。Length <= 40
order_list／platform	String	Y	平台，需要自定义平台请联系我们。alixpress，amazon，cdiscount_api，customPlatformParent，dhgate_api，ebay，ensogo_api，factoryMarket_api，jdgj_api，joom_api，lazada_api，newegg_api，shopee_api，shopify_api，walmart_api，wish_api，yandex_api。Length <= 30
order_list／total_price	Double	Y	订单总价值。系统接收后自动四舍五入至2位小数
order_list／total_price_currency	String	Y	订单总价值币种单位，如:USD,CNY。
order_list／shipping_code	String	Y	配送方式，选择其中一个：PYL-000：PYL全球全平台智能配送，PYL-001：PYL全球智能境外直发。Length <= 7
order_list／name	String	Y	收货姓名。Length <= 64
order_list／country	String	Y	收货国家二字代码。Length <= 2
order_list／state	String	N	收货省州。Length <= 64
order_list／city	String	Y	收货城市。Length <= 64
order_list／address1	String	Y	收货地址1。Length <= 200
order_list／address2	String	N	收货地址2。Length <= 200
order_list／postal_code	String	Y	收货邮编。Length <= 32
order_list／phone1	String	Y	收货号码1。Length <= 32
order_list／phone2	String	N	收货号码2。Length <= 32
order_list／email	String	N	收货邮箱。Length <= 128
order_list／remark	String	N	备注。Length <= 1000
order_list／buyer_id	String	N	买家ID。Length <= 64
order_list／platform_seller_id	String	N	平台卖家ID。通途对应字段示例图:https://image.pyl.com/doc/order-sample.png 。Length <= 64
order_list／platform_order_id	String	N	平台订单号。Length <= 64
order_list／message	String	N	留言。Length <= 200
order_list／goods／	Container Array	Y	最少1个，最多50个
order_list／goods／sku	String	Y	商品SKU。Length <= 50
order_list／goods／quantity	Integer	Y	数量。必须为正整数
order_list／goods／url	String	Y	商品链接。Length <= 100
order_list／goods／item_id	String	N	物品号。Length <= 30
order_list／goods／transaction_id	String	N	交易号。Length <= 50

请求示例

 
xxxxxxxxxx
{
    "order_list":[
        {
            "total_price":10,
            "platform":"ebay",
            "order_num":"0000001",
            "address1":"Address1",
            "address2":"Address2",
            "city":"city",
            "state":"state",
            "country":"US",
            "email":"email",
            "name":"name",
            "phone1":"Phone1",
            "phone2":"Phone2",
            "postal_code":"PostalCode",
            "shipping_code":"PYL-001",
            "remark":"remark",
            "buyer_id":"111",
            "platform_seller_id":"asf",
            "platform_order_id":"111",
            "message":"thx",
            "goods":[
                {
                    "sku":"87442001",
                    "quantity":1,
                    "url":"http://xxxx.com",
                    "item_id":"111",
                    "transaction_id":"111"
                }
            ]
        }
    ]
}

返回参数data

容器／参数	数据类型	是否必定返回	说明
account_code	String	Y	经销商代号
result_list/	Container Array	Y
result_list/order_num	String	Y	订单号
result_list/operation_status	String	Y	操作执行结果：success：成功，fail：失败
result_list/error_message	String	N	操作失败的原因

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "account_code": "aaa",
        "result_list": [
            {
                "order_num": "0000001",
                "operation_status": "success"
            },
        ]
    }
}

查询订单发货详情

POST /api/v1/order-process?access_token=aaa&account_code=aaa

数据格式：application/json

请求参数

容器／参数	数据类型	是否必填	说明
orders／	Array String	Y	订单号，经销商自定义。Length <= 40。最少1个，最多100个。

请求示例

 
xxxxxxxxxx
{
    "orders":["001"]
}

返回参数data

容器／参数	数据类型	是否必定返回	说明
account_code	String	Y	经销商代号
result_list/	Container Array	Y
result_list/order_num	String	Y	订单号
result_list/operation_status	String	Y	操作执行结果：success：成功，fail：失败
result_list/error_message	String	N	操作失败的原因
result_list/status_code	Integer	Y	订单状态码：1：发货中，8：已发货，-2：缺货
result_list/status	String	Y	订单状态
result_list/packages/	Container Array	Cond	配货成功才有数据
result_list/packages／package_number	String	Y	包裹号
result_list/packages/ status_code	Integer	Y	包裹状态码：1：发货中，8：已发货
result_list/packages/ status	String	Y	包裹状态
result_list/packages/ tracking_number	String	Y	跟踪号
result_list/packages/ actual_weight	Integer	Y	实际重量
result_list/packages/ actual_weight_unit	String	Y	实际重量单位
result_list/packages/ actual_shipping_cost	Double	Y	实际运费
result_list/packages/ actual_shipping_cost_currency	String	Y	实际运费币种
result_list/packages/ shipping_method_name	String	Y	邮寄方式
result_list/packages/ shipping_method_code	String	Y	邮寄方式编码，对应于平台的物流编码，可用于向平台回传物流信息
result_list/packages/goods/	Container Array	Y
result_list/packages/goods/ sku	String	Y	商品sku
result_list/packages/goods/ quantity	Integer	Y	商品数量

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "account_code":"aaa",
        "result_list": [
            {
                "order_num": "001",
                "operation_status": "success",
                "status_code": 10,
                "status": "回传来源系统",
                "packages": [
                    {
                        "package_number": "P0000063014",
                        "status_code": 8,
                        "status": "已完成",
                        "tracking_number": "AAA667820600GB",
                        "actual_weight": 267,
                        "actual_weight_unit": "g",
                        "actual_shipping_cost": 15.84,
                        "actual_shipping_cost_currency": "CNY",
                        "shipping_method_name": "英专-RM 48 Large Letter",
                        "shipping_method_code": "RoyalMail",
                         "goods": [
                            {
                                "sku": "72592003",
                                "quantity": 1
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

作废订单

POST /api/v1/cancel-order?access_token=aaa&account_code=aaa

数据格式：application/json

请求参数

容器／参数	数据类型	是否必填	说明
orders／	Array String	Y	订单号，经销商自定义。Length <= 40。最少1个，最多100个。

请求示例

 
xxxxxxxxxx
{
    "orders":["001"]
}

返回参数data

容器／参数	数据类型	是否必定返回	说明
account_code	String	Y	经销商代号
result_list/	Container Array	Y
result_list/order_num	String	Y	订单号
result_list/operation_status	String	Y	操作执行结果：success：成功，fail：失败
result_list/error_message	String	N	操作失败的原因

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "account_code":"aaa",
        "result_list": [
            {
                "order_num": "001",
                "operation_status": "success"
            }
        ]
    }
}

取消作废订单

POST /api/v1/retrieve-order?access_token=aaa

数据格式：application/json

请求参数

容器／参数	数据类型	是否必填	说明
orders／	Array String	Y	订单号，经销商自定义。Length <= 40。最少1个，最多100个。

请求示例

 
xxxxxxxxxx
{
    "orders":["001"]
}

返回参数data

容器／参数	数据类型	是否必定返回	说明
account_code	String	Y	经销商代号
result_list/	Container Array	Y
result_list/order_num	String	Y	订单号
result_list/operation_status	String	Y	操作执行结果：success：成功，fail：失败
result_list/error_message	String	N	操作失败的原因

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "account_code":"aaa",
        "result_list": [
            {
                "order_num": "001",
                "operation_status": "success"
            }
        ]
    }
}

获取邮寄方式列表

GET /api/v1/shipping-method?access_token=aaa

返回参数data

容器／参数	数据类型	是否必定返回	说明
result_list/	Container Array	Y
result_list/shipping_method_name	String	Y	邮寄方式名称
result_list/shipping_method_code	String	Y	邮寄方式在分销系统中的编码，与订单详情返回的编码不一样

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "result_list": [
            {
                "shipping_method_name": "4PX-S小包平邮",
                "shipping_method_code": "CQ4PX"
            }
        ]
    }
}

获取已下架商品sku

GET /api/v1/sold-out-skus

请求参数

名称	类型	备注
page	int	(非必填)页码, 默认为1
length	int	(非必填）每页几个，默认为50

返回data

参数	数据类型	说明
page_no	int	当前页码
page_size	int	分页数量
total	int	sku总数
result_list	[]string	sku结果集

返回示例

 
xxxxxxxxxx
{
  "code": 200,
  "msg": "success",
  "data": {
    "page_no": 1,
    "page_size": 50,
    "total":0,
    "result_list": []
  }
}

获取经销商商品SKU

GET /api/v1/seller-skus?account_code=xxx

请求参数

名称	类型	备注
account_code	string	(必填) 经销商代号
page	int	(非必填)页码, 默认为1
length	int	(非必填）每页几个，默认为50

返回data

参数	数据类型	说明
seller_code	string	经销商代号
page_no	int	当前页码
page_size	int	分页数量
total	int	sku总数
result_list	[]string	sku结果集

返回示例

 
xxxxxxxxxx
{
  "code": 200,
  "msg": "success",
  "data": {
    "seller_code": "",
    "page_no": 1,
    "page_size": 50,
    "total":0,
    "result_list": []
  }
}

帐号绑定

页面链接示例: http://seller.pyl.com.cn/tongtool-bind?tname=yourname&secret=aaa&pub_token=bbb&redirect=http%3A%2F%2Fwww.baidu.com

除此页面外，下面其它接口的域名还是 `api.pyl.com.cn`

引导用户访问此页面将自己的通途帐号和PYL分销系统帐号进行绑定

参数

名称	类型	备注
tname	string	用户的第三方帐号(或第三方的唯一标识)
secret	string	使用 pub_token 生成的加密信息（加密方法见下）
pub_token	string	为避免access_token泄露，使用 access_token 生成的临时 token, 有效时间 7 天, 见下文
redirect	string	绑定完成后跳转到的链接, 见下文

进入页面后，用户选择 “已有账号，去绑定” 或 “未注册，马上绑定”。

如果是“已有账号，去绑定”，跳转到登录页，登录自己的PYL分销系统帐号即可绑定成功并跳转回 redirect

如果是“未注册，马上绑定”，跳转到一个快速注册页。用户只需要填入“用户名”，“邮箱”，“手机号”即可成功注册，系统自动生成的密码会发送会用户提供的邮箱中。

生成 pub_token

避免access_token 泄露，故使用 access_token 生成一个临时 token, 有效期 7 天。过期后请重新使用此接口申请新 pub_token

GET /api/v1/pub-token?access_token=aaa

Secret 生成方法

当前的时间戳 ts = "1529905473"

当前用户的通途帐号 tname = "name" (即页面里传入的 tname 参数)

假设当前的临时 token pub_token = 09bf0734a48be6137e771d59cbc50518

将tname和ts使用 "$" 进行拼接，得到 text = "name$1529905473"

使用 pub_token 作为密钥, 对拼接得到的 text 进行一次 AES 加密(CFB模式, PKCS5padding, 使用token的前16位作为IV)，再进行一次 BASE64 url_encoding （如果用的Base64库中只有标准式没有"url encoding", 自行将 "+" 替换为 "-", "/"替换为"_"即可）

最后得到的结果： secret = "bxBjgRBCQ2t9y60eaKpZUA==

请注意，Java 标准库中不支持16位以上的AES密钥，需要手动替换相应的jar包

redirect

填一个经过了 url_encode 的链接，在成功绑定后，页面会将绑定的用户唯一标识作为 _secret参数 加在此链接上，并自动跳转访问此链接。建议你方系统的一个页面url, 使得用户在绑定成功后可以自动跳转回你方系统；同时可以用作回调接口。

示例：假如需要跳转的链接是 http://baidu.com, 那么填入的参数是?redirect=http%3a%2f%2fbaidu.com, 最后实际跳转的链接是 http://baidu.com?_secret=xxxxx，再获取 _secret的值进行解析。

_secret 是一个AES 加密(方法同上)后的字符串，使用access_token作为密钥（请注意不是上文中的pub_token），其中包含的原文是将绑定的 tname, account_code, 和当前的时间戳 的字符串使用 "$" 进行拼接得到的,即 "tname$ts$accountCode".

account_code 是PYL的分销商用户的唯一标识，获取到后需要自行储存此值及其对应的 tname。

收到 _secret 后，请使用对应的解密函数和密钥解析得到原文，再根据时间戳判断是否过期(建议设置过期时间为1小时)

另附几组测试用例

tname	ts	pub_token	secret
tt	1530150000	09bf0734a48be6137e771d59cbc50518	dQUq1QFARmhxwq0bbJ5pUg==
aaa	153012345	09bf0734a48be6137e771d59cbc50518	YBBvwAVGRWl1wK4faZ5pUg==

查询是否已绑定用户

GET /api/v1/check-bind?access_token=xxx&tname=yyy

请求参数

容器／参数	数据类型	是否必定返回	说明
tname	String	Y	用户的第三方帐号(或第三方的唯一标识)

返回data

容器／参数	数据类型	是否必定返回	说明
tname	String	Y	用户的第三方帐号(或第三方的唯一标识)
operation_status	String	Y	success：已绑定，fail：未绑定
error_message	String	N	操作失败描述
account_code	String	N	已绑定的用户代号

返回示例

 
xxxxxxxxxx
{
    "code": 200,
    "msg": "success",
    "data": {
        "tname": "yyy",
        "operation_status": "success",
        "account_code": "qqq"
    }
}

解绑用户

POST /api/v1/unbind-user

参数

(全部必填)

名称	类型	备注
tname	string	要解绑的用户的第三方帐号(或第三方的唯一标识)
secret	string	使用 access_token 生成的加密信息，见下文
pub_token	string	为避免access_token泄露，使用 access_token 生成的临时 token, 有效时间 7 天
account	string	要解绑的PYL系统帐号
password	string	要解绑的PYL帐号密码

secret

原文格式 "tname$ts", tname即参数中的tname字段， ts即当前时间戳，格式如"1539245230"。对原文使用 access_token 进行 AES加密（加密方式与上文相同），得到的密文即为 secret 值。

时间戳有效期为1小时

例： access_token="22222222222222222222222222222222" 原文="000000$1539244803", 密文 "n7UyHoQYFdCIcPKH7FEsQTx7-CPOKj1WNt7gSKb-EHY="

返回示例

 
xxxxxxxxxx
{
   "code": 200,
   "msg": "success",
}

绑定信息回调

绑定操作完成后，收到PYL发出的回调链接后，需要再请求此API返回给PYL一个回调，以确保双方都已经收到同一份回调。

GET /api/v1/callback

请求参数

名称	类型	备注
access_token	string	(必填) 注意是 access_token
secret	string	(必填) 从PYL的回调里接受到的 secret 值

重新绑定用户(未使用)

将自己的通途帐号重新绑定到一个新的分销系统帐号上

POST /api/v1/rebind

请求参数

名称	类型	备注
account_code	string	(必填) 新的经销商代号
tname	string	(必填) 要重新授权的通途帐号

返回示例

 
xxxxxxxxxx
{
   "code": 200,
   "msg": "success",
}

信息接口

域名： http://api.pyl.com.cn

鉴权方式

返回格式

商品列表：

参数

data

分类列表

data

库存列表

参数

data

查询多个SKU的专线物流信息

参数

返回参数data

返回示例

订单接口

创建订单

请求参数

请求示例

返回参数data

返回示例

查询订单发货详情

请求参数

请求示例

返回参数data

返回示例

作废订单

请求参数

请求示例

返回参数data

返回示例

取消作废订单

请求参数

请求示例

返回参数data

返回示例

获取邮寄方式列表

返回参数data

返回示例

获取已下架商品sku

请求参数

返回data

返回示例

获取经销商商品SKU

请求参数

返回data

返回示例

帐号绑定

除此页面外，下面其它接口的域名还是 api.pyl.com.cn

参数

生成 pub_token

Secret 生成方法

redirect

另附几组测试用例

查询是否已绑定用户

请求参数

返回data

返回示例

解绑用户

参数

secret

返回示例

绑定信息回调

请求参数

重新绑定用户(未使用)

请求参数

返回示例

除此页面外，下面其它接口的域名还是 `api.pyl.com.cn`