电子发票
接入文档
接入文档 /发票开具/开具发票

开具发票

提交一张蓝字发票的开票申请。接口同步完成参数校验并返回受理结果，实际开票由 EasyAPI 异步对接电子税务局完成，开票结果通过 回调通知 推送，或按外部订单号 查询。

POST/invoice/make

请求参数

请求体为 JSON。

参数 类型 必填 说明
appKey string 条件必填 服务密钥 Key，与 appSecret 成对使用；传了 accessToken 时可不传
appSecret string 条件必填 服务密钥 Secret
accessToken string 条件必填 访问令牌，通过 获取访问令牌 接口获取；传了 accessToken 则无需 appKey / appSecret
taxNumber string 必填 企业纳税人识别号，指定本次操作的开票企业；必须是该密钥已关联的企业
outOrderNo string 必填 外部订单号（商户流水号），同一企业内唯一。开票失败、待审核、审核驳回的订单号允许再次提交并覆盖原申请；已红冲的订单号允许重新开票
type string 必填 抬头类型：个人、企业；数电发票还支持 自然人、个体工商户。个人 不能开具专用发票
category string 必填 发票类型，可选值见 发票类型
purchaserName string 必填 购买方名称，首尾不能有空格，不能包含换行、制表符、冒号
purchaserTaxpayerNumber string 条件必填 购买方纳税人识别号，type 为 企业 时必填；15 / 17 / 18 / 19 / 20 位，须大写，不能有空格。控制台可配置为所有抬头类型必填
purchaserAddress string 选填 购买方地址
purchaserPhone string 选填 购买方电话
purchaserBank string 选填 购买方开户行，不能包含空格、换行，不能全为数字
purchaserBankAccount string 选填 购买方银行账号，不能包含空格、换行，不能全为中文
ifPerson boolean 选填 购买方是否自然人（数电发票），默认 false
purchaserIdType string 选填 购买方证件类型代码（自然人），见 证件类型代码
purchaserIdNumber string 选填 购买方证件号码（自然人）
purchaserCountry string 选填 购买方国籍或地区（自然人）
showPurchaserAddressPhoneBank string 选填 是否在票面展示购买方地址电话、开户行账号：true / false
sellerName string 选填 销售方名称，不传使用控制台企业信息
sellerTaxpayerNumber string 选填 销售方纳税人识别号，不传使用控制台企业信息
sellerAddress string 选填 销售方地址
sellerPhone string 选填 销售方电话
sellerBank string 选填 销售方开户行
sellerBankAccount string 选填 销售方银行账号
showSellerAddressPhoneBank string 选填 是否在票面展示销售方地址电话、开户行账号：true / false
receiverName string 选填 收款人
checkerName string 选填 复核人
drawerName string 选填 开票人，不传使用控制台配置
mobile string 选填 购买方接收发票的手机号；控制台可配置为必填，开票成功后用于短信交付
email string 选填 购买方接收发票的邮箱；控制台可配置为必填，开票成功后用于邮件交付
remark string 选填 发票备注（票面右下角）
callbackUrl string 选填 开票结果回调地址，格式见 回调通知
username string 选填 用户标识（客户系统中的用户唯一编号）；使用 accessToken 鉴权时自动取令牌绑定的用户标识
chinaTaxMobile string 选填 指定开票员的电子税务局手机号，企业配置了多个开票员时使用
ifSkipAudit boolean 选填 控制台开启了「开票审核」时，传 true 跳过审核直接开票，默认 false
specificBusinessCode string 选填 特定业务代码：03 建筑服务、04 货物运输服务、05 不动产销售、06 不动产经营租赁服务、09 旅客运输服务、10 医疗服务（住院）、11 医疗服务（门诊）。仅数电发票（全电 开头的类型）生效
specificBusiness object / array 条件必填 特定业务内容，03、05、06、10、11 为 JSON 对象，04、09 为 JSON 数组。字段见 特定业务开票 与 医疗服务发票对接
differenceType string 选填 差额征税类型：01 差额征税-全额开票、02 差额征税-差额开票
differenceVouchers array 条件必填 差额扣除凭证列表，差额开票时传入，字段见 差额凭证
items array 必填 商品明细，最多 500 行，字段见 商品明细
extends array 选填 扩展信息，字段见 扩展信息

