报销应用

简介

支付宝发票报销为用户提供了随时随地快速选择发票报销的功能,省去用户以往繁琐的报销过程,方便用户快速完成选择发票报销。由用户在报销APP中选择支付宝导入发票,在支付宝端选择发票后,报销服务方获取用户选择的发票,快速完成报销,用户可在支付宝发票管家中查看发票所处于的报销状态,同时可在发票详情页中点击发票状态,进入报销app查看具体发票报销流程。

支付宝提供的能力

1.发票输出能力
用户主动选取发票管家的发票后,可以输出给报销系统用于报销。

2.发票报销情况跟踪能力
从支付宝上选取到报销系统的发票,用户可在发票管家查看对应发票的报销状态或者审批进度。

DEMO示例

系统流程


接入说明

1.发票输出组件说明

使用场景:主要完成由ISV唤醒支付宝发票管家选择发票后携带查询令牌返回到报销app。

端外APP唤起支付宝发票输出组件方法:

1、 构造发票输出回调链接
如发票输出回调地址为 http://isv.app.com?param1=aaa&param2=bbb
a.回调地址参数部分命名不能包含(invoiceToken),整体url长度不能超过300个字符
b.需要对发票输出回调地址整体进行encode,编码格式固定为utf-8
  如URLEncoder.encode("http://isv.app.com?param1=aaa&param2=bbb","utf-8");
 
2、 构造支付宝发票输出组件链接
支付宝发票输出组件固定链接地址为 /www/invoiceSelect.htm?scene=#发票输出业务场景#&einvMerchantId=#企业标志#&serverRedirectUrl=#步骤1中urlEncode后的发票输出回调地址#
       参数说明:

参数名称 参数说明 是否必填
scene 发票输出业务场景码
固定值:INVOICE_EXPENSE
einvMerchantId 企业标志即用户所属企业的税号,唯一,该企业需要在发票管家入驻
serverRedirectUrl 发票输出回调地址,由报销平台提供,且此地址(参数前部分)需要和报销平台入驻发票管家时提供配置保持一致


      步骤1构造的发票输出回调链接作为支付宝发票输出组件链接的请求参数serverRedirectUrl的值
      注:支付宝发票输出组件链接需要再次进行整体URLEncoder
 
3、 构造支付宝app唤起链接

a)H5唤起支付宝app链接

支付宝app唤起地址为固定链接:
https://render.alipay.com/p/s/i?scheme=alipays://platformapi/startapp?appId=20000920&startMultApp=YES&url=#步骤步骤2中urlEncode后的发票输出组件链接地址#
参数说明:

参数名称 参数说明 是否必填
appid 固定值:20000920
url 步骤3.2中构造的发票输出组件链接地址,并对链接地址整体进行urlencode

示例:
https://render.alipay.com/p/s/i?scheme=alipays://platformapi/startapp?appId=20000920&startMultApp=YES&url=%2Fwww%2FinvoiceSelect.htm%3Fscene%3DINVOICE_EXPENSE%26einvMerchantId%3D9131000074027295XF%26serverRedirectUrl%3Dhttp%253A%252F%252Fhtml.qingyuko.com%252Fticket2.html
 
b)IOS唤起支付宝app链接
 
示例代码(详见SDK文档):

- (void)demoAuth
{
    NSDictionary *params = @{kAFServiceOptionBizParams: @{
            @"url": @"/www/invoiceSelect.htm?scene=INVOICE_EXPENSE&einvMerchantId=9131000074027295XF&serverRedirectUrl=http%3A%2F%2Fhtml.qingyuko.com%2Fticket2.html "
            },
      kAFServiceOptionCallbackScheme: @"apsdkdemo",
      };
    
    [AFServiceCenter callService:AFServiceEInvoice withParams:params andCompletion:^(AFServiceResponse *response) {
        
        NSLog(@"%@", response.result);
    }];
}

参数说明:

