淘宝开放平台

请求地址：

环境	HTTP请求地址	HTTPS请求地址
正式环境	http://gw.api.taobao.com/router/rest	https://eco.taobao.com/router/rest

公共请求参数：

名称	类型	是否必须	描述
method	String	是	API接口名称。
app_key	String	是	TOP分配给应用的AppKey。
target_app_key	String	否	被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。
sign_method	String	是	签名的摘要算法，可选值为：hmac，md5。
sign	String	是	API输入参数签名结果，签名算法介绍请点击这里。
session	String	否	用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。
timestamp	String	是	时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2015-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。
format	String	否	响应格式。默认为xml格式，可选值：xml，json。
v	String	是	API协议版本，可选值：2.0。
partner_id	String	否	合作伙伴身份标识。
simplify	Boolean	否	是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。

名称	类型	是否必须	示例值	更多限制	描述
client_ads	ClientAd []	必须		最大列表长度：100	客户端的有效广告列表
└ ad_id Number 必须 2 广告id └ md5_code String 必须 ED903AEDB5C276F33AE60F63C6B24C41 广告文件的实际md5码 └ play_status String 必须 PLAYED 广告播放状态：PLAYED-播放中，PLAYING-播放时间未到，待播放 └ play_count Number 可选 10 广告轮播次数（间隔增量）
partner_no	String	必须	taijiu		供应商编号
terminal_id	String	必须	TB00001		机具编号

名称	类型	示例值	描述
data	ClientAdListReceiveResponse	data	数据模型
└ interval Number 240 接口调用频率，单位（分）
result_code	String	1	请求处理的异常代码
result_desc	String	操作成功	请求处理的异常信息
status	Number	1	本次交互是否有异常：1-成功，0-异常

JAVA
.NET
PHP
CURL
Python
C/C++
NodeJS

TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
FilmTerminalClientadReceiveRequest req = new FilmTerminalClientadReceiveRequest();
List<FilmTerminalClientadReceiveRequest.ClientAd> list2 = new ArrayList<FilmTerminalClientadReceiveRequest.ClientAd>();
FilmTerminalClientadReceiveRequest.ClientAd obj3 = new FilmTerminalClientadReceiveRequest.ClientAd();
list2.add(obj3);
obj3.setAdId(2L);
obj3.setMd5Code("ED903AEDB5C276F33AE60F63C6B24C41");
obj3.setPlayStatus("PLAYED");
obj3.setPlayCount(10L);
req.setClientAds(list2);
req.setPartnerNo("taijiu");
req.setTerminalId("TB00001");
FilmTerminalClientadReceiveResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

ITopClient client = new DefaultTopClient(url, appkey, secret);
FilmTerminalClientadReceiveRequest req = new FilmTerminalClientadReceiveRequest();
List<FilmTerminalClientadReceiveRequest.ClientAdDomain> list2 = new List<FilmTerminalClientadReceiveRequest.ClientAdDomain>();
FilmTerminalClientadReceiveRequest.ClientAdDomain obj3 = new FilmTerminalClientadReceiveRequest.ClientAdDomain();
list2.Add(obj3);
obj3.AdId = 2L;
obj3.Md5Code = "ED903AEDB5C276F33AE60F63C6B24C41";
obj3.PlayStatus = "PLAYED";
obj3.PlayCount = 10L;
req.ClientAds_ = list2;
req.PartnerNo = "taijiu";
req.TerminalId = "TB00001";
FilmTerminalClientadReceiveResponse rsp = client.Execute(req);
Console.WriteLine(rsp.Body);

$c = new TopClient;
$c->appkey = $appkey;
$c->secretKey = $secret;
$req = new FilmTerminalClientadReceiveRequest;
$client_ads = new ClientAd;
$client_ads->ad_id="2";
$client_ads->md5_code="ED903AEDB5C276F33AE60F63C6B24C41";
$client_ads->play_status="PLAYED";
$client_ads->play_count="10";
$req->setClientAds(json_encode($client_ads));
$req->setPartnerNo("taijiu");
$req->setTerminalId("TB00001");
$resp = $c->execute($req);

curl -X POST 'http://gw.api.taobao.com/router/rest' \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'app_key=12129701' \
-d 'format=json' \
-d 'method=taobao.film.terminal.clientad.receive' \
-d 'partner_id=apidoc' \
-d 'sign=49A1BB90069151D23F30B9707D21ECB9' \
-d 'sign_method=hmac' \
-d 'timestamp=2025-05-06+01%3A54%3A23' \
-d 'v=2.0' \
-d 'client_ads=null' \
-d 'partner_no=taijiu' \
-d 'terminal_id=TB00001'

# -*- coding: utf-8 -*-
import top.api

req=top.api.FilmTerminalClientadReceiveRequest(url,port)
req.set_app_info(top.appinfo(appkey,secret))

req.client_ads=""
req.partner_no="taijiu"
req.terminal_id="TB00001"
try:
	resp= req.getResponse()
	print(resp)
except Exception,e:
	print(e)

pTopRequest pRequest = alloc_top_request();
pTopResponse pResponse = NULL;
pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret);
set_api_name(pRequest,"taobao.film.terminal.clientad.receive");
add_param(pRequest,"client_ads","数据结构JSON示例");
add_param(pRequest,"partner_no","taijiu");
add_param(pRequest,"terminal_id","TB00001");
pResponse = top_execute(pClient,pRequest,NULL);
printf("ret code:%d\n",pResponse->code);
if(pResponse->code == 0){
	pTopResponseIterator ite = init_response_iterator(pResponse);
	pResultItem pResultItem = alloc_result_item();
	while(parseNext(ite, pResultItem) == 0){
		printf("%s:%s\n",pResultItem->key,pResultItem->value);
	}
	destroy_response_iterator(ite);
	destroy_result_item(pResultItem);
}
destroy_top_request(pRequest);
destroy_top_response(pResponse);
destroy_taobao_client(pClient);

TopClient = require('./topClient').TopClient;
var client = new TopClient({
	'appkey': 'appkey',
	'appsecret': 'secret',
	'REST_URL': 'http://gw.api.taobao.com/router/rest'
});

client.execute('taobao.film.terminal.clientad.receive', {
	'client_ads':'数据结构JSON示例',
	'partner_no':'taijiu',
	'terminal_id':'TB00001'
}, function(error, response) {
	if (!error) console.log(response);
	else console.log(error);
})

XML示例
JSON示例

<film_terminal_clientad_receive_response>
    <data>
        <interval>240</interval>
    </data>
    <result_code>1</result_code>
    <result_desc>操作成功</result_desc>
    <status>1</status>
</film_terminal_clientad_receive_response>

{
    "film_terminal_clientad_receive_response":{
        "data":{
            "interval":240
        },
        "result_code":"1",
        "result_desc":"操作成功",
        "status":1
    }
}

XML示例
JSON示例

<error_response>
    <code>50</code>
    <msg>Remote service error</msg>
    <sub_code>isv.invalid-parameter</sub_code>
    <sub_msg>非法参数</sub_msg>
</error_response>

{
	"error_response":{
		"msg":"Remote service error",
		"code":50,
		"sub_msg":"非法参数",
		"sub_code":"isv.invalid-parameter"
	}
}

错误码	错误描述	解决方案

API测试工具错误码查询工具 SDK下载

电影票API

taobao.film.terminal.clientad.receive (机具客户端有效广告列表上送)

公共参数

请求参数

响应参数

请求示例

响应示例

异常示例

错误码解释

API工具

如何获得此API

FAQ