票据查验 · API 文档

统一网关查验通,覆盖增值税 / 电票 / 数电纸质等发票查验及版式、入账扩展能力。所有接口 POST JSON,鉴权一致。

鉴权

先用 App 凭据换取访问令牌,每次业务请求在请求头携带令牌、时间戳与请求签名。

字段	类型	必填	说明
X-App-Key	string	必填	查验通为你签发的应用标识 app_key
X-Timestamp	string	必填	Unix 秒级时间戳,与服务器时差需在 ±300 秒内
X-Sign	string	必填	sha256(appKey + timestamp + body + appSecret) 小写 hex

POST

税控发票查验

增值税平台查验

增值税发票四要素查验,口径对齐全国增值税发票查验平台。不同发票类型返回明细字段略有差异。

/api/v1/verify/vat-control

请求参数

字段	类型	必填	说明
cyList	array	必填	查验发票列表
└ fpdm	string	必填	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期 yyyy-MM-dd / yyyyMMdd
└ je	number	条件	不含税金额;专票/电子专票/机动车销售统一发票/数电纸质(专票·机动车)/二手车类必填
└ jym	string	条件	校验码后 6 位;普票/电子普票/卷式/通行费/数电纸质(普票)必填
customReqId	string	可选	调用方唯一请求 ID,规则 AppKey+去横杠 UUID

请求示例

{
  "cyList": [
    {
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-11-01",
      "je": 1421.63
    }
  ]
}

响应参数

字段	类型	必填	说明
code	string	必填	业务编码,2000 成功;非 2000 见错误码表
success	boolean	必填	是否成功(有无业务异常)
message	string	可选	提示/错误信息
reqId	string	必填	服务端请求唯一标识,排障用
data	array	必填	逐票查验结果列表
└ success	boolean	必填	该票查验是否成功
└ code	string	可选	查验失败编码(详见附录)
└ message	string	可选	查验失败信息
└ time	string	必填	查验时间
└ times	integer	可选	查验次数
└ fpdm	string	可选	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jym	string	可选	校验码
└ je	number	可选	金额
└ jshj	number	可选	价税合计
└ fplx	string	可选	发票类型代码(详见附录)
└ dq	string	可选	地区代码
└ customReqId	string	必填	请求 ID,入参传则用入参否则自动生成
└ data	object	可选	查验明细(发票全要素)
└ xfmc	string	可选	销方名称
└ xfsbh	string	可选	销方税号
└ gfmc	string	可选	购方名称
└ gfsbh	string	可选	购方税号
└ je	number	可选	不含税金额
└ se	number	可选	税额
└ jshj	number	可选	价税合计
└ fpztDm	string	可选	发票状态代码(0 正常)
└ hwxx	array	可选	货物/服务明细行
└ mc	string	可选	货物或应税劳务名称
└ je	number	可选	明细金额
└ se	number	可选	明细税额
└ slv	number	可选	税率
└ spbm	string	可选	税收分类编码

响应示例

{
  "code": "2000",
  "success": true,
  "message": null,
  "reqId": "0550e35a24014277ab056cf7246eb7db",
  "data": [
    {
      "success": true,
      "time": "2024-03-01 10:00:00",
      "times": 1,
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-09-28",
      "je": 21640.26,
      "jshj": 22938.69,
      "fplx": "01",
      "dq": "深圳",
      "customReqId": "10001995...",
      "data": {
        "xfmc": "示例销方科技有限公司",
        "xfsbh": "914403003119439031",
        "gfmc": "示例购方有限公司",
        "gfsbh": "91211103MA107PP20C",
        "je": 21640.26,
        "se": 1298.43,
        "jshj": 22938.69,
        "fpztDm": "0",
        "hwxx": [
          {
            "mc": "*信息技术服务*软件服务费",
            "je": 2539.62,
            "se": 152.38,
            "slv": 0.06,
            "spbm": "3040201990000000000"
          }
        ]
      }
    }
  ]
}

POST

数电票查验

电票平台查验

数电(电子)发票查验,按发票号码 + 开票日期 + 价税合计三要素核验。

/api/v1/verify/einvoice

请求参数

