1.01.托管开票接口

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

POST

/m5/bill/invoice/create

businessType全电开票扩展开全电时发票类型必填：1全电发票(普通发票)2全电发票(增值税专用发票)联云托管可以开纸普、电普、纸专、电专航信托管只能开普通电票

状态信息 ：
{"errcode":"0000","description":"成功","data":"整个发票数据"}
{"errcode":"0501","description":"发票开票数据为空"}
{"errcode":"0502","description":"发票数据解密异常"}
{"errcode":"0503","description":"请求流水号参数错误"}
{"errcode":"0504","description":"失败,票无忧无企业名称或纳税人识别号信息"}
{"errcode":"0505","description":"该流水号已经存在"}
{"errcode":"0506","description":"特殊充红标记参数错误"}
{"errcode":"0507","description":"操作代码参数错误"}
{"errcode":"0508","description":"含税标记不能为空"}
{"errcode":"0509","description":"含税标记错误"}
{"errcode":"0510","description":"清单标记为1，清单项目名称不能为空"}
{"errcode":"0511","description":"开票人不能为空"}
{"errcode":"0512","description":"商品编码长度必须为19位"}
{"errcode":"0513","description":"发票行性质参数错误,是否折扣"}
{"errcode":"0514","description":"优惠使用标识参数错误"}
{"errcode":"0515","description":"发票使用标记为1时，增值税特殊管理不能为空"}
{"errcode":"0516","description":"无此流水号对应发票"}
{"errcode":"0517","description":"此发票不是蓝票"}
{"errcode":"0518","description":"电票服务时间未开始或已过期"}
{"errcode":"0519","description":"电票订购发票的数量已经使用完"}
{"errcode":"0520","description":"开票方企业税号不能为空"}

1. 发票金额算法：

1.1 蓝票算法：

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

1.2 红票算法：

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

2. 明细项:

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

3. 误差规则

单行商品明细 |单价×数量-金额|<=0.01 元
|不含税金额×税率-税额|<=0.06元

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

4.1 正数发票

正数发票合计金额>0 ；
价税合计=合计金额+合计税额；
开票合计金额与明细行所有金额加起来要一致；
开票合计税额与明细行所有税额加起来要一致；
除折扣行外，正数发票的商品行金额必须大于0 ；
正数发票每行商品行金额均不能为0，税额不能为负数；
折扣行金额不能大于被折扣行金额。多行折扣情况下，折扣行金额不能大于各被折扣行金额之和。
正数发票金额为负的商品行（即折扣行），其上一行商品金额必须为正。
单价和数量同时为空，或都不能为空；
金额、税额、数量、单价必须是合法数字；
折扣行税率必须与被折扣行税率相同。多行折扣情况下，各被折扣行税率相同，且与折扣行税率相同。

4.2 负数发票

负数发票合计金额<0 ；
价税合计=合计金额+合计税额；
开票合计金额与明细行所有金额加起来要一致；
开票合计税额与明细行所有税额加起来要一致；
负数发票的商品行金额必须小于0，税额不能为正数；
单价和数量同时为空，或都不能为空；
金额、税额、数量、单价必须是合法数字

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

5.1 如果BMB_BBH不为空，并且第一行商品明细中KCE不为空，则认为是差额征税发票。

5.2 差额征税蓝字发票：只允许一条商品行，如果存在折扣行，则最多两条。

5.3 差额征税红字发票：只允许一条商品行。

5.4 差额征税蓝字发票：第一行商品明细中KCE不能为负数，并且不能大于第一行商品的不含税金额。

5.5 差额征税红字发票：第一行商品明细中KCE不能为正数，并且不能大于第一行商品的不含税金额。

5.6 差额征税蓝字发票：备注中要增加“差额征税：20.00。”字样，如图1。

5.7 差额征税红字发票：备注中要增加“差额征税。”字样，如图2。

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

图一：

图二：

请求参数

Query 参数

access_token

string

必需

访问token，获取方式请查阅《对接约定》

reqid

string

必需

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

示例值:

1624601109096123

Header 参数

Content-Type

string

必需

示例值:

application/json

Body 参数application/json

inventoryProjectName

string

可选

清单发票项目名称，需要打印清单时对应发票票面项目名称，清单标志 inventoryFlag为1时必填，为0不必处理

originalInvoiceNo

string

可选

(原)蓝票发票号码(开红票时候需要)

originalInvoiceCode

string

可选

