开放平台
地铁线上购票快速接入
该文档主要面向需要入驻蚂蚁金服开放平台的产品、架构、开发等相关人员， 需要有基本的程序开发背景。通过该文档能够快速集成（地铁线上购票）功能，接入前需要入驻开放平台并创建了应用，应用已申请该接口权限并配置RSA密钥。
第一步：创建应用
要在您的应用中使用支付宝开放产品的接口能力，您需要先去蚂蚁金服开放平台（open.alipay.com），在开发者中心中创建登记您的应用，并提交审核，审核通过后会为您生成应用唯一标识（APPID），并且可以申请开通开放产品使用权限，通过APPID您的应用才能调用开放产品的接口能力。需要详细了解开放平台创建应用步骤请参考《开放平台应用创建指南》。
第二步：配置密钥
开发者调用接口前需要先生成RSA密钥，RSA密钥包含应用私钥(APP_PRIVATE_KEY)、应用公钥(APP_PUBLIC_KEY）。生成密钥后在开放平台开发者中心进行密钥配置，配置完成后可以获取支付宝公钥(ALIPAY_PUBLIC_KEY)。详情请参考《配置应用环境》。
第三步：搭建和配置开发环境
接口调用流程
| 接口英文名 | 接口中文名 | 业务功能 |
|---|---|---|
| alipay.commerce.cityfacilitator.voucher.generate |
购票发码 |
开发者在用户支付成功后够调用该接口进行发码 |
| alipay.commerce.cityfacilitator.voucher.refund |
购票发码退款 |
发码成功后但用户未核销前调用该接口进行撤销，资金退还给用户 |
| alipay.commerce.cityfacilitator.station.query |
地铁车站数据查询 |
开发者可通过该接口查询指定城市的地铁站相关信息，比如A城市支持的购票起点站 |
| alipay.commerce.cityfacilitator.voucher.batchquery |
核销码批量查询 |
开发者可通过该接口批量查询指定核销码的记录 |
购票发码流程：
通过demo集成接入
点击下载地铁购票demo相应版本
地铁购票demo时在原SDK的基础上，针对接口的调用做了一层封装，在调用中会更方便；Java demo是eclipse编写的，解压后，请导入到eclipse工程中，在了解demo时，请结合demo中的说明文档进行集成。
工程目录结构：
运行环境：
- JDK:1.5
- Eclipse（字符集：UTF-8）
运行步骤：
- 将工程导入到eclipse
- 配置alipay.metro.sdk.config.AlipayConfig文件，根据商户自身情况，修改APPID（开发在开放平台中的APPID）、APP_PRIVATE_KEY（应用私钥）
- 打开alipay.metro.sdk.demo包中的指定接口demo运行
- 其余问题请查看readme
工程目录结构：
基于大部分机具所使用的操作系统都原生支持C\C++，所以Demo目前为C++版本，可以基于Qt，也可以基于标准库STL；其它语言可以通过动态库调用的方式调用C\C++代码生成的动态库（比如Java\C#）。
运行环境取决于机具本身的操作系统，支持大部分通用的操作系统，如windows\linux\android。
Demo直接运行就可以（双击或者命令行都可以）
通过SDK集成接入
1.下载SDK
为了帮助开发者调用开放接口，我们提供了开放平台服务端SDK，包含JAVA、PHP和.NET三个语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的SDK并引入您的开发工程。
2.SDK调用示例
在SDK调用前需要进行初始化，代码如下：
AlipayClient alipayClient = new DefaultAlipayClient(URL, APP_ID, APP_PRIVATE_KEY, FORMAT, CHARSET, ALIPAY_PUBLIC_KEY, SIGN_TYPE);
关键参数说明:
| 配置参数 | 示例值解释 | 获取方式/示例值 |
|---|---|---|
| URL | 支付宝网关（固定） | https://openapi.alipay.com/gateway.do |
| APPID | APPID 即创建应用后生成 | 获取见上面创建应用并获取APPID |
| APP_PRIVATE_KEY | 开发者私钥，由开发者自己生成 | 获取详见上面配置密钥 |
| FORMAT | 参数返回格式，只支持json | json（固定） |
| CHARSET | 编码集，支持GBK/UTF-8 | 开发者根据实际工程编码配置 |
| ALIPAY_PUBLIC_KEY | 支付宝公钥，由支付宝生成 | 获取详见上面配置密钥 |
| SIGN_TYPE | 商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2 | RSA2 |
1. 购票发码alipay.commerce.cityfacilitator.voucher.generate
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayCommerceCityfacilitatorVoucherGenerateRequest request = new AlipayCommerceCityfacilitatorVoucherGenerateRequest();
request.setBizContent("{" +
"\"city_code\":\"440300\"," +
"\"trade_no\":\"2016072621001004110000001346\"," +
"\"total_fee\":\"10.00\"," +
"\"ticket_num\":\"2\"," +
"\"ticket_type\":\"oneway\"," +
"\"site_begin\":\"02490301\"," +
"\"site_end\":\"02490305\"," +
"\"ticket_price\":\"5.00\"" +
"}");
AlipayCommerceCityfacilitatorVoucherGenerateResponse response = alipayClient.execute(request);
//------------开发者需要根据response返回结果处理业务 --------------//
2. 购票发码退款alipay.commerce.cityfacilitator.voucher.refund
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayCommerceCityfacilitatorVoucherRefundRequest request = new AlipayCommerceCityfacilitatorVoucherRefundRequest();
request.setBizContent("{" +
"\"city_code\":\"440300\"," +
"\"trade_no\":\"2016072621001004110000001346\"" +
"}");
AlipayCommerceCityfacilitatorVoucherRefundResponse response = alipayClient.execute(request);
//------------开发者需要根据response返回结果处理业务 --------------//
3. 地铁车站数据查询alipay.commerce.cityfacilitator.station.query
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayCommerceCityfacilitatorStationQueryRequest request = new AlipayCommerceCityfacilitatorStationQueryRequest();
request.setBizContent("{" +
" \"city_code\":\"440300\"" +
" }");
AlipayCommerceCityfacilitatorStationQueryResponse response = alipayClient.execute(request);
//------------开发者需要根据response返回结果处理业务 --------------//
4. 核销码批量查询alipay.commerce.cityfacilitator.voucher.batchquery
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", APP_ID, APP_PRIVATE_KEY, "json", CHARSET, ALIPAY_PUBLIC_KEY, "RSA2");
AlipayCommerceCityfacilitatorVoucherBatchqueryRequest request = new AlipayCommerceCityfacilitatorVoucherBatchqueryRequest();
request.setBizContent("{" +
" \"city_code\":\"440300\"," +
" \"trade_nos\":[" +
" \"2016072621001004110000001346\"" +
" ]" +
" }");
AlipayCommerceCityfacilitatorVoucherBatchqueryResponse response = alipayClient.execute(request);
//------------开发者需要根据response返回结果处理业务 --------------//
接口调用结果处理
获取接口处理结果代码示例
AlipayCommerceCityfacilitatorVoucherGenerateResponse response = alipayClient.execute(request); System.out.println(response.getCode());//获取结果码 System.out.println(response.getSubCode());//获取子错误码 System.out.println(response.getMsg());//获取子错误描述 System.out.println(response.getBody());//获取返回报文
| 同步返回结果码 | 含义 | 说明 |
|---|---|---|
| 10000 |
业务处理成功 |
|
| 40001～40006 |
业务处理失败 |
具体失败原因请参考公共错误码。其它请参考API文档。 |
| 20000 |
业务出现未知错误或者系统异常 |
业务出现未知错误或者系统异常（请一定要在确定本次调用结果后，再发起重试），若有结果接口的，需调用查询接口发起查询。 |
