发票查验接口 · API 文档
统一一个接口,覆盖全票种真伪查验。传入发票字段即可,系统按票种自动路由查验通道。
简介
发票查验接口通过传入发票要素进行真伪核验,验真后返回全票面信息与当日最新发票状态。支持单张与批量(单次最多 50 张)。 覆盖增值税发票(专票/普票/电子/卷式/通行费/机动车/二手车)、数电发票(电子及纸质)、区块链发票、通用电子发票等; 数据范围全国,可查验最近 5 年内开具的发票,平均响应 1–2 秒。
快速开始
- 1获取密钥 · 联系商务开通,获得 app_key 与 app_secret(在商户中心也可查看)。
- 2计算签名 · 每次请求按 sha256(app_key + 时间戳 + 请求体 + app_secret) 算出 X-Sign。
- 3发起查验 · 带上三个鉴权头,POST 发票字段到查验接口,即时返回查验结果。
完整示例(含签名,可直接运行)
APP_KEY="你的app_key"
APP_SECRET="你的app_secret"
BODY='{"fphm":"26112000002558759236","kprq":"2026-06-23","jshj":377}'
TS=$(date +%s)
# 签名 = sha256(appKey + 时间戳 + body + appSecret)
SIGN=$(printf "%s" "$APP_KEY$TS$BODY$APP_SECRET" | openssl dgst -sha256 | awk '{print $2}')
curl -X POST https://openapi.kailingteck.com/api/v1/verify \
-H "Content-Type: application/json" \
-H "X-App-Key: $APP_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Sign: $SIGN" \
-d "$BODY"鉴权
每次请求在请求头携带应用标识、时间戳与签名。
| 请求头 | 必填 | 说明 |
|---|---|---|
| X-App-Key | 必填 | 平台为你签发的应用标识 app_key |
| X-Timestamp | 必填 | Unix 秒级时间戳,与服务器时差需在 ±300 秒内 |
| X-Sign | 必填 | sha256(appKey + timestamp + body + appSecret) 小写 hex |
POST
发票查验接口
/api/v1/verify
请求参数
支持单张(扁平字段)或批量(cyList 数组)。不同票种填不同字段,见「票种传参对照」。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fphm | string | 必填 | 发票号码 |
| fpdm | string | 条件 | 发票代码(数电票无代码可不传) |
| kprq | string | 条件 | 开票日期 yyyy-MM-dd |
| je | number | 条件 | 不含税金额(专用发票类必填) |
| jym | string | 条件 | 校验码后 6 位(普通发票类必填;区块链发票为票面短码) |
| jshj | number | 条件 | 价税合计(数电票 / 通用电子发票必填) |
| xfsbh | string | 条件 | 销售方纳税人识别号(区块链 / 通用电子发票必填) |
| dq | string | 条件 | 地区码(仅特殊票种需要,见地区码表) |
| customReqId | string | 可选 | 调用方自定义请求 ID,便于对账与排障 |
| cyList | array | 可选 | 批量查验:多张票字段放入数组(单次最多 50 张);不传则按上述扁平字段查单张 |
请求示例(数电普票)
{
"fphm": "26112000002558759236",
"kprq": "2026-06-23",
"jshj": 377.00
}票种传参对照
照这张表传参即可,系统按地区码 dq 自动路由通道。
| 票种 | 必填字段 | dq | |
|---|---|---|---|
| 数电普通发票 | 发票号码 + 开票日期 + 价税合计 | 不用填 | 在沙箱试 → |
| 数电专用发票 | 发票号码 + 开票日期 + 价税合计 | 不用填 | 在沙箱试 → |
| 数电纸质(专用发票) | 发票代码 + 发票号码 + 开票日期 + 不含税金额 | 不用填 | 在沙箱试 → |
| 数电纸质(普通发票) | 发票代码 + 发票号码 + 开票日期 + 校验码后6位 | 不用填 | 在沙箱试 → |
| 增值税专用发票 | 发票代码 + 发票号码 + 开票日期 + 不含税金额 | 不用填 | 在沙箱试 → |
| 增值税普通发票 / 电子普票 / 通行费 | 发票代码 + 发票号码 + 开票日期 + 校验码后6位 | 不用填 | 在沙箱试 → |
| 区块链发票(深圳/北京/云南) | 发票代码 + 发票号码 + 销方税号 + 校验码 | 4403 / 1100 / 5300 | 在沙箱试 → |
| 通用电子发票(广东/浙江宁波) | 发票代码 + 发票号码 + 销方税号 + 价税合计 | 4400 / 3300 | |
| 车辆通行费发票(江苏) | 发票代码 + 发票号码 + 开票日期 + 不含税金额 | 3200 |
地区码 dq
| dq | 地区 | 适用 |
|---|---|---|
| (不传) | 全国 | 增值税 / 数电 / 数电纸质发票,默认通道 |
| 4403 | 深圳 | 区块链发票 |
| 1100 | 北京 | 区块链发票 |
| 5300 | 云南 | 区块链发票 |
| 4400 | 广东 | 通用电子发票 |
| 3300 | 浙江 / 宁波 | 通用电子发票 |
| 3200 | 江苏 | 车辆通行费发票 |
响应参数
外层信封与逐票公共字段所有票种一致;票面明细 result[].data 的字段随票种不同,下方按票种分组对照。
公共字段(所有票种一致)
| 字段 | 中文名 | 类型 | 说明 |
|---|---|---|---|
| code | 业务编码 | string | CYT_00000 为成功,其余见业务编码表 |
| msg | 提示信息 | string | |
| requestId | 请求标识 | string | 排障可提供 |
| data.verified | 是否查验通过 | boolean | 真票且要素一致 |
| data.channel | 路由通道 | string | 本次自动选用的查验通道 |
| data.result | 逐票结果 | array | 每张票一项 |
| result[].success | 该票是否成功 | boolean | |
| result[].fphm | 发票号码 | string | |
| result[].kprq | 开票日期 | string | |
| result[].fplx | 发票类型代码 | string | 见附录 |
| result[].times | 当日查验次数 | integer | |
| result[].data | 全票面明细 | object | 字段随票种不同,见下表 |
票面明细 result[].data(按票种对照)
增值税 / 数电发票(普票·专票·数电纸质)
| xfmc | 销售方名称 | string |
| xfsbh | 销售方税号 | string |
| gfmc | 购买方名称 | string |
| gfsbh | 购买方税号 | string |
| je | 不含税金额 | number |
| se | 税额 | number |
| jshj | 价税合计 | number |
| jshjcn | 价税合计(大写) | string |
| fpztDm | 发票状态代码 | string |
| bz | 备注 | string |
| hwxx[] | 货物/服务明细 | array |
| └ mc | 货物或服务名称 | string |
| └ slv | 税率 | number |
| └ se | 明细税额 | number |
| └ spbm | 税收分类编码 | string |
航空运输电子客票行程单· 税额字段是 zzsse(不是 se);税费拆得很细
| lkxm | 旅客姓名 | string |
| sfzjhm | 证件号码 | string |
| pj | 票价 | number |
| ryfjf | 燃油附加费 | number |
| zzssl | 增值税税率 | string |
| zzsse | 增值税税额 | number |
| mhfzjj | 民航发展基金 | number |
| qtsf | 其他税费 | number |
| bxf | 保险费 | number |
| jshj | 合计 | number |
| fpztDm | 发票状态代码 | string |
| hwxx[] | 航段明细 | array |
| └ cyr | 承运人 | string |
| └ hbh | 航班号 | string |
| └ sfz | 始发站 | string |
| └ mdz | 目的站 | string |
| └ qfsj | 起飞时间 | string |
| └ zwdj | 座位等级 | string |
铁路电子客票· 旅客字段是 name(非航空票的 lkxm);税额是 se;车次/席别为平铺字段、无 hwxx
| name | 旅客姓名 | string |
| zjh | 证件号码 | string |
| cc | 车次 | string |
| cfz | 出发站 | string |
| ddz | 到达站 | string |
| ccrq | 乘车日期 | string |
| cfsj | 出发时间 | string |
| xw | 席别 | string |
| je | 不含税金额 | number |
| se | 税额 | number |
| slv | 税率 | string |
| jshj | 价税合计(票价) | number |
| fpztDm | 发票状态代码 | string |
区块链发票(深圳/北京/云南)· 局端只验真,字段较少;qkl=true 标识区块链票
| xfmc | 销售方名称 | string |
| xfsbh | 销售方税号 | string |
| gfmc | 购买方名称 | string |
| je | 不含税金额 | number |
| se | 税额 | number |
| jshj | 价税合计 | number |
| jym | 校验码 | string |
| fpzt | 发票状态 | string |
| qkl | 区块链标识 | boolean |
响应示例
{
"code": "CYT_00000",
"data": {
"verified": true,
"channel": "增值税 / 数电发票",
"result": [{
"data": {
"xfmc": "北京祥瑞南门餐饮有限公司",
"gfmc": "北京开灵科技有限公司",
"jshj": 377.00, "je": 373.27, "se": 3.73,
"fplx": "0910", "fpztDm": "0"
}
}]
},
"requestId": "cyt_xxx"
}失败处理建议
税局 / 网络类异常可重试;业务类异常(查无此票、要素不一致、参数错误等)不要重试,以免占用税局当日查验次数。
| 情况 | 是否重试 | 说明 |
|---|---|---|
| 查验源/税局服务异常(CYT_50200) | 可重试 | 多为短时波动,建议 15–20 分钟后再试;月底税局停机维护也会偶发 |
| 请求时间戳过期(CYT_40103) | 可重试 | 校准本地时间后重新签名发起即可 |
| 查无此票(CYT_10001) | 不要重试 | 可能离线开票数据未上传,或要素有误;反复查会占用税局当日查验次数 |
| 要素不一致(CYT_10002) | 不要重试 | 核对四要素是否与票面一致,金额是否为不含税金额 |
| 参数错误(CYT_40001) | 不要重试 | 按票种传参对照表核对必填字段 |
| 签名/鉴权失败(CYT_40102/40101) | 不要重试 | 检查 app_key/app_secret 与签名算法 |
| 配额已用尽(CYT_42900) | 不要重试 | 联系商务续费或调高配额 |
附录
发票类型代码 fplx
| 0910 | 数电发票(普通发票) |
| 0920 | 数电发票(增值税专用发票) |
| 0901 | 数电纸质(增值税专用发票) |
| 0904 | 数电纸质(普通发票) |
| 0930 | 数电发票(机动车销售统一发票) |
| 0940 | 数电发票(二手车统一销售发票) |
| 100 | 区块链电子普通发票 |
| 102 | 通用电子发票 |
| 01 | 增值税专用发票 |
| 04 | 增值税普通发票 |
| 10 | 增值税电子普通发票 |
| 11 | 增值税普通发票(卷式) |
发票状态代码 fpztDm
| 0 | 正常 |
| 2 | 作废 |
| 3 | 已红冲 |
| 7 | 部分红冲 |
| 8 | 全额红冲 |
业务编码 code
| CYT_00000 | 查验成功 / 真票 |
| CYT_10001 | 查无此票 |
| CYT_10002 | 票面要素与底账不一致 |
| CYT_40001 | 请求参数缺失或格式错误 |
| CYT_40100 | 缺少鉴权请求头 |
| CYT_40101 | app_key 不存在或已停用 |
| CYT_40102 | 签名校验失败 |
| CYT_40103 | 请求时间戳过期(防重放) |
| CYT_42900 | 配额已用尽 |
| CYT_50200 | 查验源暂时不可用,请稍后重试 |