名称 说明 是否必填
callService 固定值:AFServiceEInvoice
withParams.url 步骤2中构造的发票输出组件链接地址,无需对整体链接进行encode,sdk会自动进行此步骤
andCompletion 回调函数

业务回调结果(response.result):

返回结果-成功

{
  status: "success",
  token: "" // 获取用户选择的发票的token串
}

返回结果-用户取消

{
  status: "cancel"
}

返回结果-发生错误

{
  status: "fail",
  errorCode: 4002, // 后端错误码
  errorMsg: "" // 后端错误Msg
}

4、 构造发票输出组件链接示例代码(java)

//唤起支付宝固定链接
String url="https://render.alipay.com/p/s/i?appId=20000920&startMultApp=YES&url=";
        //ISV回调地址
        String isvUrl="http://html.qingyuko.com/ticket2.html";
        //编码之后的ISV回调地址
        String encodeIsvUrl=UrlUtils.encode(isvUrl);
        //发票输出组件固定链接
        String alipayUrl="/www/invoiceSelect.htm?scene=INVOICE_EXPENSE&einvMerchantId=9131000074027295XF&serverRedirectUrl="+encodeIsvUrl;
        //编码之后的发票输出组件链接
        String encodeAlipayUrl=UrlUtils.encode(alipayUrl);
        //唤起发票输出组件的完整链接
        String alipayLandingUrl=url+encodeAlipayUrl;

2、根据查询令牌获取发票要素列表(alipay.ebpp.invoice.token.batchquery )

场景说明:只有在外部app唤起支付宝选择发票后才能调用该接口,根据用户通过发票管家选择发票列表产生的请求令牌获取用户选择发票要素列表:

SDK调用示例(以JAVA为例,更多语言示例参见接口文档)

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayEbppInvoiceTokenBatchqueryRequest request = new AlipayEbppInvoiceTokenBatchqueryRequest();
request.setBizContent("{" +
"\"invoice_token\":\"0136d80096e34a07a528db7cc5bc442888s\"," +
"\"scene\":\"INVOICE_EXPENSE\"" +
"  }");
AlipayEbppInvoiceTokenBatchqueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_ebpp_invoice_token_batchquery_response":{
    "code":"10000",
    "msg":"Success",
"user_id":"20880000000000000",
      "invoice_element_list":[{
        "expense_status":"WAIT_EXPENSE",
"invoice_status":"SUCCEED",
"invoice_code":"1234567890",
"invoice_no":"12345678",
"invoice_amount":"100",
"invoice_date":"2017-07-11",
"invoice_kind":"PLAIN",
"payer_name":"支付宝(中国)技术有限公司",
"payer_tax_no":"1234567890",
"payee_name":"国力大酒店",
"payee_tax_no":"1234567890",
"invoice_img_url":"https://www.alipay.com",
"has_risk":true,
"has_pdf_file":true
        }]
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

3、发票报销处理进度同步(alipay.ebpp.invoice.expense.progress.sync)

使用场景:ISV获取发票要素后,此时要给用户展示在支付宝选择的发票,用户必须确认是否报销,确认后,需要调用发票报销处理进度同步接口,同步到支付宝该发票状态为报销中,此时支付宝端会锁定该发票,其他报销app无法再获取或者同步该发票,该发票详情页右上角的报销中状态处于可点击状态,会根据该链接跳转到ISV的发票报销流程页面,该链接为ISV调用报销报销处理进度同步时,传入的报销详情地址,除参数列表部分外,传入值必须和配置模板中提供的查看报销进度地址一致。