发票类型 category

值 说明
全电电子普通发票 数电发票（电子）普通发票，推荐
全电电子专用发票 数电发票（电子）增值税专用发票，推荐
增值税电子普通发票 税控电子普通发票
增值税电子专用发票 税控电子专用发票
增值税普通发票 纸质普通发票
增值税专用发票 纸质专用发票
数电普通发票 数电纸质普通发票
数电增值税专用发票 数电纸质专用发票
企业可开票类型

企业支持的发票类型及每种类型的开票金额区间在控制台「企业信息」中配置，不在范围内的类型或金额会被拒绝。二手车销售统一发票请使用 二手车发票开具 接口。

商品明细 items

参数 类型 必填 说明
lineNumber int 选填 行号，从 1 开始；医疗服务等特定业务需要用行号关联明细
name string 必填 商品或服务名称，不要自行拼接 *税收分类简称* 前缀，系统会根据税收分类编码自动补全；*简称*名称 合计不能超过 100 字节（1 个汉字 2 字节）
no string 条件必填 税收分类编码（19 位）。no 或 taxRate 任一未传时，按控制台「税收分类编码规则」用商品名称匹配，匹配不到则报错
taxRate double 条件必填 税率，如 0.13、0.06、0.03、0.01、0；规则同 no
number double 选填 数量，必须大于 0；只传 price 时默认为 1
price decimal 条件必填 含税单价；未传 sum 时必填
sum decimal 条件必填 含税金额；未传 price 时必填。两者都传时以 sum 为准；只传 sum 和 number 时自动计算 price
model string 选填 规格型号
unit string 选填 单位
discount decimal 选填 含税折扣金额，必须为负数，默认 0
zeroRateFlag int 选填 零税率标识：不传为非零税率，0 出口零税、1 免税、2 不征税、3 普通零税率
preferentialPolicyFlag int 选填 是否享受优惠政策：不传或 0 不享受，1 享受
preferentialPolicyName string 条件必填 优惠政策名称（增值税特殊管理），preferentialPolicyFlag 为 1 时必填

金额计算规则：

  • sum 为空时 sum = price × number，四舍五入保留两位小数。
  • 发票总金额 = 所有明细 sum 之和 + 所有明细 discount 之和（折扣为负数），总金额须在企业配置的开票区间内。
  • 单行明细 sum 不能为 0。

差额凭证 differenceVouchers

参数 类型 必填 说明
voucherType string 必填 凭证类型：数电票、增值税专用发票、增值税普通发票、营业税发票、财政票据、法院裁决书、契税完税凭证、其他发票类、其他扣除凭证
allElectronicInvoiceNumber string 条件必填 数电发票号码（20 位），凭证为数电票时填写
code string 条件必填 发票代码，凭证为税控发票时填写
number string 条件必填 发票号码，凭证为税控发票时填写
voucherNumber string 选填 凭证号码（非发票类凭证）
makeDate string 选填 开票 / 凭证日期，yyyy-MM-dd
price decimal 必填 凭证金额
difference decimal 必填 本次扣除金额
remark string 选填 备注

扩展信息 extends

参数 类型 必填 说明
fieldKey string 必填 扩展字段键
fieldName string 必填 扩展字段名称
fieldValue string 必填 扩展字段值

请求示例

