响应格式与错误码
统一响应结构
所有接口返回 application/json，结构如下：
| 字段 |
类型 |
说明 |
| code |
int |
结果码，1 表示成功，0 表示暂无数据或处理中，负数表示失败 |
| message |
string |
结果描述 |
| content |
object / array / string |
业务数据，没有数据时不返回该字段 |
json
{
"code": 1,
"message": "提交成功",
"content": "ORDER20260101"
}
分页接口在上述字段之外还会返回分页信息：
json
{
"code": 1,
"message": "获取成功",
"content": [],
"number": 0,
"size": 10,
"numberOfElements": 10,
"totalElements": 120,
"totalPages": 12,
"first": true,
"last": false
}
HTTP 状态码
| HTTP 状态 |
说明 |
| 200 |
请求受理成功；code 为 1 表示成功，0 表示暂无数据 |
| 400 |
参数错误或业务校验失败，code 为负数，错误原因见 message |
| 404 |
接口路径不存在，返回 {"code":-1,"message":"...","path":"请求地址"} |
| 500 |
服务端异常，返回 {"code":-1,"message":"...","path":"请求地址"}，请携带 path 与时间联系技术支持 |
结果码
| code |
说明 |
| 1 |
成功 |
| 0 |
暂无数据（查询类接口无结果），或处理中（如登录 / 认证状态查询） |
| -1 |
业务错误，具体原因见 message |
| -3 |
团队账户余额不足 |
| -4 |
未选择企业 |
| -5 |
服务已过期 |
| -6 |
服务未订购 |
| -7 |
认证失败（appKey / appSecret 不正确） |
| -8 |
无团队信息 |
| -9 |
用户信息不存在 |
发票状态说明
查询与回调返回的发票对象中包含多个状态字段，含义如下。
state 基本状态
| 值 |
说明 |
| 0 |
审核中（控制台开启开票审核时，待审核或审核驳回，具体看 auditState） |
| 4 |
开票中（已提交电子税务局，等待开具结果） |
| 1 |
已开票 |
| 2 |
已作废（纸质发票） |
| 3 |
退票 |
| -1 |
开票失败，原因见 failMsg |
| -9 |
放弃开票 |
auditState 审核状态
printState 开票中状态
| 值 |
说明 |
| 0 |
待开票 |
| 1 |
已开票 |
| 2 |
其他途径开票中 |
redState 蓝票红冲状态
| 值 |
说明 |
| 0 |
未红冲 |
| 1 |
红冲中 |
| 2 |
已红冲 |
| 3 |
红冲审核中 |
| 4 |
部分红冲 |
| -1 |
红冲失败 |
cancelState 纸票作废状态
| 值 |
说明 |
| 0 |
未作废 |
| 1 |
作废中 |
| 2 |
已作废 |
| 3 |
作废审核中 |
| -1 |
作废失败 |
判断开票结果
判断一张蓝票是否开具成功，以 state == 1 为准；electronicInvoiceUrl（PDF）、electronicInvoiceOfd、electronicInvoiceXml、downloadUrl（交付页）等文件字段在开票成功后返回。
常见错误信息
| message |
原因与处理 |
| 密钥不能为空 / 认证失败 |
鉴权参数缺失或错误，见 鉴权方式 |
| 缺少外部订单号 |
outOrderNo 必填 |
| 该外部订单号已存在 |
同一企业内 outOrderNo 已开过票；只有开票失败、待审核、审核驳回、已红冲的订单号允许再次提交 |
| 请不要瞬间重复提交同一外部订单号 |
同一 outOrderNo 在 30 秒内重复提交 |
| 请不要连续访问接口，建议使用回调接口 |
同一订单号 3 秒内重复查询，请改用 回调通知 |
| 非法发票类型category |
category 不在可选值范围内，见 开具发票 |
| 个人不允许开具专票，务必传入企业税号 |
type 为个人时不能开专用发票 |
| 纳税人识别号长度不正确 |
税号长度须为 15、17、18、19 或 20 位，且不能包含空格 |
| 纳税人识别号不能有小写字母 |
税号须全部大写 |
| 自己不能为自己开票 |
购买方税号与销售方税号相同 |
| 请输入邮箱 / 请输入手机号 |
控制台「开票参数」配置了邮箱 / 手机号必填 |
| 发票明细不能为空 / 发票明细不能超过500行 |
items 为空或超过 500 行 |
| xxx请设置编码规则或传入编码及税率 |
明细未传 no 与 taxRate，且控制台未配置匹配的税收分类编码规则 |
| 缺少含税单价 参数:price |
明细未传 sum 时必须传 price |
| 折扣金额必须是负数 |
discount 必须小于等于 0 |
| 开票金额不能小于等于0 / 低于最小开票金额xx元 / 超过最大开票金额xx元 |
发票总金额超出控制台「企业信息」配置的开票区间 |
| 非法发票ID参数 / 非法主键参数 |
id 不存在或不属于当前企业 |
| 非法参数 |
传入的资源不属于当前企业 |
| 助手不在线 |
开票助手（发票机器人）离线，需在控制台或 登录&认证卡片 完成登录 |