字段	类型	必填	说明
cyList	array	必填	查验发票列表
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期 yyyy-MM-dd / yyyyMMdd
└ jshj	number	必填	价税合计
customReqId	string	可选	调用方唯一请求 ID

请求示例

{
  "cyList": [
    {
      "fphm": "21317000000000000000",
      "kprq": "2021-12-01",
      "jshj": 1129.99
    }
  ]
}

响应参数

字段	类型	必填	说明
code	string	必填	业务编码,2000 成功;非 2000 见错误码表
success	boolean	必填	是否成功(有无业务异常)
message	string	可选	提示/错误信息
reqId	string	必填	服务端请求唯一标识,排障用
data	array	必填	逐票查验结果列表
└ success	boolean	必填	该票查验是否成功
└ code	string	可选	查验失败编码(详见附录)
└ message	string	可选	查验失败信息
└ time	string	必填	查验时间
└ times	integer	可选	查验次数
└ fpdm	string	可选	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jym	string	可选	校验码
└ je	number	可选	金额
└ jshj	number	可选	价税合计
└ fplx	string	可选	发票类型代码(详见附录)
└ dq	string	可选	地区代码
└ customReqId	string	必填	请求 ID,入参传则用入参否则自动生成
└ data	object	可选	查验明细(发票全要素)
└ xfmc	string	可选	销方名称
└ xfsbh	string	可选	销方税号
└ gfmc	string	可选	购方名称
└ gfsbh	string	可选	购方税号
└ je	number	可选	不含税金额
└ se	number	可选	税额
└ jshj	number	可选	价税合计
└ fpztDm	string	可选	发票状态代码(0 正常)
└ hwxx	array	可选	货物/服务明细行
└ mc	string	可选	货物或应税劳务名称
└ je	number	可选	明细金额
└ se	number	可选	明细税额
└ slv	number	可选	税率
└ spbm	string	可选	税收分类编码

响应示例

{
  "code": "2000",
  "success": true,
  "message": null,
  "reqId": "0550e35a24014277ab056cf7246eb7db",
  "data": [
    {
      "success": true,
      "time": "2024-03-01 10:00:00",
      "times": 1,
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-09-28",
      "je": 21640.26,
      "jshj": 22938.69,
      "fplx": "01",
      "dq": "深圳",
      "customReqId": "10001995...",
      "data": {
        "xfmc": "示例销方科技有限公司",
        "xfsbh": "914403003119439031",
        "gfmc": "示例购方有限公司",
        "gfsbh": "91211103MA107PP20C",
        "je": 21640.26,
        "se": 1298.43,
        "jshj": 22938.69,
        "fpztDm": "0",
        "hwxx": [
          {
            "mc": "*信息技术服务*软件服务费",
            "je": 2539.62,
            "se": 152.38,
            "slv": 0.06,
            "spbm": "3040201990000000000"
          }
        ]
      }
    }
  ]
}

POST

数电纸质发票查验

其它票据查验

数电纸质发票(纸质形态的数电票)查验,要素以数电票为基,纸质代码/号码组合核验。

/api/v1/verify/paper-einvoice

请求参数

字段	类型	必填	说明
cyList	array	必填	查验发票列表
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jshj	number	条件	价税合计/不含税金额(按票种)
customReqId	string	可选	调用方唯一请求 ID

请求示例

{
  "cyList": [
    {
      "fphm": "24000000000000000000",
      "kprq": "2024-03-01",
      "jshj": 100
    }
  ]
}

响应参数

