1.03.发票开具(czlx-3)

测试环境(除税控、数电和扫码开票外的接口）

https://api-dev.piaozone.com/test

POST

全电接口生产环境把接口地址改成https://api.piaozone.com/bill-websocket/v3/invoicewebsocket/push?taxNo=xxxxxxxxxxxxxx&clientId=xxxxxxxxxxxxxxxxxxxxxxxx
全电接口测试环境把接口地址改成https://api-dev.piaozone.com/test/bill-websocket/v3/invoicewebsocket/push?taxNo=当前企业税号&clientId=企业对应的发票云ClientId的值&paperInvoiceFlag=1&debugOpenInvoice=1

1. 发票金额算法：

1.1 蓝票算法：

不含税金额(四舍五入,保留两位小数)= 含税金额/(1+税率)
税额= 含税金额-不含税金额
不含税总金额=各行不含税金额相加
总税额 = 价税合计-不含税总金额
最后一项税额 = 总税额-（前n项税额之和）

1.2 红票算法：

价税合计=取蓝票的价税合计
合计税额=取蓝票的合计税额
合计金额=取蓝票合计金额

2. 明细项:

不含税金额(四舍五入,保留两位小数)= 含税金额/(1+税率)
税额= 含税金额-不含税金额
最后一项不含税金额 = 合计金额-（前n项不含税金额之和)
最后一项税额 = 合计税额-（前n项税额之和）

3. 误差规则

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。

差额征税计算公式：不含税差额 = 不含税金额 - 扣除额；税额 = 不含税差额*税率。开具请求报文要按照上述计算公式计算税额，合计税额等，开票服务不进行相应计算，只进行误差校验。
图一：

图二：

请求参数

Query 参数

name

string

必需

clientsecret+税盘号(旧税盘开票)；数电票勿传该字段

reqid

string

必需

当前13位毫秒级时间戳加3位随机数字(总共16位)

taxNo

string

可选

企业税号，数电票必填

clientId

string

可选

cleintId，数电票必填

paperInvoiceFlag

string

可选

是否需要开数电纸质发票空或者0，开电票，如果1，可开纸票-对应的kpzl传0或2（非必填）

invoiceCopyType

string

可选

数电纸质发票类型（非必填）

示例值:

Header 参数

Content-Type

string

必需

示例值:

application/json

Body 参数application/json

czlx

enum<string>

固定为：3

必需

枚举值:

sfrz

object

身份认证

必需

client_id

string

由发票云分配的id

必需

client_secret

string

由发票云分配的密钥

可选

timestamp

string

时间戳

可选

sjd

object

发票相关信息

必需

fpqqlsh

string

可选

流水号相同流水号将返回上一次的开票结果

ddh

string

单据编号

可选

hsbz

string

必需

含税标识 0：不含税 1：含税。数电发票只支持0-不含税。

hzqrdbh

string

红字确认单编号

可选

kpzl

string

必需

发票类型 0：专用发票 2：普通纸质发票 41：卷式发票,51:电子发票,61:电子专票(税务ukey才能开具)，26，数电普票，27，数电专票

kplx

string

必需

开票类型 0：蓝子发票 1：红字发票

zsfs

string

必需

征收方式 0：普通征收 1：减按计增 2：差额征收

qdbz

string

可选

清单标志 0非清单开具 1清单开具；纸质发票时必填

string

可选

备注;税控限制230字节（一个汉字两个字节）；数电限制200字符（一个汉字算一个字符）

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

可选

购货方微信openid，后续可用于推送微信消息

ghf_dzdh

string

购货方地址电话

可选

ghf_yhzh

string

购货方银行账号

可选

gmfzrrbs

string

可选

购买方自然人标识，Y-是，N-否；默认N

kpy

string

开票员

必需

sky

string

可选

收款人（数电票显示在备注）

fhr

string

可选

复核人（数电票显示在备注）

hjbhsje

string

必需

开票合计金额（不含税

kphjse

string

开票合计税额

必需

jshjje

string

价税合计金额

必需

cezslxDm

string

可选

差额征税类型，01-差额征税-全额开票，02-差额征税-差额开票

kce

string

可选

合计扣除额差额征税时必填在差额征税类型‘cezslxDm’为01时应为0

cepzmxList

array [object {9}]

可选

差额扣除额清单在差额征税类型‘cezslxDm’为02差额开票时必填

tdyslxDm

string

可选

特定业务类型（数电票） 01：成品油发票02：稀土发票03：建筑服务发票04：货物运输服务发票05：不动产销售服务发票06：不动产租赁服务发票07：代收车船税08：通行费09：旅客运输服务发票10：医疗服务（住院）发票11：医疗服务（门诊）发票12：自产农产品销售发票 14：机动车15：二手车16：农产品收购发票17：光伏收购发票18：卷烟发票

bdczyTdys

object

可选

不动产经营租赁服务信息，特定业务类型为06时必填

bdcTdys

object

可选

不动产销售服务信息，特定业务类型为05时必填

lkysList

array [object {8}]

可选

