API调用

请注意本文章只针对V2.0接口调用进行讲述。

正式环境和测试环境我们都提供两种域名：

正式环境：

https://openplatform.shopee.cn/ —服务部署地近中国大陆的开发者使用

https://openplatform.shopee.com.br/ —服务部署地近美国的开发者使用

https://partner.shopeemobile.com/ —服务部署地近新加坡的开发者使用

沙箱环境：

https://openplatform.sandbox.test-stable.shopee.sg/ —所有开发者都可以使用

https://openplatform.sandbox.test-stable.shopee.cn/ —中国大陆的开发者使用

请您根据调用Open API服务器所在地，选择正确的域名。

目前Open API 只提供两种请求方法：Get和Post。

大多数API使用HTTP/JSON协议。 某些API，例如上传文件的 API，使用的 HTTP/FORM。

在API文档中，您将会看到两种请求参数，一种是公共请求参数（Common Parameter），一种是业务请求参数（Request Parameter），对于Get类型的接口，可能两种参数同时存在，也可能只存在公共请求参数，Post类型接口，两种参数同时存在。

下面是关于公共参数的说明：

在API文档中，根据公共参数的不同，我们分为三种API类型，这三种类型包含的公共参数如下：

• Shop API: partner_id、 timestamp、sign、access_token、shop_id
• Merchant API: partner_id、 timestamp、sign、access_token、merchant_id
• Public API: partner_id、 timestamp、sign

可以看到，Public类型接口不需要access token, Shop类型和Merchant类型接口都需要access_token, 这意味着Shop类型和Merchant类型接口需要完成店铺授权之后才能调用，Public类型接口不需要。

*目前只有Shopee跨境商家需要使用Merchant类型接口，本土卖家不需要使用。

第一步: 创建基本字符串(Base string):

不同类型的API，Base string包含的元素不一样，请严格按照下列先后次序，将api path(不带host) 和下列公共参数拼接为单一字符串，即为base string:

*api path 样例：/api/v2/auth/token/get

Shop API: partner_id, api path, timestamp, access_token, shop_id

*样例：

partner_id: 2001887

api path: /api/v2/shop/get_shop_info

timestamp: 1655714431

access_token: 59777174636562737266615546704c6d

shop id: 14701711

Base string=2001887/api/v2/shop/get_shop_info165571443159777174636562737266615546704c6d14701711

Merchant API:partner_id, api path, timestamp, access_token, merchant_id

*样例：

partner_id: 2001887

api path: /api/v2/global_product/get_category

timestamp: 1655714431

access_token: 09777174636962737266615546704c6d

merchant_id: 1000000

Base string=2001887/api/v2/global_product/get_category165571443109777174636962737266615546704c6d1000000

Public API:partner_id, api path, timestamp

*样例：

partner_id:2001887

api path: /api/v2/public/get_shops_by_partner

timestamp:1655714431

Base string=2001887/api/v2/public/get_shops_by_partner1655714431

第二步: 采用HMAC-SHA256算法计算签名(sign)

将基本字符串(Base string)和partner Key( 通过控制台获取）用HMAC-SHA256散列算法来计算签名。 散列函数的输出是一个十六进制编码的字符串。

*样例：

sign=56f31d01aeda9d08bf456b37f6f6640ef8614b4d6ad49baafe30b39a061f0e26

*如果您在调用过程中遇到Wrong sign的报错，可以点击这里查看解决方案

生成签名代码样例：

#!/usr/bin/envpython

# encoding:utf-8



import hmac 

import time

import requests

import hashlib

timest=int(time.time())

host="https://partner.shopeemobile.com 

access_token = "random string"



partner id =80001

partner key = "test....."



#### call shop level api 

shop id =209920

base string ="%s%s%s%s%s"%(partner id, path timest access token, shop id) 

sign = hmac.new( partner key,base string,hashlib.sha256)hexdigest() 

path ="/api/v2/example/shop level/get"



url = host + path + "?partner_id=%s&shop_id=%s&timestamp=%s&access_token=%s&sign=%s"%(partner_id, shop_id, timest, access_token, sign) 

headers={"Content-Type":"application/ison"? 

resp=requests.post(urlheaders=headers)



#### call merchant level api 

merchant id =1234567

base string ="%s%s%s%s%s"%(partner id, path timest, access token, merchant id) 

sign =hmac.new( partner key,base string,hashlib.sha256).hexdigest() 

path ="/api/v2/example/merchant_level/get"



url = host+ path +"?partner id=%s&merchant id=%s&timestamp=%s&access token=%s&sign=%s"%(partnerid, merchant id, timest, access token, sign) 

headers ={"Content-Type":"application/ison"? resp =requests.eet(urlheaders=headers)



#### call public api

base string ="%s%s%5%s"%(partner idpathtimestaccess token)

sign= hmac.new( partner keybase stringhashlib.sha256)hexdigest() 

path ="/api/v2/auth merchant/access token/get"



url = host+path+"?partner id=%s&timestamp=%s&sign=%s%(partner idtimest, sign)

body ={"partner id":partner id, "merchant id": merchant id,"refresh token":"testingtoken") 

headers =["Content-Type":"application/ison"?

resp =requests.post(url,json=bodyheaders=headers)

对于Get请求，您需要将公共参数和业务参数都放在url中

例如v2.product.get_category

请求URL样例:

https://partner.shopeemobile.com/api/v2/product/get_category?partner_id=851249&timestamp=1654673582&shop_id=1001094&access_token=367a0a8eb9d1837cbf7c43b587a0faa4&sign=a40fc50a08c382eeee08e2eb00deb8464c6fdcbe4f1c271e033cdbca3ded4d5b&language=zh-hans

*此接口中，partner_id、timestamp、access_token、shop_id、sign都是公共参数，language是业务参数

对于Post请求，您需要将公共参数放在请求url中，业务参数放在request body中

例如v2.shop.update_profile

请求URL样例:

https://partner.shopeemobile.com/api/v2/shop/update_profile?partner_id=851249&timestamp=1654673582&shop_id=1001094&access_token=367a0a8eb9d1837cbf7c43b587a0faa4&sign=80cbce8da907d5a1237711409920fc16908a9f9e01b1254ff9cc44aaf0836122

Request body:

{

"shop_logo": "https://cf.shopee.sg/file/8424390be4677b0b3c37ce6499ce261a",

"description": "TTest",

"shop_name": "123"

}

*此接口中，partner_id、timestamp、access_token、shop_id、sign都是公共参数，shop_log、description、shop_name是业务参数

每个API都有调用频率限制，如果超出限制您会收到HttpCode429的错误。当您收到此错误时，请适当降低调用频率，以便在接口限流的情况下保持稳定的调用，避免频繁的重试操作，因为这会进一步增加接口的负载压力。如果您未及时进行调整并且持续产生此错误，我们会限制您的API调用，这可能会对您的业务产生不利影响。

如果您在API集成过程中，遇到问题，可以先查询FAQ模块，如果仍不能解决，可以提报工单。