json
{
  "appKey": "你的appKey",
  "appSecret": "你的appSecret",
  "taxNumber": "91320211MA1WML8X6T",
  "outOrderNo": "ORDER20260101001",
  "type": "企业",
  "category": "全电电子普通发票",
  "purchaserName": "深圳市腾讯计算机系统有限公司",
  "purchaserTaxpayerNumber": "91440300708461136T",
  "purchaserAddress": "",
  "purchaserPhone": "",
  "purchaserBank": "",
  "purchaserBankAccount": "",
  "mobile": "13800000000",
  "email": "finance@example.com",
  "remark": "订单号：ORDER20260101001",
  "callbackUrl": "https://www.example.com/invoice/callback",
  "items": [
    {
      "lineNumber": 1,
      "name": "技术服务费",
      "no": "3040201010000000000",
      "taxRate": 0.06,
      "unit": "次",
      "number": 1,
      "price": 1000,
      "sum": 1000,
      "discount": 0
    }
  ]
}

响应示例

受理成功时 content 为外部订单号：

json
{
  "code": 1,
  "message": "提交成功",
  "content": "ORDER20260101001"
}

参数校验失败时返回 HTTP 400：

json
{
  "code": -1,
  "message": "请输入购买方税号"
}
受理成功不等于开票成功

返回 提交成功 仅表示申请已受理。请通过 回调通知 或 查询发票 获取最终结果（state == 1 开票成功，state == -1 开票失败，failMsg 为失败原因）。

业务规则

  • 重复提交：同一 outOrderNo 30 秒内重复提交会返回 请不要瞬间重复提交同一外部订单号；已开票或开票中的订单号再次提交返回 该外部订单号已存在。
  • 覆盖开票：开票失败（state == -1）、待审核（state == 0）、审核驳回、助手离线时开票中的申请，再次提交同一 outOrderNo 会用新参数覆盖并重新开票。
  • 已红冲重开：蓝票已红冲（redState == 2）后，可用同一 outOrderNo 重新开具。
  • 开票审核：控制台开启「开票审核」后，申请先进入 state == 0 待审核状态，审核通过后开票；传 ifSkipAudit: true 可跳过审核。
  • 可开票金额校验：控制台配置了「实际可开票金额查询地址」时，开票前会向该地址查询用户可开票金额，不足时拒绝开票。
  • 税收分类编码规则：明细未传 no / taxRate 时，用商品名称匹配控制台配置的编码规则，建议接口直接传入编码与税率以减少匹配失败。
  • API 日志：每次调用的请求与响应都会记录在控制台「API 日志」中，便于排查。

错误信息

message 说明
缺少外部订单号 outOrderNo 为空
请选择个人或企业 type 为空
普通发票请选择个人、企业，数电发票请选择个人、自然人、个体工商户、企业 type 不在可选范围
发票类型category不能为空 / 非法发票类型category category 为空或不在可选范围
请输入购买方抬头 purchaserName 为空
购买方抬头开头末尾不能包含空格 / 不能包含换行符 / 不能包含冒号等无关内容 purchaserName 含非法字符
请输入购买方税号 企业抬头未传税号，或控制台配置了税号必填
纳税人识别号长度不正确 / 不能有小写字母 税号格式错误
自己不能为自己开票 购买方税号等于销售方税号
个人不允许开具专票，务必传入企业税号 个人抬头开专票
请输入邮箱 / 请输入手机号 / xxx邮箱格式不正确 / xxx手机号码格式不正确 交付信息缺失或格式错误
发票明细不能为空 / 发票明细不能超过500行 items 不合法
缺少商品名称:name 明细名称为空
折扣金额必须是负数 / 商品数量不能小于等于0 / 商品金额不能为0 / 缺少含税单价 参数:price 明细金额不合法
xxx请设置编码规则或传入编码及税率 税收分类编码匹配失败
税收分类编码名称商品名称，不能超过100个字节，1个汉字2个字节 商品名称过长
开票金额不能小于等于0 / 低于最小开票金额xx元 / 超过最大开票金额xx元 总金额超出企业开票区间
请不要瞬间重复提交同一外部订单号 / 该外部订单号已存在 重复提交
特定业务内容格式不正确 specificBusiness 不是合法 JSON 对象或数组
银行名称不能包括空格 / 银行账号不能全部是中文字符 等 购买方开户行信息格式错误
上一篇 响应格式与错误码下一篇 特定业务开票