• 发票查验服务


    服务简码 HIVC

    默认端口 8015

    组件编码 hzero-invoice

    简介

    1.1 概述

    通过传入发票六要素,或者发票图片地址,识别发票结构化信息,并完成发票真实性检查。

    1.2 主要功能

    开发指导

    2.1 服务配置

    手动查验的订单号,需要向海马汇购买

    hzero:
      invoice:
        helios:
          check-order-no: ${HELIOS_CHECK_ORDER_NO:}
    

    OCR查验的订单号,需要向海马汇购买

    hzero:
      invoice:
        helios:
          ocr-order-no: ${HELIOS_OCR_ORDER_NO:}
    

    查验使用的接口需要定义在hzero接口平台,以下为接口平台的参数: 接口定义的服务编码

    hzero:
      invoice:
        interface-config:
          server-code: ${INTERFACE_SERVER_CODE:}
    

    接口定义,手工查验接口的编码

    hzero:
      invoice:
        interface-config:
          check-interface-code: ${INTERFACE_CHECK_CODE:}
    

    接口定义,ocr查验接口的编码

    hzero:
      invoice:
        interface-config:
          ocr-interface-code: ${INTERFACE_OCR_CODE:}
    

    上述配置都是必须的,否则查验功能不能使用。

    2.2 发票六要素查验

    POST /v1/{organizationId}/invoice/check

    传入参数

    {
        "invoiceTypeNo": "04",
        "invoiceCode": "3100164320",
        "invoiceNo": "59957351",
        "billingDate": "20190306",
        "invoiceAmount": 123,
        "checkCode": "315048"
    }
    

    参数说明

    字段名 含义
    invoiceTypeNo 发票类型代码
    invoiceCode 发票代码
    invoiceNo 发票号码
    billingDate 开票日期
    checkCode 校验码后六位

    发票类型解释

    发票类型代码 类型说明
    01 增值税专用发票
    02 货运运输业增值税专用发票
    03 机动车销售统一发票
    04 增值税普通发票
    10 增值税普通发票(电子)
    11 增值税普通发票(卷式)
    14 通行费发票

    返回参数

    [
      {
        "data": {
          "beginTime": 0,
          "billingTime": 0,
          "checkCode": "string",
          "checkPlatform": "string",
          "detail": "string",
          "deviceNumber": "string",
          "draweeAddressPhone": "string",
          "draweeBankAccount": "string",
          "draweeNo": "string",
          "endTime": 0,
          "fee": 0,
          "feeWithoutTax": 0,
          "invalidStatus": "string",
          "invoiceCode": "string",
          "invoiceGoods": [
            {
              "amount": 0,
              "brandModel": "string",
              "carType": "string",
              "certificateNumber": "string",
              "commodityInspectionNo": "string",
              "count": "string",
              "detailNo": "string",
              "engineNumber": "string",
              "expenseItem": "string",
              "frameNumber": "string",
              "goodsName": "string",
              "importCertificate": "string",
              "invoiceUniqueCode": "string",
              "limitMultiplier": "string",
              "organizationCode": "string",
              "passDateFrom": "string",
              "passDateTo": "string",
              "placeOfOrigin": "string",
              "plateNumber": "string",
              "specificationModel": "string",
              "taxPrice": 0,
              "taxRate": "string",
              "tonnage": "string",
              "unit": "string",
              "unitPrice": 0,
              "vehicleType": "string"
            }
          ],
          "invoiceNo": "string",
          "invoiceTypeNo": "string",
          "payee": "string",
          "payeeAddressPhone": "string",
          "payeeBankAccount": "string",
          "payeeNo": "string",
          "remark": "string",
          "tax": 0,
          "taxAuthorityName": "string",
          "taxAuthorityNo": "string",
          "taxCertificateNumber": "string",
          "taxRate": 0,
          "title": "string",
          "tollType": "string",
          "tollZeroTaxFlag": "string",
          "type": "string"
        },
        "error": "string",
        "errorCode": "string",
        "error_description": "string",
        "message": "string",
        "resultId": 0
      }
    ]
    

    状态字段

    字段名 含义
    resultId 查验结果id,存在则表示查验成功
    message 查验结果描述
    errorCode 公共错误码

    发票对象

    参数名 类型 说明 备注
    beginTime String 发票的有效期起始时间
    endTime String 发票的有效期截止时间
    type String 发票的类型,如广东增值税普通发票
    payee String 发票的收款方(销售方)
    fee Double 发票价税合计金额
    vatInvoiceCurrencyCode String 增值税发票币种
    title String 发票的抬头
    billingTime String 开票时间,为十位时间戳(utc+8)
    invoiceNo String 发票号码
    invoiceCode String 发票代码
    feeWithoutTax Double 不含税金额
    pdfUrl String 这张发票对应的 PDF_URL
    tax Double 税额,以分为单位
    reimburseStatus String 发票报销状态
    draweeNo String 购方识别号
    payeeNo String 销方识别号
    draweeAddressPhone String 购方地址电话
    payeeAddressPhone String 销方地址电话
    draweeBankAccount String 购方开户行及账号
    payeeBankAccount String 销方开户行及账号
    deviceNumber String 设备号码
    invoiceTypeNo String 发票类型编号
    invalidStatus String 作废标志
    checkCode String 校验码
    taxAuthorityName String 主管税务机关名称
    taxAuthorityNo String 主管税务机关代码
    taxCertificateNumber String 完税凭证号码
    remark String 备注
    tollType String 通行费标志 06-可抵扣通行费,07-不可抵扣通行费
    tollZeroTaxFlag String 零税率标志 空:非零税率,1:税率栏位显示“免税”,2:税率栏位显示“不征收”,3:零税率

    商品行invoiceGood对象

    参数名 类型 说明 备注
    invoiceUniqueCode String 发票code拼接发票号码,一般为发票唯一码
    goodsName String 商品/服务名称
    specificationModel String 规格型号
    unit String 单位
    count String 数量
    unitPrice String 单价
    amount String 金额
    taxRate String 税率
    taxPrice String 税额
    organizationCode String 身份证号码/组织机构代码
    vehicleType String 车辆类型
    brandModel String 厂牌型号
    placeOfOrigin String 产地
    certificateNumber String 合格证号
    commodityInspectionNo String 商检单号
    engineNumber String 发动机型号
    frameNumber String 车架号码
    importCertificate String 进口证明书号
    tonnage String 吨位
    limitMultiplier String 限乘人数
    carType String 车辆类型
    plateNumber String 车牌号
    passDateFrom String 通行日期起
    passDateTo String 通行日期止
    detailNo String 明细编号

    错误码说明:

    公共错误码

    errorCode message 说明
    121800 查验成功,发票一致
    121801 超过该张票当天查验次数
    121802 发票代码、号码正确,请修改其他参数
    121708 参数不能为空
    121803 所查发票不存在
    121805 超过一年的不能查验
    121806 日期当天的不能查验
    121807 发票类型不支持
    121984 不存在的发票类型
    121995 发票类型不能为空
    121993 发票代码不能为空
    121994 发票代码长度不合法
    121996 检验码不能为空
    121997 检验码长度不合法
    121998 发票号码不能为空
    121999 发票号码长度不合法
    121980 开票日期不能为空
    121981 开票日期格式不合法
    121982 开票金额不能为空
    126015 开票金额长度不合法
    126105 发票代码、号码不规范,请修改后重试!
    129999 税局系统不稳定,请稍后再试
    120998 无可用订单

    2.3 发票Ocr识别查验

    POST /v1/{organizationId}/invoice/ocr/check

    传入参数

    {
      "imageURL": "string"
    }
    

    参数说明

    字段名 含义
    imageURL 图片地址

    返回参数

    [
      {
        "data": {
          "beginTime": 0,
          "billingTime": 0,
          "checkCode": "string",
          "checkPlatform": "string",
          "detail": "string",
          "deviceNumber": "string",
          "draweeAddressPhone": "string",
          "draweeBankAccount": "string",
          "draweeNo": "string",
          "endTime": 0,
          "fee": 0,
          "feeWithoutTax": 0,
          "invalidStatus": "string",
          "invoiceCode": "string",
          "invoiceGoods": [
            {
              "amount": 0,
              "brandModel": "string",
              "carType": "string",
              "certificateNumber": "string",
              "commodityInspectionNo": "string",
              "count": "string",
              "detailNo": "string",
              "engineNumber": "string",
              "expenseItem": "string",
              "frameNumber": "string",
              "goodsName": "string",
              "importCertificate": "string",
              "invoiceUniqueCode": "string",
              "limitMultiplier": "string",
              "organizationCode": "string",
              "passDateFrom": "string",
              "passDateTo": "string",
              "placeOfOrigin": "string",
              "plateNumber": "string",
              "specificationModel": "string",
              "taxPrice": 0,
              "taxRate": "string",
              "tonnage": "string",
              "unit": "string",
              "unitPrice": 0,
              "vehicleType": "string"
            }
          ],
          "invoiceNo": "string",
          "invoiceTypeNo": "string",
          "payee": "string",
          "payeeAddressPhone": "string",
          "payeeBankAccount": "string",
          "payeeNo": "string",
          "remark": "string",
          "tax": 0,
          "taxAuthorityName": "string",
          "taxAuthorityNo": "string",
          "taxCertificateNumber": "string",
          "taxRate": 0,
          "title": "string",
          "tollType": "string",
          "tollZeroTaxFlag": "string",
          "type": "string"
        },
        "error": "string",
        "errorCode": "string",
        "error_description": "string",
        "message": "string",
        "resultId": 0
      }
    ]
    

    状态字段

    字段名 含义
    resultId 查验结果id,存在则表示查验成功
    message 查验结果描述
    errorCode 公共错误码

    发票对象

    参数名 类型 说明 备注
    beginTime String 发票的有效期起始时间
    endTime String 发票的有效期截止时间
    type String 发票的类型,如广东增值税普通发票
    payee String 发票的收款方(销售方)
    fee Double 发票价税合计金额
    vatInvoiceCurrencyCode String 增值税发票币种
    title String 发票的抬头
    billingTime String 开票时间,为十位时间戳(utc+8)
    invoiceNo String 发票号码
    invoiceCode String 发票代码
    feeWithoutTax Double 不含税金额
    pdfUrl String 这张发票对应的 PDF_URL
    tax Double 税额,以分为单位
    reimburseStatus String 发票报销状态
    draweeNo String 购方识别号
    payeeNo String 销方识别号
    draweeAddressPhone String 购方地址电话
    payeeAddressPhone String 销方地址电话
    draweeBankAccount String 购方开户行及账号
    payeeBankAccount String 销方开户行及账号
    deviceNumber String 设备号码
    invoiceTypeNo String 发票类型编号
    invalidStatus String 作废标志
    checkCode String 校验码
    taxAuthorityName String 主管税务机关名称
    taxAuthorityNo String 主管税务机关代码
    taxCertificateNumber String 完税凭证号码
    remark String 备注
    tollType String 通行费标志 06-可抵扣通行费,07-不可抵扣通行费
    tollZeroTaxFlag String 零税率标志 空:非零税率,1:税率栏位显示“免税”,2:税率栏位显示“不征收”,3:零税率

    商品行invoiceGood对象

    参数名 类型 说明 备注
    invoiceUniqueCode String 发票code拼接发票号码,一般为发票唯一码
    goodsName String 商品/服务名称
    specificationModel String 规格型号
    unit String 单位
    count String 数量
    unitPrice String 单价
    amount String 金额
    taxRate String 税率
    taxPrice String 税额
    organizationCode String 身份证号码/组织机构代码
    vehicleType String 车辆类型
    brandModel String 厂牌型号
    placeOfOrigin String 产地
    certificateNumber String 合格证号
    commodityInspectionNo String 商检单号
    engineNumber String 发动机型号
    frameNumber String 车架号码
    importCertificate String 进口证明书号
    tonnage String 吨位
    limitMultiplier String 限乘人数
    carType String 车辆类型
    plateNumber String 车牌号
    passDateFrom String 通行日期起
    passDateTo String 通行日期止
    detailNo String 明细编号

    错误码说明:

    公共错误码

    errorCode message 说明
    121800 查验成功,发票一致
    121801 超过该张票当天查验次数
    121802 发票代码、号码正确,请修改其他参数
    121708 参数不能为空
    121803 所查发票不存在
    121805 超过一年的不能查验
    121806 日期当天的不能查验
    121807 发票类型不支持
    121984 不存在的发票类型
    121995 发票类型不能为空
    121993 发票代码不能为空
    121994 发票代码长度不合法
    121996 检验码不能为空
    121997 检验码长度不合法
    121998 发票号码不能为空
    121999 发票号码长度不合法
    121980 开票日期不能为空
    121981 开票日期格式不合法
    121982 开票金额不能为空
    126015 开票金额长度不合法
    126105 发票代码、号码不规范,请修改后重试!
    129999 税局系统不稳定,请稍后再试
    120998 无可用订单

    展望