字段	类型	必填	说明
code	string	必填	业务编码,2000 成功;非 2000 见错误码表
success	boolean	必填	是否成功(有无业务异常)
message	string	可选	提示/错误信息
reqId	string	必填	服务端请求唯一标识,排障用
data	array	必填	逐票查验结果列表
└ success	boolean	必填	该票查验是否成功
└ code	string	可选	查验失败编码(详见附录)
└ message	string	可选	查验失败信息
└ time	string	必填	查验时间
└ times	integer	可选	查验次数
└ fpdm	string	可选	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jym	string	可选	校验码
└ je	number	可选	金额
└ jshj	number	可选	价税合计
└ fplx	string	可选	发票类型代码(详见附录)
└ dq	string	可选	地区代码
└ customReqId	string	必填	请求 ID,入参传则用入参否则自动生成
└ data	object	可选	查验明细(发票全要素)
└ xfmc	string	可选	销方名称
└ xfsbh	string	可选	销方税号
└ gfmc	string	可选	购方名称
└ gfsbh	string	可选	购方税号
└ je	number	可选	不含税金额
└ se	number	可选	税额
└ jshj	number	可选	价税合计
└ fpztDm	string	可选	发票状态代码(0 正常)
└ hwxx	array	可选	货物/服务明细行
└ mc	string	可选	货物或应税劳务名称
└ je	number	可选	明细金额
└ se	number	可选	明细税额
└ slv	number	可选	税率
└ spbm	string	可选	税收分类编码

响应示例

{
  "code": "2000",
  "success": true,
  "message": null,
  "reqId": "0550e35a24014277ab056cf7246eb7db",
  "data": [
    {
      "success": true,
      "time": "2024-03-01 10:00:00",
      "times": 1,
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-09-28",
      "je": 21640.26,
      "jshj": 22938.69,
      "fplx": "01",
      "dq": "深圳",
      "customReqId": "10001995...",
      "data": {
        "xfmc": "示例销方科技有限公司",
        "xfsbh": "914403003119439031",
        "gfmc": "示例购方有限公司",
        "gfsbh": "91211103MA107PP20C",
        "je": 21640.26,
        "se": 1298.43,
        "jshj": 22938.69,
        "fpztDm": "0",
        "hwxx": [
          {
            "mc": "*信息技术服务*软件服务费",
            "je": 2539.62,
            "se": 152.38,
            "slv": 0.06,
            "spbm": "3040201990000000000"
          }
        ]
      }
    }
  ]
}

POST

区块链发票(深圳)

其它票据查验

深圳区块链电子普通发票查验。校验码为 5 位短码,不用开票日期,需销方税号。

/api/v1/verify/blockchain-sz

请求参数

字段	类型	必填	说明
cyList	array	必填	查验发票列表
└ dq	string	必填	地区固定值 4403(深圳)
└ fpdm	string	必填	发票代码
└ fphm	string	必填	发票号码
└ xfsbh	string	必填	销售方纳税人识别号
└ jym	string	必填	校验码(区块链发票为短码,如 6c6b5)
customReqId	string	可选	调用方唯一请求 ID

请求示例

{
  "cyList": [
    {
      "dq": "4403",
      "fpdm": "144032609110",
      "fphm": "07782308",
      "xfsbh": "91440300MA5HTARM9D",
      "jym": "6c6b5"
    }
  ]
}

响应参数

字段	类型	必填	说明
code	string	必填	业务编码,2000 成功;非 2000 见错误码表
success	boolean	必填	是否成功(有无业务异常)
message	string	可选	提示/错误信息
reqId	string	必填	服务端请求唯一标识,排障用
data	array	必填	逐票查验结果列表
└ success	boolean	必填	该票查验是否成功
└ code	string	可选	查验失败编码(详见附录)
└ message	string	可选	查验失败信息
└ time	string	必填	查验时间
└ times	integer	可选	查验次数
└ fpdm	string	可选	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jym	string	可选	校验码
└ je	number	可选	金额
└ jshj	number	可选	价税合计
└ fplx	string	可选	发票类型代码(详见附录)
└ dq	string	可选	地区代码
└ customReqId	string	必填	请求 ID,入参传则用入参否则自动生成
└ data	object	可选	查验明细(发票全要素)
└ xfmc	string	可选	销方名称
└ xfsbh	string	可选	销方税号
└ gfmc	string	可选	购方名称
└ gfsbh	string	可选	购方税号
└ je	number	可选	不含税金额
└ se	number	可选	税额
└ jshj	number	可选	价税合计
└ fpztDm	string	可选	发票状态代码(0 正常)
└ hwxx	array	可选	货物/服务明细行
└ mc	string	可选	货物或应税劳务名称
└ je	number	可选	明细金额
└ se	number	可选	明细税额
└ slv	number	可选	税率
└ spbm	string	可选	税收分类编码

响应示例