旅客运输服务特定信息，特定业务类型为09时必填，但行数可为0即空数组[]

jzfwTdys

object

可选

建筑服务信息，特定业务类型为03时必填

hwysfwdzfpmxbList

array [object {5}]

可选

货物运输服务，特定业务类型为04时必填

items

array [object {12}]

必需

发票明细行信息差额征税与特定业务类型为:03建筑服务、06不动产经营租赁、09旅客运输服务时明细行数量限制为1

ghf_email

string

可选

购货方邮箱地址，可用于发送邮件

sgfp

string

可选

特殊票种标识（非数电） 1：农产品销售 2：农产品收购 8：成品油 11：卷烟类 18：机动车

hcyy

string

可选

红冲原因 1:销货退回 2:开票有误 3:服务中止 4:销售折让,非专票红冲必填

dylppz

string

可选

对应蓝票票种 2:普通发票 41:卷票 51:电子普通发票 999:其他普通发票(如通行费发票),非专票红冲必填

dylpkprq

string

可选

对应蓝票开票日期 yyyyMMdd 如20211230,非专票红冲必填

sfzsgmfyhzh

string

可选

是否展示购买方银行账号，默认为空不展示：枚举值：Y:是 N:否

sfzsxsfyhzh

string

可选

是否展示销售方银行账号，默认为空不展示：枚举值：Y:是 N:否

ncpsgzjlx

string

可选

证件类型- 特定业务类型为农产品收购时必传：
枚举值：'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': '其他个人证件'

kjly

string

可选

放弃享受减按1%征收率原因，非必填，注释：小规模纳税人开具1%税率时必填

jazslxDm

string

减按征税类型

可选

sfzsxsfdzdh

string

可选

是否展示销售方地址电话，默认为空不展示：枚举值：Y:是 N:否

sfzsgmfdzdh

string

可选

是否展示购买方地址电话，默认为空不展示：枚举值：Y:是 N:否

fjys

array [object {3}]

附加要素

可选

fjysmc

string

附加要素名称

可选

fjyslx

string

附加要素类型

可选

fjysnr

string

附加要素内容

可选

示例

{
    "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"
        }
    ]
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api-dev.piaozone.com/test/?name=&reqid=&taxNo=&clientId=&paperInvoiceFlag=&invoiceCopyType=2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
        }
    ]
}'

返回响应

🟢200成功

application/json

Body

errcode

string

0：成功

必需

description

string

描述

必需

ddh

string

必需

订单号，请求中的流水号(fpqqlsh)为20位时ddh与流水号相同，否则将生成一个新的ddh

business_id

string

必需

单据编号，和请求信息中的ddh一致

is_duplicate

boolean

必需

是否是重复流水号，若是则会返回上一次的开票结果

device_info

object

开票设备信息对象

必需

card_no

string

必需

税控设备编号（税盘上带有xx-的一串数字，card_no不带'xx-'字符）

taxcode

string

税控设备税号

可选

subid

number

税控设备分机号

必需

lists

array [object {16}]

必需

兼容原因此处为数组，取第一条记录即可

description

string

可选

errcode

string

可选

seller_taxcode

string

销方税控设备编号

可选

seller_tax_subid

number

销方税控设备分机号

可选

fpdm

string

发票代码

可选

fphm

string

发票号码

可选

hjbhsje

string

可选

开票金额（不含税）。本字段税控票才返回，数电票不返回

jshjje

string

可选

价税合计。本字段税控票才返回，数电票不返回

kphjse

string

可选

税额。本字段税控票才返回，数电票不返回

kprq

string

可选

开票日期 yyyy-MM-dd hh:mm:ss

pdfurl

string

可选

税控设备是ukey开电子普票，或者发票是电子专票时该地址为预览地址，航信百旺开普通电票时则是PDF下载地址

bswj_pdf

string

可选

税局生成的PDF文件(电子专票\ukey开具的电子发票)

bswj_ofd

string

可选

税局生成的OFD源文件(数电票\电子专票\ukey开具的电子发票)

bswj_xml

string

可选

税局生成的XML源文件(数电票)

qdbz

string

可选

清单标识 0：非清单 1：清单

jym

string

校验码

可选

示例

{"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"}]}

修改于 2025-04-28 09:30:02

1.02 .读取票种信息(czlx-30)

1.04.发票作废(czlx-6)

1.03.发票开具(czlx-3)

1. 发票金额算法：#

1.1 蓝票算法：#

1.2 红票算法：#

2. 明细项:#

3. 误差规则#

4. 发票开具校验注意事项#

4.1 正数发票#

4.2 负数发票#

4.3 关于发票红冲#

4.4 税收分类编码#

5. 差额征税发票注意事项#

请求参数

示例代码

返回响应

1. 发票金额算法：

1.1 蓝票算法：

1.2 红票算法：

2. 明细项:

3. 误差规则

4. 发票开具校验注意事项

4.1 正数发票

4.2 负数发票

4.3 关于发票红冲

4.4 税收分类编码

5. 差额征税发票注意事项