(原)蓝票发票代码(开红票时候需要)

salerCardNumber

string

销方银行账号,

可选

salerCardName

string

销方银行名称

可选

salerPhone

string

销方电话

可选

salerAddress

string

销方地址

可选

salerAccount

string

可选

销方银行地址+银行账号

salerTaxNo

string

销方税号

必需

buyerAddress

string

可选

购方地址电话，buyerAddress和buyerFixedTelephone总长度不大于100

buyerTaxNo

string

购方纳税人识别号

可选

buyerFixedTelephone

string

可选

购方固定电话，buyerAddress和buyerFixedTelephone总长度不大于100

buyerName

string

购方名称

必需

buyerAccount

string

购方银行账号

可选

buyerEmail

object

购买方邮箱

可选

buyerMobilePhone

string

可选

购买方手机，移动电话

invoiceAmount

number

金额合计(不含税)

必需

remark

string

备注

可选

type

string

必需

开票类型 0蓝票，1红票

payee

string

收款人

可选

taxFlag

string

必需

含税标记 0:不含税1:含税

inventoryFlag

string

可选

清单标志， 0-普通电子发票1-普通电子发票(清单) 2-收购电子发票 3-收购电子发票(清单) 4-成品油电子发票(成品油无清单)

drawer

string

开票人

必需

reviewer

string

复核人

可选

serialNo

string

必需

流水号,发票云发票数据唯一值，长度不低于20，如果存在重复流水号，则返回上一次开票结果

totalAmount

number

价税合计(小写)

必需

totalTaxAmount

number

总税额

必需

purchaseFlag

string

可选

农产品收购发票标志，0:普通发票,2:农产品收购发票。非农产品收购发票可不填

redReason

string

可选

红冲原因,1:销货退回 2:开票有误 3:服务中止 4:销售折让开红票不填值系统默认填2，需要税局校验，测试环境填4

invoiceType

string

可选

全电必填：1全电发票(普通发票)，2，全电发票(增值税专用发票)，航信托管只支持电子普票，发票云联云托管支持发票类型：1普通电票，2，电子专票，3普通纸票，4纸质专票；不填，默认为1

items

array [object {14}]

必需

unitPrice

number

可选

单价（根据taxFlag确定是否含税）(小数点后6位,四舍五入)，和num同时存在或者同时为空

num

string

可选

数量（直接填写总价，不写数量和单价），和unitPrice同时存在或者同时为空

preferentialPolicy

string

可选

0(不使用)，1（使用）优惠政策

zeroTaxRateFlag

string

可选

零税率标识空：非零税率， 1：免税，2：不征税， 3 普通零税率不是必填

taxRate

number

可选

税率（折扣行税率与被折扣行税率一致），税局给每个商品都定义了对应的税率，不能随意填写，详情请咨询各自企业的财务人员

unit

string

单位

可选

vatException

string

可选

增值税特殊管理，当preferentialPolicy为1是必填

detailAmount

number

可选

总价（根据taxFlag确定是否含税）( 小数点后2位,以元为单位精确到分.等于=单价*数量,根据含税标志，确定此金额是否为含税金额)

specModel

object

规格型号

可选

discountType

string

可选

0 正常行、1 折扣行、2 被折扣行

goodsCode

string

可选

商品编码，税局给每个商品都定义了对应的编码，不能随意填写，详情请咨询各自企业的财务人员

taxAmount

number

可选

税额（计算税额请注意总价是否含税）(小数点后2位,以元为单位精确到分)

goodsName

string

可选

货物名称。如discountType =1，则此商品行为折扣行，此版本折扣行不允许多行折扣，折扣行必须紧邻被折扣行，项目名称必须与被折扣行一致。

deduction

string

可选

差额，差额存在的时候，detailAmount-deduction之后再去按照含税/不含税计算税额

businessType

string

可选

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

buildInfo

object

可选

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

simpleAddress

string

必需

建筑服务发生地：省市区县省市区县+具体地址长度限制为120

detailAddress

string

可选

具体地址省市区县+具体地址长度限制为120

buildingName

string

建筑项目名称

必需

landTaxNo

string

土地增值税项目编号

可选

crossCitySign

string

跨地（市）标志

必需

freightList

object

可选

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

startPlace

string

起运地省市区县

必需

endPlace

string

到达地省市区县

必需

transportType

string

运输工具种类

必需

licensePlate

string

运输工具牌号

必需

