管理API对接文档（2024版）

最近更新时间：

接口说明

说明

1.先调用“商旅订单”接口，获取订单id、票id

2.按选择的订单id或票id，调用“商旅按行程开票”接口，发起开票申请，接口会返回开票申请批id（batch_id）

3.根据申请批id（batch_id）定时调用“发票查询”接口，可查询开票申请的状态

4.根据申请批id（batch_id）调用“电子发票下载”接口，下载发票文件zip包

5.根据申请批id（batch_id）调用“电子发票信息查询”接口，查询发票结构化数据（不含电子行程单）

注意

  1. 开票规则：只有商旅品类且未开票(is_invoice=0)的订单才可以开票

  2. 参数限制：

    1. 普票：invoice_type=4, invoice_title为发票抬头，必填；
    2. 专票：invoice_type=5, invoice_qid为开票资质ID，必填，并且必须为专票资质列表api返回结果中的资质ID


流程：

基本信息

HTTP URL

/river/Invoice/applybiz

HTTP Method

JSON

权限要求


请求头

参数名称

参数值

Content-Type

application/json

请求参数

字段名

字段说明

字段类型

必填

备注

client_id

申请应用时分配的AppKey

string

Y

申请应用时分配的AppKey

access_token

授权后的access token

string

Y

授权后的access token

timestamp

当前时间戳

bigint

Y

当前时间戳

sign

签名

string

Y

签名

company_id

公司id

Long

Y

公司id

sub_business_type

商旅品类开票子品类

int

Y

商旅品类开票子品类
201：国内酒店 202：国内机票 203 : 火车票 204 : 国际酒店

pay_type

订单类型

int

Y

订单类型
0-个垫订单开票
1-企业支付订单开票

invoice_no

开票请求编号

string

Y

开票请求编号(客户接入方唯一标识)

remark

备注

string

N

备注(长度<=100)

receiver_email

开票收件邮箱

string

Y

开票收件邮箱

invoice_info

invoice_info

string

Y

开票信息(可多个 上限500笔订单或票id)，json格式


invoice_info

字段名

字段说明

字段类型

必填

备注

order_ids

酒店订单集合

string

no

酒店子品类时必填
酒店订单集合,字符串类型 多个时逗号分割 by 订单开票,：支持酒店,机票,火车票品类 by 订单开票；
字符串类型，多个时逗号分割；
订单开票时, 订单下的相同费项(例如服务费)会聚合开一张大票(行程单,火车票票根类型除外)。

ticket_ids

机票票id 集合

string

no

机票子品类时必填
机票票id 集合,字符串类型 多个时逗号分割

invoice_type

发票类型

int

no

发票类型 (4 数电普票, 5 数电专票)，默认专票

invoice_title

发票抬头

string

no

发票抬头(数电普票时必填,专票时不会使用)

invoice_qid

资质id(

Long

no

资质id(数电专票时必填,普票时不会使用)

is_merge

发票是否聚合开具

Int

no

是否聚合开票(相同费项聚合开一张发票，默认“是” ； 这里的合并是：相同开票主体、相同发票类型下 本次申请的订单 或 票id 下相同费项合并开票（机票行程单火车票票根费项除外)


请求示例

curl -X POST --location "https://api.es.xiaojukeji.com/river/invoice/applybiz" -H "Content-Type: application/json" -d '{"access_token": "a2dbeb9d64573f61427b9003cf646747ef534cd8","invoice_info": "[{\"order_ids\":"1111111111111,1111111111112,1111111111113",\"ticket_ids\":"",\"invoice_type\":4,\"invoice_title\":\"普票抬头 \",\"invoice_qid\":2222111}]","company_id": "xxxxxxxxxx","receiver_email": "xxxxx@xxxxx.com","invoice_no": "aaaaaddddd","sign": "f8b206b0a81e084a3206429c66b7e521","pay_type": 0,"remark": "测试数据","sub_business_type": 201,"client_id": "8c284774bad6368160c489667813f0f7a","sign_key": "fbba07E606f359AC1981","timestamp": "1730448237218"}'

字段名

字段说明

字段类型

备注

errno

错误码

string

0表示成功，非0表示失败

errmsg

错误信息

string

errno=0时为常量"SUCCESS"，errno!=0时为错误信息

data

返回数据

object

返回数据

data.batch_id

开票批次id



data.status

申请开票状态

int

该批次申请开票状态,非0时,result有值
全部成功 0 ；部分成功 1；全部失败 2

data.result

失败明细

list

失败明细合计, 实际开票是以最细粒度去开票的 ：酒店是订单, 机票火车票是票；
因此最细粒度开票失败时,此字段会记录开票失败原因, 可能会有订单id或票id定位提示


data数据格式

字段名

字段说明

字段类型

备注

batch_id

开票批次id

string



注意
  1. 多笔订单开票时,相同开票信息的相同开票品类的多个相同开票费项会合并开票,且这些订单会在一个批次里开票,故返回开票申请的批次id
  2. is_merge 聚合开票的含义是整体开票申请下相同开票抬头相同发票类型相同开票费项聚合开大票,同样机票行程单,火车票票根除外

响应示例

正常示例

{
    "errno":0,
    "errmsg":"success",
    "data":{
        "batch_id":11112333322244444
    }
}

全部失败示例

// 全部失败示例

{
    "errno": 0,
    "errmsg": "SUCCESS",
    "data": {
        "status": 2,
        "result": [
            {
                "message": "未查询到可开票的数据"
            }
        ],
        "batch_id": null
    }
}

部分失败示例

{
"errno": 0,
    "errmsg": "SUCCESS",
    "data": {
        "status": 1,
        "result": [
            {
                "order_id": 4503547744,
                "message": "此订单id没有可开票数据,无法开票,请仔细检查,如有疑问,请联系管理员"
            }
        ],
        "batch_id": 1125968374853271
    }
}


错误码

通用错误解决方案

错误码

错误说明

50103(该流水号已经开过票了)

invoice_no不能重复，本次传参中的invoice_no已经被使用过，请换一个


版本记录

日期

更新人

更新内容

上线时间

2024.11.04

陈继诗

迁移文档

2024.11.20

2024.11.20

陈继诗

迁移文档，修改请求地址为https://api.es.xiaojukeji.com/river/Invoice/applybiz

2024.11.20

2024.12.03

陈继诗

迁移文档，修改invoice_info为string类型

2024.12.03

2025.06.20

关珺丹

更新开票接口字段信息

2025.06.13