发票云(标准版)API文档
1.03.发票开具(czlx-3)
POST/1. 发票金额算法：
1.1 蓝票算法：
不含税金额(四舍五入,保留两位小数)= 含税金额/(1+税率)
税额= 含税金额-不含税金额
不含税总金额=各行不含税金额相加
总税额 = 价税合计-不含税总金额
最后一项税额 = 总税额-（前n项税额之和）
1.2 红票算法：
价税合计=取蓝票的价税合计
合计税额=取蓝票的合计税额
合计金额=取蓝票合计金额
2. 明细项:
不含税金额(四舍五入,保留两位小数)= 含税金额/(1+税率)
税额= 含税金额-不含税金额
最后一项不含税金额 = 合计金额-（前n项不含税金额之和)
最后一项税额 = 合计税额-（前n项税额之和）
3. 误差规则
单行商品明细 |单价×数量-金额|<=0.01 元
正常行或被折扣行：|不含税金额×税率-税额|<=0.06元
折扣行：|不含税金额×税率-税额|<=0.01元
4. 发票开具校验注意事项
4.1 正数发票
正数发票合计金额>0 ；
价税合计=合计金额+合计税额；
开票合计金额 与 明细行所有金额加起来要一致；
开票合计税额 与 明细行所有税额加起来要一致；
除折扣行外，正数发票的商品行金额必须大于0 ；
正数发票每行商品行金额均不能为0，税额不能为负数 ；
折扣行金额不能大于被折扣行金额。多行折扣情况下，折扣行金额不能大于各被折扣行金额之和。
正数发票金额为负的商品行（即折扣行），其上一行商品金额必须为正。
单价和数量同时为空，或都不能为空 ；
金额、税额、数量、单价必须是合法数字 ；
折扣行税率必须与被折扣行税率相同。多行折扣情况下，各被折扣行税率相同，且与折扣行税率相同。
4.2 负数发票
负数发票合计金额<0 ；
价税合计=合计金额+合计税额；
开票合计金额 与 明细行所有金额加起来要一致；
开票合计税额 与 明细行所有税额加起来要一致；
负数发票的商品行金额必须小于0，税额不能为正数；
单价和数量同时为空，或都不能为空 ；
金额、税额、数量、单价必须是合法数字
4.3 关于发票红冲
提示：本节内容适用税控票，数电票仅做参考
4.3.1. 开具负数增值税普通发票，必须在备注中注明 对应正数发票代码:XXXXXXXXXX 号码:YYYYYYYY 字样，其中X为发票左上角10位或 12位代码数字，Y为发票右上角 8 位号码数字
4.3.2. 开具负数增值税专用发票，必须在备注中注明开具红字增值税专用发票信息表编号XXXXXXXXXXXXXXXX，其中 X 为信息表编号。同时，数量、金额、税额为负数
4.3.3. 开具货物运输发票的负数票备注中注明开具红字货物运输业增值税专用发票信息表编号
XXXXXXXXXXXXXXX，其中X 为信息表编号。
4.3.4. 开具机动车销售统一发票的负数票需在备注中注明对应正数发票代
码:XXXXXXXXXX 号码:YYYYYYYY字样，其中“X”为发票左上角10 位
或12 位代码数字，“Y”为发票右上角8 位号码数字。
4.4 税收分类编码
说明：商品和服务税收分类编码，详细编码信息可参考开票软件中的编码查询
| API接口字段 | 是否必须 | 字段描述 | 字段解释 |
|---|---|---|---|
| ssflbm | 是 | 商品编码 | 有税务局统一规范的商品与服务代码 |
| kce | 否 | 扣除额 | 对于征税对象全部数额中扣除的一定数额 |
| lslbs | 否 | 零税率标识 | 空值->普通非零税率；0->出口退税; 1->免税; 2->不征收; 3->普通零税率 |
| qyzbm | 否 | 企业自编码 | 由企业自定义的编码 |
| ssyhzc | 是 | 优惠政策标识 | 0->不享受优惠政策，1->享受优惠政策 |
| ssyhzcnr | 否 | 优惠政策内容 | 具体的优惠政策内容 当优惠政策标识为1时，必须填写优惠政策的具体内容 |
示例
null指代空值（以下表格不涵盖所有情况，只做示例作用）
| 类型 | 零税率标识 | 优惠政策标识 | 优惠政策内容 |
|---|---|---|---|
| 普通非零税率 | null | 0 | null |
| 普通零税率（税率=0） | 3 | null | null |
| 免税（税率=0） | 1 | 1 | 免税 |
| 出口退税（税率=0） | 0 | 1 | 出口退税 |
5. 差额征税发票注意事项
- 如果BMB_BBH不为空，并且第一行商品明细中KCE不为空，则认为是差额征税发票。
- 差额征税蓝字发票：只允许一条商品行，如果存在折扣行，则最多两条。
- 差额征税红字发票：只允许一条商品行。
- 差额征税蓝字发票：第一行商品明细中KCE不能为负数，并且不能大于第一行商品的不含税金额。
- 差额征税红字发票：第一行商品明细中KCE不能为正数，并且不能大于第一行商品的不含税金额。
- 差额征税蓝字发票：备注中要增加“差额征税：20.00。”字样，如图1。
- 差额征税红字发票：备注中要增加“差额征税。”字样，如图2。
- 差额征税计算公式：不含税差额 = 不含税金额 - 扣除额； 税额 = 不含税差额*税率。 开具请求报文要按照上述计算公式计算税额，合计税额等，开票服务不进行相应计算，只进行误差校验。
图一：
图二：
请求参数
clientsecret+税盘号(旧税盘开票)；数电票勿传该字段
当前13位毫秒级时间戳加3位随机数字(总共16位)
企业税号，数电票必填
cleintId，数电票必填
是否需要开数电纸质发票 空或者0，开电票，如果1，可开纸票-对应的kpzl传0或2（非必填）
数电纸质发票类型（非必填）
流水号 相同流水号将返回上一次的开票结果
含税标识 0：不含税 1：含税。数电发票只支持0-不含税。
发票类型 0：专用发票 2：普通纸质发票 41：卷式发票,51:电子发票,61:电子专票(税务ukey才能开具)，26，数电普票，27，数电专票
开票类型 0：蓝子发票 1：红字发票
征收方式 0：普通征收 1：减按计增 2：差额征收
清单标志 0非清单开具 1清单开具；纸质发票时必填
备注;税控限制230字节（一个汉字两个字节）；数电限制200字符（一个汉字算一个字符）
原发票代码。开具税控红字发票必填。
原发票号码。红字发票必填。
销售方地址；开具数电票必传、税控非必传
销售方电话；开具数电票必传、税控非必传
销售方银行账号；开具数电票必传、税控非必传
购货方纳税人识别号；专票为必填
购货方手机号，可用于发送短信通知
购货方微信openid，后续可用于推送微信消息
购买方自然人标识，Y-是，N-否；默认N
收款人（数电票显示在备注）
复核人（数电票显示在备注）
开票合计金额（不含税
差额征税类型，01-差额征税-全额开票，02-差额征税-差额开票
合计扣除额 差额征税时必填 在差额征税类型‘differenceTaxType’为01时应为0
差额扣除额清单 在差额征税类型‘cezslxDm’为02差额开票时必填
特定业务类型（数电票） 01：成品油发票02：稀土发票03：建筑服务发票04：货物运输服务发票05：不动产销售服务发票06：不动产租赁服务发票07：代收车船税08：通行费09：旅客运输服务发票10：医疗服务（住院）发票11：医疗服务（门诊）发票12：自产农产品销售发票 14：机动车15：二手车16：农产品收购发票17：光伏收购发票18：卷烟发票
不动产经营租赁服务信息，特定业务类型为06时必填
不动产销售服务信息，特定业务类型为05时必填
旅客运输服务特定信息，特定业务类型为09时必填，但行数可为0即空数组[]
建筑服务信息，特定业务类型为03时必填
货物运输服务，特定业务类型为04时必填
发票明细行信息 差额征税与特定业务类型为:03建筑服务、06不动产经营租赁、09旅客运输服务时明细行数量限制为1
购货方邮箱地址，可用于发送邮件
特殊票种标识（非数电） 1：农产品销售 2：农产品收购 8：成品油 11：卷烟类 18：机动车
红冲原因 1:销货退回 2:开票有误 3:服务中止 4:销售折让,非专票红冲必填
对应蓝票票种 2:普通发票 41:卷票 51:电子普通发票 999:其他普通发票(如 通行费发票),非专票红冲必填
对应蓝票开票日期 yyyyMMdd 如20211230,非专票红冲必填
是否展示购买方银行账号，默认为空不展示： 枚举值：Y:是 N:否
是否展示销售方银行账号，默认为空不展示：枚举值：Y:是 N:否
证件类型- 特定业务类型为农产品收购时必传：
枚举值：'101': '组织机构代码证', '102': '营业执照', '103': '税务登记证', '199': '其他单位证件', '201': '居民身份证', '202': '军官证', '203': '武警警官证', '204': '士兵证', '205': '军队离退休干部证', '206': '残疾人证', '207': '残疾军人证（1-8级）', '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': '中华人民共和国台湾居民居住证', '239': '《中华人民共和国外国人工作许可证》（A类）', '240': '《中华人民共和国外国人工作许可证》（B类）', '241': '《中华人民共和国外国人工作许可证》（C类）', '291': '出生医学证明', '299': '其他个人证件'
放弃享受减按1%征收率原因，非必填，注释：小规模纳税人开具1%税率时必填
是否展示销售方地址电话，默认为空不展示： 枚举值：Y:是 N:否
是否展示购买方地址电话，默认为空不展示：枚举值：Y:是 N:否
{
"czlx": "3",
"sfrz": {
"client_id": "string",
"client_secret": "string",
"timestamp": "string"
},
"sjd": {
"fpqqlsh": "string",
"ddh": "string",
"hsbz": "string",
"hzqrdbh": "string",
"kpzl": "string",
"kplx": "string",
"zsfs": "string",
"qdbz": "string",
"bz": "string",
"yfpdm": "string",
"yfphm": "string",
"xhf_nsrsbh": "string",
"xhf_mc": "string",
"xhf_dz": "string",
"xhf_dh": "string",
"xhf_yhzh": "string",
"ghf_nsrsbh": "string",
"ghf_mc": "string",
"ghf_sj": "string",
"ghf_openid": "string",
"ghf_dzdh": "string",
"ghf_yhzh": "string",
"gmfzrrbs": "string",
"kpy": "string",
"sky": "string",
"fhr": "string",
"hjbhsje": "string",
"kphjse": "string",
"jshjje": "string",
"cezslxDm": "string",
"kce": "string",
"cepzmxList": [
{
"pzlx": "string",
"fphm": "string",
"fpdm": "string",
"zzfphm": "string",
"pzhm": "string",
"kjrq": "string",
"pzhjje": "string",
"bckcje": "string",
"bz": "string"
}
],
"tdyslxDm": "string",
"bdczyTdys": {
"cqzsh": "string",
"bdcdz": "string",
"bdcjtdz": "string",
"zlqq": "string",
"zlqz": "string",
"kdsbz": "string",
"dw": "string"
},
"bdcTdys": {
"wqhtbabh": "string",
"bdcdz": "string",
"bdcjtdz": "string",
"kdsbz": "string",
"tdzzsxmbh": "string",
"hdjsjg": "string",
"sjcjhsje": "string",
"cqzsh": "string",
"dw": "string"
},
"lkysList": [
{
"qyd": "string",
"ddd": "string",
"cxr": "string",
"cxrq": "string",
"sfzjlx": "string",
"sfzjhm": "string",
"jtgjlx": "string",
"dengj": "string"
}
],
"jzfwTdys": {
"jzfwfsd": "string",
"jzfwfsdjtdz": "string",
"jzxmmc": "string",
"tdzzsxmbh": "string",
"kdsbz": "string",
"kqysssxbyglbh ": "string"
},
"hwysfwdzfpmxbList": [
{
"qyd": "string",
"ddd": "string",
"ysgjzl": "string",
"ysgjhp": "string",
"yshwmc1": "string"
}
],
"items": [
{
"xmlx": "string",
"xmdw": "string",
"xmmc": "string",
"xmsl": "string",
"xmdj": "string",
"xmje": "string",
"sl": "string",
"ggxh": "string",
"se": "string",
"taxcode": {
"kce": "string",
"lslbs": "string",
"qyzbm": "string",
"ssflbm": "string",
"ssyhzc": "string",
"ssyhzcnr": "string"
},
"hh": "string",
"sm": "string"
}
],
"ghf_email": "string",
"sgfp": "string",
"hcyy": "string",
"dylppz": "string",
"dylpkprq": "string",
"sfzsgmfyhzh": "string",
"sfzsxsfyhzh": "string",
"ncpsgzjlx": "string",
"kjly": "string",
"jazslxDm": "string",
"sfzsxsfdzdh": "string",
"sfzsgmfdzdh": "string"
},
"fjys": [
{
"fjysmc": "string",
"fjyslx": "string",
"fjysnr": "string"
}
]
}示例代码
返回响应
订单号，请求中的流水号(fpqqlsh)为20位时ddh与流水号相同，否则将生成一个新的ddh
单据编号，和请求信息中的ddh一致
是否是重复流水号，若是则会返回上一次的开票结果
税控设备编号 （税盘上带有xx-的一串数字，card_no不带'xx-'字符）
兼容原因此处为数组，取第一条记录即可
开票金额（不含税）。本字段税控票才返回，数电票不返回
价税合计。本字段税控票才返回，数电票不返回
税额。本字段税控票才返回，数电票不返回
开票日期 yyyy-MM-dd hh:mm:ss
税控设备是ukey开电子普票，或者发票是电子专票时该地址为预览地址，航信百旺开普通电票时则是PDF下载地址
税局生成的PDF文件(电子专票\ukey开具的电子发票)
税局生成的OFD源文件(数电票\电子专票\ukey开具的电子发票)
税局生成的XML源文件(数电票)
清单标识 0：非清单 1：清单
{
"business_id": "",
"ddh": "3973283AC7B5884196D8",
"description": "开具成功",
"device_info": {
"card_no": "661532817749",
"subid": 0,
"taxcode": "440301999999030"
},
"errcode": "0",
"is_duplicate": false,
"lists": [
{
"description": "开具成功",
"errcode": "4011",
"fpdm": "044031800105",
"fphm": "00412435",
"hjbhsje": "100.00",
"jshjje": "113.00",
"jym": "76820754360221005394",
"kphjse": "13.00",
"kprq": "2021-09-22 16:12:59",
"pdfurl": "",
"qdbz": "0"
}
]
}