transportGoods

string

运输货物名称

必需

estateSaleInfo

object

可选

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

estateCode

string

可选

simpleAddress

string

必需

省市区县省市区县+具体地址长度限制为120

detailAddress

string

必需

具体地址：必须包含“街、路、村、乡、镇、道”等关键词之一省市区县+具体地址长度限制为120

crossCitySign

string

跨地（市）标志

必需

landTaxNo

string

土地增值税项目编号

可选

approvedPrice

string

核定计税价格

可选

actualTurnover

string

必需

实际成交含税金额：按核定计税价格征税的，必填

estateId

string

可选

房屋产权证书/不动产权证号

areaUnit

string

必需

面积单位㎡的ASCII码为\u33a1

estateLeaseInfo

object

可选

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

estateId

string

必需

房屋产权证书/不动产权证号，没有证书填写"无"

simpleAddress

string

必需

省市区县省市区县+具体地址长度限制为120

detailAddress

string

必需

具体地址：必须包含“街、路、村、乡、镇、道”等关键词之一省市区县+具体地址长度限制为120

startLeaseDate

string

必需

租赁期起日期格式"YYYYMMDD"

endLeaseDate

string

必需

租赁期止日期格式"YYYYMMDD"

crossCitySign

string

跨地（市）标志

必需

areaUnit

string

必需

面积单位㎡的ASCII码为\u33a1

differenceTaxType

string

必需

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

totalDeduction

number

必需

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

deductionList

array [object {9}]

必需

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

evidenceType

string

可选

凭证类型 01 全电发票、02 增值税专用发票、03 增值税普通发票、04 营业税发票、05 财政票据、06 法院裁决书、07 契税完税凭证、08 其他发票类、09 其他扣除凭证。

etaxInvoiceNo

string

数电发票号码

可选

invoiceCode

string

发票代码

可选

invoiceNo

string

发票号码

可选

evidenceNo

string

凭证号码

可选

invoiceDate

string

可选

开具日期日期格式"YYYY-MM-DD"

evidenceAmount

number

凭证合计金额

可选

deduction

number

本次扣除金额

可选

remark

string

备注

可选

travelerList

array [object {8}]

必需

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

traveler

string

出行人

必需

cardType

string

出行人证件类型

必需

cardNo

string

出行人证件号码

必需

travelDate

string

必需

出行日期日期格式"YYYY-MM-DD"

startPlace

string

出发地省市区县

必需

endPlace

string

到达地省市区县

必需

transportType

string

交通工具类型

必需

seatClass

string

必需

等级若交通工具类型选择“火车、飞机、船舶”，则等级为必填项，否则为非必填项

示例

