发票开具接口

需授权 2019/7/22 预计阅读时间: 58 分钟

公共参数

名称 说明
appCode 由电子发票平台分配的 appCode
cmdName chinaeinv.api.invoice.v3.kp_async
sign 数字签名字符串，调用方需要使用电子发票服务平台􏰀供的数字证书对 请求报文进行签名并作 Base64 编码，生成数字签名字符串

请求参数说明

名称 类型 必传 长度 描述
serialNo String 是 50 操作流水号。传入重复的操作流水号则认为是重复操作。
postTime String 是 19 请求发送时间。格式为yyyy-MM-dd HH:mm:ss。
order Object 是   订单信息。
 ├ orderNo String 是 50 订单编号。
 ├ account String 否 100 消费者的用户名。
 ├ address String 否 250 货物配送地址。
 ├ tel String 否   消费者电话号码。手机号码或区号-固定电话号码。
 └ email String 否   消费者电子邮件地址。电子邮件格式。
invoice Object 是   发票信息。
 ├ taxpayerCode String 是 20 销货方纳税人识别号。
 ├ taxpayerName String 否 100 销货方纳税人名称
 ├ taxpayerAddress String 否 79 销货方地址。如果填写则使用填写的信息，否则使用纳税人注册时预留的信息。
 ├ taxpayerTel String 否 20 销货方电话。
 ├ taxpayerBankName String 否 69 销货方开户银行。
 ├ taxpayerBankAccount String 否 30 销货方银行账号。
 ├ customerName String 是 100 购货方名称，即发票抬头。
 ├ customerCode String 否 20 购货方纳税人识别号或者个人身份证号
 ├ customerAddress String 否 79 购货方地址。
 ├ customerTel String 否 20 购货方电话。
 ├ customerBankName String 否 69 购货方开户银行。
 ├ customerBankAccount String 否 30 购货方银行账号。
 ├ invoiceType String 否 2 开票类型。p:电子增值税普通发票（默认）； ps:电子收购发票； py：成品油 ；q:全电普票(数电普票)；w:全电专票（数电专票）；qs:全电收购
 ├ shopCode String 否 50 店铺编号
 ├ shopName String 否 50 店铺名称
 ├ payType String 否 50 支付方式
 ├ payBillNo String 否 50 支付流水号
 ├ drawer String 是 8 开票人。
 ├ payee String 否 8 收款人。
 ├ reviewer String 否 8 复核人。
 ├ totalAmount Number 是 18(整)2(小) 税价合计金额。必须大于等于0.01元；必须等于发票明细合计金额；必须小于等于在税务局进行票种核定时确定的单张发票开票限额。
         
 ├ remark String 否 130 发票备注。增值税发票备注长度为130；全电发票（数电发票）长度为400；
 └ items Array 是 100 发票项目明细列表。每张发票最多一百条。
  ├ type String 是 1 发票行性质 0 正常行、1 折扣行、2 被 折扣行。
  ├ code String 否 50 商品编码。
  ├ name String 是 90 商品名称。可在每一行商品下加入折扣行,折扣行商品名称与被折扣商品名称一致,金额栏以负数填写,税率与被折扣行商品税率相同,其它栏不填写。
  ├ spec String 否 40 规格型号。
  ├ price Number 否 18(整)6(小) 商品单价。必须等于amount/quantity的四舍五入值。
单价和数量为组合校验，任何一方为空，则另外一方也必须也为空
  ├ quantity Number 否 18(整)6(小) 数量。必须大于等于0.000001。
单价和数量为组合校验，任何一方为空，则另外一方也必须也为空
  ├ uom String 否 20 单位。
  ├ taxRate Number 是 6(小) 税率。只能为0、 0.01、 0.03、0.04、0.06、0.09、0.10、0.11、0.13、0.16、0.17。
  ├ amount Number 是 18(整)2(小) 税价合计金额。
  ├ catalogCode String 是 50 商品分类编码。目前的分类编码为19位，不足19位的在后面补0。
  ├ preferentialPolicyFlg String 否 1 优惠政策标识。0:不使用,1:使用。
  ├ addedValueTaxFlg String 否 50 增值税特殊管理（当优惠政策标识为1时必填）。
  └ zeroTaxRateFlg String 否 1 零税率标识。1:免税,2:不征税,3:普通零税率。税率为零的情况下，如果不传，则默认为1:免税。
 ├ tdyslxdm String 否 2 特定业务必填，传值特定要素编码值（比如货物运输服务，传值为04）,03：建筑服务发票;04：货物运输服务发票、06：不动产经营租赁服务、09：旅客运输服务发票
 └ jzfw Object 否   建筑服务必填
  ├ jzfwfsd String 否 50 建筑服务发生地，建筑服务必填
  ├fsdxxdz String 否 200 发生地详细地址，建筑服务必填
  ├jzxmmc String 否 50 建筑项目名称，建筑服务必填
  ├kdsbz String 否 50 跨地市标志，建筑服务必填（Y/N）
  ├tdzzsxmbh String 否 50 土地增值税项目编号
 └ bdcjyzlfw Object 否   不动产经营租赁服务必填
  ├fwcqzshm String 否 50 房屋产权证书/不动产权证号码，不动产经营租赁服务必填
  ├ bdcdz String 否 200 不动产地址，不动产经营租赁服务必填
  ├bdcxxdz String 否 200 不动产详细地址，不动产经营租赁服务必填
  ├zlqq String 否 50 租赁期起，不动产经营租赁服务必填 格式:yyyyMMdd
