管理API对接文档（2024版）

最近更新时间：

接口说明

注意
  • 开票规则：只有是个人垫付（pay_type=1）或混合支付（pay_type=2）且未开票(is_invoice=0)的订单（已支付或部分退款的）才可以开票，支持网约车、代驾
  • 出租车只支持个垫管控客户（存在税损）且有白名单控制，如需使用请联系滴滴企业级开通

参数限制：

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


基本信息

HTTP URL

/river/Invoice/apply

HTTP Method

POST

权限要求


请求头

参数名称

参数值

Content-Type

application/json

请求参数

字段名

字段说明

字段类型

必填

备注

client_id

申请应用时分配的AppKey

string

Y

申请应用时分配的AppKey

access_token

授权后的access token

string

Y

授权后的access token

timestamp

当前时间戳

bigint

Y

当前时间戳

company_id

公司编号

string

Y

公司编号

settle_type

品类

int

N

品类 默认是网约车 1.网约车、40.新代驾 100.出租车

receiver_email

电子邮箱

string

Y

电子邮箱(接收电子发票)

invoice_title

发票抬头

string

N

发票抬头（普票必填，专票不填）

tax_registration_number

纳税人识别号

string

N

纳税人识别号（非必填）

invoice_qid

资质id

string

N

资质id（专票必填，普票不填），专票资质列表返回结果中的资质ID

invoice_type

发票类型

int

Y

发票类型4：数电普票，5：数电专票

invoice_content

发票内容

string

N

settle_type = 1，默认为 发票内容（*运输服务*客运服务费） ，其他品类无需填写

invoice_no

开票请求编号

string

Y

开票请求编号（接入方唯一标识）

invoice_no_process

处理标记

int

N

是否对invoice_no做处理 0 不处理 1 处理 默认是0

data

发票信息

string

Y

发票信息json数据{"total_price":"1000","orders":\[{"order_id":xxxx,"price":"20.00"},...\]} 最大500条

remark

备注

string

N

备注(长度限制：100个字符)

sign

签名

string

Y

签名


请求示例

curl -X POST -H "content-type:application/json" \
-d '{"client_id":"client_id_test","access_token":"c69340a883d3c87133793f71f6c960cbc7ae9284","timestamp":1583482495,"company_id":"12345678980","receiver_email":"11000005555@qq.com","invoice_type":3,"invoice_content":"*\u8fd0\u8f93\u670d\u52a1*\u5ba2\u8fd0\u670d\u52a1\u8d39","invoice_no":"125904356705555","data":"{\"total_price\":\"13\",\"orders\":[{\"order_id\":\"1125904356700122\",\"price\":\"13\"}]}","invoice_title":"1259xxxxxx555","tax_registration_number":"222259xxxx05555","sign":"9b4ef177eda266c8db62bdbc81d5c36f"}' \
https://api.es.xiaojukeji.com/river/Invoice/apply

响应参数

字段名

字段说明

字段类型

备注

errno

错误码

string

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

errmsg

错误信息

string

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

data

返回数据

object

返回数据

data

发票ID

data.invoice_id

发票id(同一发票id可能对应多张发票)


响应示例

正常示例

{
    "errno":0,
    "errmsg":"success",
    "data":{
        "invoice_id":"erpa4cfbd6185429572c2c92ba5614a2bc4"
    }
}

异常示例


错误码

通用错误解决方案

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

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

51100,51102(不满足开票要求(原因可能是:xxx))

xxx可能是：

  1. 存在金额不符订单
  2. 该订单开票金额确实与订单支付金额不符
  3. 该订单发生了退款，但是开票时的开票金额没有减去退款金额(检查方法：调用订单详情接口重新拉一下订单，检查是否发生退款)
  4. 存在实际可开票金额为零的订单
  5. 订单可能发生全部退款(检查方法：调用订单详情接口重新拉一下订单，检查支付金额与退款金额是否相等，如果相等则表示全额退款)
  6. 不支持非个垫管控的出租车订单开票
  7. 存在非支付订单
  8. 括号后面列举的订单还没有支付，需要支付后才能开票
  9. 存在已开票订单
  10. 括号后面列举的订单已经开过票，不能再开

版本记录

日期

更新人

更新内容

上线时间

2024.01.29

陈继诗

迁移文档


2024.04.12

魏正龙

迁移文档：增加settle_type字段

2024.04.12

2024.05.22

冯海锋

新增字段invoice_no_process

2024.05.22

2024.09.01

魏正龙

下掉 receiver、receiver_address 、receiver_phone,invoice_type 只支持 4,5, receiver_mail 必填

2024.09.01

2024.11.12

戴松

补充说明出租车个垫开票有白名单

2024.01.26

2025.1.8

戴松

invoice_content改为非必填，并将描述从‘发票内容（*运输服务*客运服务费） 此为唯一默认值，不能变更’ 改为 ‘settle_type = 1，默认为 发票内容（*运输服务*客运服务费） ，其他品类无需填写’

2024.11.15