{
  "inventoryProjectName": "string",
  "originalInvoiceNo": "string",
  "originalInvoiceCode": "string",
  "salerCardNumber": "string",
  "salerCardName": "string",
  "salerPhone": "string",
  "salerAddress": "string",
  "salerAccount": "string",
  "salerTaxNo": "string",
  "buyerAddress": "string",
  "buyerTaxNo": "string",
  "buyerFixedTelephone": "string",
  "buyerName": "string",
  "buyerAccount": "string",
  "buyerEmail": {},
  "buyerMobilePhone": "string",
  "invoiceAmount": 0,
  "remark": "string",
  "type": "string",
  "payee": "string",
  "taxFlag": "string",
  "inventoryFlag": "string",
  "drawer": "string",
  "reviewer": "string",
  "serialNo": "string",
  "totalAmount": 0,
  "totalTaxAmount": 0,
  "purchaseFlag": "string",
  "redReason": "string",
  "invoiceType": "string",
  "items": [
    {
      "unitPrice": 0,
      "num": "string",
      "preferentialPolicy": "string",
      "zeroTaxRateFlag": "string",
      "taxRate": 0,
      "unit": "string",
      "vatException": "string",
      "detailAmount": 0,
      "specModel": {},
      "discountType": "string",
      "goodsCode": "string",
      "taxAmount": 0,
      "goodsName": "string",
      "deduction": "string"
    }
  ],
  "businessType": "string",
  "buildInfo": {
    "simpleAddress": "string",
    "detailAddress": "string",
    "buildingName": "string",
    "landTaxNo": "string",
    "crossCitySign": "string"
  },
  "freightList": {
    "startPlace": "string",
    "endPlace": "string",
    "transportType": "string",
    "licensePlate": "string",
    "transportGoods": "string"
  },
  "estateSaleInfo": {
    "estateCode": "string",
    "simpleAddress": "string",
    "detailAddress": "string",
    "crossCitySign": "string",
    "landTaxNo": "string",
    "approvedPrice": "string",
    "actualTurnover": "string",
    "estateId": "string",
    "areaUnit": "string"
  },
  "estateLeaseInfo": {
    "estateId": "string",
    "simpleAddress": "string",
    "detailAddress": "string",
    "startLeaseDate": "string",
    "endLeaseDate": "string",
    "crossCitySign": "string",
    "areaUnit": "string"
  },
  "differenceTaxType": "string",
  "totalDeduction": 0,
  "deductionList": [
    {
      "evidenceType": "string",
      "etaxInvoiceNo": "string",
      "invoiceCode": "string",
      "invoiceNo": "string",
      "evidenceNo": "string",
      "invoiceDate": "string",
      "evidenceAmount": 0,
      "deduction": 0,
      "remark": "string"
    }
  ],
  "travelerList": [
    {
      "traveler": "string",
      "cardType": "string",
      "cardNo": "string",
      "travelDate": "string",
      "startPlace": "string",
      "endPlace": "string",
      "transportType": "string",
      "seatClass": "string"
    }
  ]
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api-dev.piaozone.com/test/m5/bill/invoice/create?access_token=&reqid=1624601109096123' \
--header 'Content-Type: application/json' \
--data-raw ''

返回响应

🟢200成功

application/json

Body

errcode

string

0000

必需

description

string

成功

必需

data

object

必需

invoiceCode

string

可选

发票代码,开全电发票时为空

invoiceNo

string

发票号码

必需

pdfUrl

string

pdf下载地址

必需

serialNo

string

开票流水号

必需

示例

{
  "errcode": "0000",
  "description": "发票开具成功",
  "data": {
    "pdfUrl": "https://down.szhtxx.cn/downPdf/440301999999980/2021/08/12/16485220210812151550.pdf",
    "sms_result": "推送失败：企业没有开通短信权限",
    "downloadUrl": "http://tax-test.piaozone.com/pdfPreview?serialNum=f2b20ed8855942749096ede62b7da23d",
    "email_result": "推送失败：企业没有开通邮件权限",
    "invoiceNo": "21435735",
    "invoiceCode": "044032000111",
    "serialNo": "16485220210812151550"
  }
}

🟠401失败

修改于 2024-06-05 08:21:31

开发指南

1.02.发票红冲接口(通过流水号做全额冲红)

1.01.托管开票接口

1. 发票金额算法：#

1.1 蓝票算法：#

1.2 红票算法：#

2. 明细项:#

3. 误差规则#

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

4.1 正数发票#

4.2 负数发票#

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

5.1 如果BMB_BBH不为空，并且第一行商品明细中KCE不为空，则认为是差额征税发票。#

5.2 差额征税蓝字发票：只允许一条商品行，如果存在折扣行，则最多两条。#

5.3 差额征税红字发票：只允许一条商品行。#

5.4 差额征税蓝字发票：第一行商品明细中KCE不能为负数，并且不能大于第一行商品的不含税金额。#

5.5 差额征税红字发票：第一行商品明细中KCE不能为正数，并且不能大于第一行商品的不含税金额。#

5.6 差额征税蓝字发票：备注中要增加“差额征税：20.00。”字样，如图1。#

5.7 差额征税红字发票：备注中要增加“差额征税。”字样，如图2。#

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

请求参数

示例代码

返回响应

1. 发票金额算法：

1.1 蓝票算法：

1.2 红票算法：

2. 明细项:

3. 误差规则

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

4.1 正数发票

4.2 负数发票

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

5.1 如果BMB_BBH不为空，并且第一行商品明细中KCE不为空，则认为是差额征税发票。

5.2 差额征税蓝字发票：只允许一条商品行，如果存在折扣行，则最多两条。

5.3 差额征税红字发票：只允许一条商品行。

5.4 差额征税蓝字发票：第一行商品明细中KCE不能为负数，并且不能大于第一行商品的不含税金额。

5.5 差额征税红字发票：第一行商品明细中KCE不能为正数，并且不能大于第一行商品的不含税金额。

5.6 差额征税蓝字发票：备注中要增加“差额征税：20.00。”字样，如图1。

5.7 差额征税红字发票：备注中要增加“差额征税。”字样，如图2。

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