文档中心 > API类目 > 电影票API

taobao.film.data.third.party.issue.order (淘票票对外售票能力-出票接口)

淘票票对外售票能力-出票接口

公共参数

请求参数

名称 类型 是否必须 示例值 更多限制 描述
user_id Number 必须 3714018795 淘宝账号ID,此ID是一串数字。可自行百度查看如何获取或者咨询淘票票技术人员提供
platform Number 必须 3 淘票票分配的渠道码
lock_seat_apply_key String 必须 3714018795_3714018795 调用该接口前请确认一定是锁座成功的前提。该参数是从锁座返回的锁座ID,外部渠道需保证传入该参数的正确性,如果由于外部渠道自身传入的参数有问题而导致的下单出票接口返回的结果有误,需要外部渠道自己承担损失
ext_user_id String 必须 222222222 锁座身份ID,用于标识一个购票用户的身份,该参数需要跟锁座接口的ext_order_id参数一致,否则下单会失败。外部渠道需保证该参数的唯一性及准确性,下单出票接口会利用该参数做冥等性判断,如果由于外部渠道自身传入的参数有问题而导致的下单出票接口返回的结果有误,需要外部渠道自己承担损失
ext_order_id String 必须 111111111 下单时候需要传入第三方的订单号。外部渠道需保证该参数的唯一性和准确性
total_price Number 必须 5000 下单价格(以分为单位)
params Json 可选 {"price_detail":"user-3000,other-2000"} 参数必须要填,后期开票等需要用到。订单成本字段,key(price_detail), value(user-3000,other-2000), user代表用户实付金额,other代表其他补贴金额,两者相加等于订单的实际金额。价格字段以分为单位,不要有空格 代码如下所示: TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret); FilmDataThirdPartyIssueOrderRequest req = new FilmDataThirdPartyIssueOrderRequest(); req.setPlatform(3L); req.setParamsString("{\"price_detail\":\"user-3000,other-2000\"}"); req.setUserId(3714018795L); req.setLockSeatApplyKey("3714018795_3714018795"); req.setExtUserId("222222222"); req.setExtOrderId("111111111"); req.setTotalPrice(5000L); FilmDataThirdPartyIssueOrderResponse rsp = client.execute(req); System.out.println(rsp.getBody());

响应参数