TIPS发票管家的发票状态需和报销app中状态保持一致
SDK调用示例(以JAVA为例,更多语言示例参见接口文档)

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayEbppInvoiceExpenseProgressSyncRequest request = new AlipayEbppInvoiceExpenseProgressSyncRequest();
request.setBizContent("{" +
"\"user_id\":\"20880000000000000\"," +
"\"invoice_code\":\"1234567890\"," +
"\"invoice_no\":\"12345678\"," +
"\"status\":\"EXPENSE_APPLY\"," +
"\"expense_detail_url\":\"http://www.baidu.com\"," +
"\"expense_order_no\":\"123\"," +
"\"business_time\":\"2017-08-14 10:10:00\"," +
"\"expense_tax_no\":\"123456\"," +
"\"apply_id\":\"BxpO0dtPbcLLpwD8h5H47ehQXkBdI\"," +
"\"memo\":\"财务已打款\"" +
"  }");
AlipayEbppInvoiceExpenseProgressSyncResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_ebpp_invoice_expense_progress_sync_response":{
    "code":"10000",
    "msg":"Success"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

4、获取发票详细信息(alipay.ebpp.invoice.detail.output.query)

使用场景:根据发票代码,发票号码获取发票详细信息 查询权限要求: 发票属于当前isv报销单据进行状态(支持的状态有 EXPENSE_APPLY-用户已提交申请 EXPENSE_APPROVAL_PASS -报销审核通过 EXPENSE_FINISHED-报销完结)。

SDK调用示例(以JAVA为例,更多语言示例参见接口文档)

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayEbppInvoiceDetailOutputQueryRequest request = new AlipayEbppInvoiceDetailOutputQueryRequest();
request.setBizContent("{" +
"\"user_id\":\"20880000000000000\"," +
"\"invoice_code\":\"1234567890\"," +
"\"invoice_no\":\"12345678\"," +
"\"scene\":\"INVOICE_EXPENSE\"" +
"  }");
AlipayEbppInvoiceDetailOutputQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_ebpp_invoice_detail_output_query_response":{
    "code":"10000",
    "msg":"Success",
"invoice_code":"123456",
"invoice_no":"123",
"invoice_amount":"100.00",
"invoice_date":"2017-07-10",
"tax_type":"PLAIN",
"expense_status":"WAIT_APPLY",
"invoice_type":"blue",
"invoice_status":"SUCCEED",
"payee_register_name":"国力大酒店",
"has_upload_pdf":"false",
"ex_tax_amount":"85.00",
"sum_tax_amount":"15.00",
"payee_tax_no":"123456789",
"payee_address":"浙江杭州万塘路18号",
"payee_phone":"012-0000000",
"payee_bank_name":"建设银行",
"payee_bank_account":"1234",
"payer_name":"支付宝(中国)技术有限公司",
"payer_tax_no":"1234",
"payer_address":"浙江杭州西湖区天目山路222号",
"payer_phone":"1893445555555",
"payer_bank_name":"招商银行",
"payer_bank_account":"123556",
      "invoice_item_content_list":[{
        "item_name":"电脑",
"item_no":"00001",
"item_price":"100.00",
"item_quantity":10,
"row_type":0,
"item_sum_price":"100.00",
"item_tax_price":"10.00",
"item_tax_rate":"0.12",
"item_unit":"单位",
"item_amount":"100.00"
        }],
"invoice_img_url":"http://img.test.com",
"anti_fake_code":"14345678908765433456",
"has_risk":true
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

5、获取电子发票原文件(alipay.ebpp.invoice.file.output.query)

使用场景:发票同步成功后,此时ISV可以获取电子发票原文件,完成发票报销。报销完成后,需要再次同步到支付宝发票状态为报销完结
 SDK调用示例(以JAVA为例,更多语言示例参见接口文档)

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayEbppInvoiceFileOutputQueryRequest request = new AlipayEbppInvoiceFileOutputQueryRequest();
request.setBizContent("{" +
"\"user_id\":\"2088550000000\"," +
"\"invoice_code\":\"123\"," +
"\"invoice_no\":\"111\"," +
"\"scene\":\"INVOICE_EXPENSE\"" +
"  }");
AlipayEbppInvoiceFileOutputQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}

JSON响应示例

{
"alipay_ebpp_invoice_file_output_query_response":{
    "code":"10000",
    "msg":"Success",
"invoice_file_content":"SEWHBFR2GKMBJNY52JBM56N"
  }
,"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}
onlineServer