若开具发票的税收分类编码为3040502020200000000(停车费)的商品时，zlqq（租赁期起）和zlqz(租赁期止)两个字段时间格式为yyyyMMddHHmm
  ├zlqz String 否 50 租赁期止，不动产经营租赁服务必填 格式:yyyyMMdd
若开具发票的税收分类编码为3040502020200000000(停车费)的商品时，zlqq（租赁期起）和zlqz(租赁期止)两个字段时间格式为yyyyMMddHHmm
   ├cph String 否 50 车牌号，zlqq（租赁期起）和zlqz(租赁期止)两个字段时间格式为yyyyMMdd，车牌号字段不可用（非停车费不要传）
  ├kdsbz String 否 50 跨地市标志，不动产经营租赁服务必填 Y/N
  ├ mjdw String 否 50 面积单位，不动产经营租赁服务必填：平方米,亩,m²,平方千米,公顷,hm²,km²
 └ hwysfw Array 否   货物运输服务
  ├ ddd String 否 200 到达地，按行政区划名称填写，包括县（市、区）名称，可在县（市、区）后自主增添具体地址；
  ├qyd String 否 200 起运地，同到达地要求
  ├ysgjhp String 否 50 运输工具号牌，运输工具种类属于无牌号的工具种类时，需填写无；
  ├ysgjzl String 否 50 运输工具种类，铁路运输、公路运输、水路运输、航空运输、管道运输等种类之一
  ├yshwmc String 否 50 运输货物名称
 └ lkysfw Array 否   旅客运输服务必填
  ├cxr String 是   出行人
  ├cxrzjlx String 是   出行人证件类型 ：
“组织机构代码证”: “101”, “营业执照”: “102”, “税务登记证”: “103”, “其他单位证件”: “199”, “居民身份证”: “201”, “军官证”: “202”,”武警警官证”: “203”,”士兵证”: “204”,”军队离退休干部证”: “205”,”残疾人证”: “206”,”残疾军人证（1-8级）”: “207”,”外国护照”: “208”,”港澳居民来往内地通行证”: “210”,”中华人民共和国往来港澳通行证”: “212”,”台湾居民来往大陆通行证”: “213”,”大陆居民往来台湾通行证”: “214”,”外国人居留证”: “215”,”外交官证”: “216”,”使（领事）馆证”: “217”,”海员证”: “218”,”香港永久性居民身份证”: “219”,”台湾身份证”: “220”,”澳门特别行政区永久性居民身份证”: “221”,”外国人身份证件”: “222”,”就业失业登记证”: “224”,”退休证”: “225”,”离休证”: “226”,”中国护照”: “227”,”城镇退役士兵自谋职业证”: “228”,”随军家属身份证明”: “229”,”中国人民解放军军官转业证书”: “230”,”中国人民解放军义务兵退出现役证”: “231”,”中国人民解放军士官退出现役证”: “232”,”外国人永久居留身份证（外国人永久居留证）”: “233”,”就业创业证”: “234”,”香港特别行政区护照”: “235”,”澳门特别行政区护照”: “236”,”中华人民共和国港澳居民居住证”: “237”,”中华人民共和国台湾居民居住证”: “238”,”《中华人民共和国外国人工作许可证》（A类）”: “239”,”《中华人民共和国外国人工作许可证》（B类）”: “240”,”《中华人民共和国外国人工作许可证》（C类）”: “241”,”医学出生证明”: “291”,”其他个人证件”: “299”
  ├cxrzjhm String 是   出行人证件号码
  ├cxrq String 是   出行日期 ，格式要求为：yyyy-MM-dd
  ├cfd String 是   出发地:
按行政区划名称填写，包括县（市、区）名称，可在县（市、区）后自主增添具体地址
  ├ddd String 是   到达地:
按行政区划名称填写，包括县（市、区）名称，可在县（市、区）后自主增添具体地址；
  ├ jtgjlx String 是   交通工具类型:
1:飞机、2:火车、3：长途汽车、4：公共交通、5：出租车、6：汽车、7：船舶、9：其他
  ├dengj String 否   等级:
若交通工具为火车、飞机、船舶，则该要素为必填；等级类型: (交通工具-飞机:经济舱、头等舱、公务舱),(交通工具-船舶:一等舱、二等舱、三等舱),(交通工具-火车:一等座、二等座、软席(软座、软卧)、硬席(硬座、硬卧))
notices Array 否 3 通知方式列表，最多3条。
 ├ type String 是   通知类型。短信：sms；电子邮件：email。
 └ value String 是   通知类型为短信时，必须为手机号码；通知类型为电子邮件时，必须为邮件地址。
extendedParams Object 否 20 扩展参数。一组Key-Value形式的数据，会在响应报文中回传给调用方，由调用者和瑞宏网双方根据实际情况协商使用。
dynamicParams Object 否   自定义参数。一组Key-Value形式的数据，key值：callbackUrl，Value为回调地址“http://wwww.***.com/test/invoice”

返回参数说明

名称 类型 描述
serialNo String 操作流水号。
postTime String 响应发送时间。格式为yyyy-MM-dd HH:mm:ss。
code String 处理结果代码。
message String 处理结果消息。

请求报文示例

{
	"serialNo": "操作流水号",
	"postTime": "请求发送时间。格式为yyyy-MM-dd HH:mm:ss。",
	"order": {
		"account": "消费者的用户名",
		"address": "货物配送地址",
		"email": "消费者电子邮件地址",
		"tel": "消费者电话号码",
		"orderNo": "订单编号"
	},
	"invoice": {
		"taxpayerCode": "销货方纳税人识别号",
		"taxpayerAddress": "销货方地址",
		"taxpayerTel": "销货方电话",
		"taxpayerBankName": "销货方开户银行",
		"taxpayerBankAccount": "销货方银行账号",
		"customerName": "购货方名称，即发票抬头",
		"customerCode": "购货方纳税人识别号",
		"shopCode": "站点/门店/店铺编号",
		"shopName": "站点/门店/店铺名称",
		"drawer": "开票人",
		"totalAmount": "税价合计金额",
		"remark": "发票备注",
		"customerAddress": "购货方地址",
		"customerTel": "购货方电话",
		"customerBankName": "购货方开户银行",
		"customerBankAccount": "购货方银行账号",
		"payee": "收款人",
		"reviewer": "复核人",
		"items": [{
			"amount": "税价合计金额",
			"code": "商品编码",
			"name": "商品名称",
			"price": "商品单价",
			"quantity": "数量",
			"taxRate": "税率",
			"uom": "单位",
			"type": "发票行性质",
			"spec": "规格型号",
			"catalogCode": "商品分类编码",
			"preferentialPolicyFlg": "优惠政策标识",
			"addedValueTaxFlg": "增值税特殊管理",
			"zeroTaxRateFlg": "零税率标识"
		}],
		"tdyslxdm ": "特定要素类型代码 ",
		"jzfw": {
			"jzfwfsd": "建筑服务发生地",
			"fsdxxdz": "发生地详细地址",
			"jzxmmc": "建筑项目名称",
			"kdsbz": "跨地市标志",
			"tdzzsxmbh": "土地增值税项目编号"
		},
		"bdcjyzlfw": {
			"fwcqzshm": "房屋产权证书/不动产权证号码",
			"bdcdz": "不动产地址",
			"bdcxxdz": "不动产详细地址",
			"zlqq": "租赁期起",
			"zlqz": "租赁期止",
			"kdsbz": "跨地市标志",
			"mjdw": "面积单位"
		},
		"hwysfw": [{
			"ddd": "到达地",
			"qyd": "起运地",
			"ysgjhp": "运输工具号牌",
			"ysgjzl": "运输工具种类",
			"yshwmc": "运输货物名称"
		}],
		"lkysfw": [{
			"cfd": "出发地",
			"cxr": "出行人",
			"cxrq": "2024-05-31",
			"cxrzjhm": "出行人证件号码",
			"cxrzjlx": "出行人证件类型",
			"ddd": "到达地",
			"dengj": "等级：经济舱",
			"jtgjlx": "交通工具类型：1"
		}]
	},
	"notices": [{
		"type": "通知类型",
		"value": "通知类型对应的值"
	}],
	"extendedParams": {
		"扩展参数1的key": "扩展参数1的value",
		"扩展参数2的key": "扩展参数2的value"
	},
	"dynamicParams": {
		"callbackUrl": "扩展参数1的value"
	}
}

响应报文示例

{
    "serialNo": "操作流水号",
    "postTime": "响应发送时间。格式为yyyy-MM-dd HH:mm:ss",
    "code": "处理结果代码",
    "message": "处理结果消息"
}

返回错误说明

代码 说明
0 处理成功。
1 系统内部错误，如出现该错误请及时联系电子发票服务平台。
2 参数校验未通过，详情请参考处理结果消息。
3 appCode不存在或数字证书不可用。
4 数字签名错误，请检查数字证书、字符编码格式等是否正确。
5 重复操作，即serialNo重复。
6 正在处理中。
400 纳税人不存在或不可用，可能是传入的纳税人识别号错误。
401 要冲红或者查询的发票不存在。

开票接口