名称 类型 示例值 描述
result ResultGeneralModel json result
  • return_value
  • TopOrderStatus
  • json
  • returnValue
  • └ message
  • String
  • 出票成功
  • message
  • └ status
  • String
  • TRADE_SUCCESS
  • 返回TRADE_SUCCESS、FAILED、DOING。95%的订单会在3s以内出票成功,调用下单出票接口的重试策略建议设置为 1s, 3s, 5s, 30s,60s, 120s,180s, 240s…..重试策略也可以由业务方自由发挥。如果出票状态是DOING,需要外部渠道一直进行重试,如果一直返回DOING, 需要外部渠道确保在第一次调用下单出票接口后的大于等于16分钟至少调用一次出票接口,如果出票结果仍旧返回是DOING,则可当做出票失败处理。如果由于外部渠道的原因未重试,或者最后一次重试的时间点未达到16分钟而导致的出票资损,需要由外部渠道承担
  • └ tb_order_id
  • String
  • 14234856846434949
  • tbOrderId
  • └ ticket_contents
  • String
  • 取票码:865202
  • 取票信息根据不同的影院会有不同的文案,所以文案的字符和格式没有固定的,多条文案以中划线分隔,外部渠道根据分隔后的字符串在app页面上逐条展示即可,文案的顺序由淘票票提供。以下是两种取票信息的示例, 1.订单号:8652026|验证码:84811 2.取票码:865202。如果想生成二维码,二维码的算法是一般的公有生成算法。如果得到的取票字段是"取票码:865202", 则使用 “865202”去生成二维码即可;如果得到的取票字段是"订单号:8652026|验证码:84811",则使用"8652026|84811"去生成二维码
  • top_sale_order_status_list
  • TopSaleOrderStatus []
  • 卖品出货信息
  • └ sale_id
  • String
  • 123
  • 卖品id
  • └ sale_tb_order_id
  • String
  • 1248719421148219
  • 卖品订单id
  • └ sale_content
  • String
  • 8432431
  • 卖品核销码
  • top_refund_rule
  • TopRefundRule
  • 退票规则。综合说明: 退票规则说明: 1、refundable = true 时,表示可以退票,结合退票时间线做进一步服务费判断; 2、refundable = false 时,表示不可退票,影院、场次排期、影片均有特殊情况直接不可退。 收费特殊说明: 1、当 is_charge = null 或者 is_charge= 0 或者 charge_rule_list 规则列表为空时,不收取手续费; 2、当 is_charge = 1 并且 charge_rule_list 规则列表size=1(只有一条规则)时,按固定金额收费; 3、当 is_charge = 1 并且 charge_rule_list 规则列表size >1(多条规则)时,按时间区间梯度收费。 4、is_charge 的判断优先级 高于 charge_rule_list 代码示例: { "top_refund_rule":{ "is_charge":1, "min_user_change_time":60, "charge_rule_list":[ { "totalCharge":0, "min_time_line":1440 }, { "totalCharge":500, "min_time_line":60 } ] } } 返回字段解释: is_charge为1: 表示收取服务费 min_user_change_time为60:表示距离开影前60分钟以上才可以退票,60分钟以内不允许再退票 charge_rule_list相关: 未取票开场前24小时以上,免费退票。 未取票开场前1小时至24小时,退票服务费5.0元/张。 未取票开场前1小时内不允许退票。
  • charge_rule_list
  • TopChargeRule []
  • 退票服务费规则
  • └ total_charge
  • Number
  • 500
  • 服务费金额。单位分
  • └ min_time_line
  • Number
  • 1440
  • 退票服务费梯度时间线。单位分钟
  • └ is_charge
  • Number
  • 1
  • 是否收费。1、0 表示不收取手续费,可免费退票。 2、1 表示收取手续费。
  • └ min_user_change_time
  • Number
  • 60
  • 距离开场前退票时间,处于该时间区间不允许退票。单位分钟
  • └ refundable
  • Boolean
  • true
  • 是否可退票。true 可退,false 不可退。 影院、场次排期、影片均有特殊情况直接不可退。
  • └ return_code
  • String
  • 0
  • 0代表接口调用成功,具体的下单出票结果参考status字段。 "40002", "非法参数",这种错误无需重试,有如下几种情况: 1.外部渠道传入了非法或者不匹配的参数导致 2.外部渠道锁座后超时未发起出票请求,导致座位被释放,一般锁座是15分钟超时释放,这种情况下也返回"非法参数" 3.外部渠道用户第一次锁座成功后生成锁座幂等串S,用户再去锁座第二个座位M, 此时会解锁第一个座位S, 如果此时外部渠道使用锁座幂等串S来下单,也会返回"非法参数" 注意:返回任何其他的错误码,都需要外部渠道进行重试,由于外部渠道未重试而导致的资损由外部渠道承担
  • └ return_message
  • String
  • 非法参数
  • 调用失败描述信息

请求示例

  • JAVA
  • .NET
  • PHP
  • CURL
  • Python
  • C/C++
  • NodeJS
TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
FilmDataThirdPartyIssueOrderRequest req = new FilmDataThirdPartyIssueOrderRequest();
req.setUserId(3714018795L);
req.setPlatform(3L);
req.setLockSeatApplyKey("3714018795_3714018795");
req.setExtUserId("222222222");
req.setExtOrderId("111111111");
req.setTotalPrice(5000L);
req.setParamsString("{\"price_detail\":\"user-3000,other-2000\"}");
FilmDataThirdPartyIssueOrderResponse rsp = client.execute(req);
System.out.println(rsp.getBody());

响应示例

  • XML示例
  • JSON示例
<film_data_third_party_issue_order_response>
    <result>
        <return_value>
            <message>出票成功</message>
            <status>TRADE_SUCCESS</status>
            <tb_order_id>14234856846434949</tb_order_id>
            <ticket_contents>取票码:865202</ticket_contents>
            <top_sale_order_status_list>
                <top_sale_order_status>
                    <sale_id>123</sale_id>
                    <sale_tb_order_id>1248719421148219</sale_tb_order_id>
                    <sale_content>8432431</sale_content>
                </top_sale_order_status>
            </top_sale_order_status_list>
            <top_refund_rule>
                <charge_rule_list>
                    <top_charge_rule>
                        <total_charge>500</total_charge>
                        <min_time_line>1440</min_time_line>
                    </top_charge_rule>
                </charge_rule_list>
                <is_charge>1</is_charge>
                <min_user_change_time>60</min_user_change_time>
                <refundable>true</refundable>
            </top_refund_rule>
        </return_value>
        <return_code>0</return_code>
        <return_message>非法参数</return_message>
    </result>
</film_data_third_party_issue_order_response>

异常示例

  • 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>

错误码解释

错误码 错误描述 解决方案

API工具

如何获得此API

FAQ

返回
顶部