{
  "code": "2000",
  "success": true,
  "message": null,
  "reqId": "0550e35a24014277ab056cf7246eb7db",
  "data": [
    {
      "success": true,
      "time": "2024-03-01 10:00:00",
      "times": 1,
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-09-28",
      "je": 21640.26,
      "jshj": 22938.69,
      "fplx": "01",
      "dq": "深圳",
      "customReqId": "10001995...",
      "data": {
        "xfmc": "示例销方科技有限公司",
        "xfsbh": "914403003119439031",
        "gfmc": "示例购方有限公司",
        "gfsbh": "91211103MA107PP20C",
        "je": 21640.26,
        "se": 1298.43,
        "jshj": 22938.69,
        "fpztDm": "0",
        "hwxx": [
          {
            "mc": "*信息技术服务*软件服务费",
            "je": 2539.62,
            "se": 152.38,
            "slv": 0.06,
            "spbm": "3040201990000000000"
          }
        ]
      }
    }
  ]
}

POST

增值税平台查验-新平台

增值税平台查验-新平台上游路径待复核

新查验平台通道的增值税发票查验,参数与税控查验一致,接入新平台路由。

/api/v1/verify/vat-new

请求参数

字段	类型	必填	说明
cyList	array	必填	查验发票列表
└ fpdm	string	条件	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ je	number	条件	不含税金额
└ jym	string	条件	校验码后 6 位

请求示例

{
  "cyList": [
    {
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2024-11-01",
      "je": 1421.63
    }
  ]
}

响应参数

字段	类型	必填	说明
code	string	必填	业务编码,2000 成功;非 2000 见错误码表
success	boolean	必填	是否成功(有无业务异常)
message	string	可选	提示/错误信息
reqId	string	必填	服务端请求唯一标识,排障用
data	array	必填	逐票查验结果列表
└ success	boolean	必填	该票查验是否成功
└ code	string	可选	查验失败编码(详见附录)
└ message	string	可选	查验失败信息
└ time	string	必填	查验时间
└ times	integer	可选	查验次数
└ fpdm	string	可选	发票代码
└ fphm	string	必填	发票号码
└ kprq	string	必填	开票日期
└ jym	string	可选	校验码
└ je	number	可选	金额
└ jshj	number	可选	价税合计
└ fplx	string	可选	发票类型代码(详见附录)
└ dq	string	可选	地区代码
└ customReqId	string	必填	请求 ID,入参传则用入参否则自动生成
└ data	object	可选	查验明细(发票全要素)
└ xfmc	string	可选	销方名称
└ xfsbh	string	可选	销方税号
└ gfmc	string	可选	购方名称
└ gfsbh	string	可选	购方税号
└ je	number	可选	不含税金额
└ se	number	可选	税额
└ jshj	number	可选	价税合计
└ fpztDm	string	可选	发票状态代码(0 正常)
└ hwxx	array	可选	货物/服务明细行
└ mc	string	可选	货物或应税劳务名称
└ je	number	可选	明细金额
└ se	number	可选	明细税额
└ slv	number	可选	税率
└ spbm	string	可选	税收分类编码

响应示例

{
  "code": "2000",
  "success": true,
  "message": null,
  "reqId": "0550e35a24014277ab056cf7246eb7db",
  "data": [
    {
      "success": true,
      "time": "2024-03-01 10:00:00",
      "times": 1,
      "fpdm": "3400000000",
      "fphm": "17000068",
      "kprq": "2021-09-28",
      "je": 21640.26,
      "jshj": 22938.69,
      "fplx": "01",
      "dq": "深圳",
      "customReqId": "10001995...",
      "data": {
        "xfmc": "示例销方科技有限公司",
        "xfsbh": "914403003119439031",
        "gfmc": "示例购方有限公司",
        "gfsbh": "91211103MA107PP20C",
        "je": 21640.26,
        "se": 1298.43,
        "jshj": 22938.69,
        "fpztDm": "0",
        "hwxx": [
          {
            "mc": "*信息技术服务*软件服务费",
            "je": 2539.62,
            "se": 152.38,
            "slv": 0.06,
            "spbm": "3040201990000000000"
          }
        ]
      }
    }
  ]
}