更新记录

1.0.1（2024-02-03）

下单后有使用问题联系客服 QQ:183654371

1.0.0（2024-02-03）

发布uniCloud版本

平台兼容性

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

下单后有使用问题联系客服 QQ:183654371

版本：ver 2.9.345

关于费用

1. 插件市场售卖的是uniCloud版的对接源码
2. 票帮手的API是付费才能使用的，本插件不包含API的费用。但是了解下来票帮手是最实惠的。

API 列表

如果你的业务不部署在uniCloud，可以参考本插件源码和接口规范，用你的业务所用语言实现网络请求。

接入方式

如果在uniCloud部署应用，您无需关心接口规范中的请求方式、headers、以及签名处理，本插件已实现。 如果的应用没有部署在uniCloud，您需要遵照下一节的接口规范实现接口通讯。

// 以下是nodejs代码示例
const appid = '您的AppID'
const secret = '您的AppSecret'
const url = 'https://api域名/pathname'
const time = Date.now()
const nonce = '随机字符串'
const params = {
    // 请求入参
}
// 拼合字串
const query = JSON.stringify(params) + `&time=${time}&nonce=${nonce}&secret=${secret}`
// 创建md5签名
const sign = require('crypto').createHash('md5').update(query).digest('hex')
// 组装post data
data = {...params, time, nonce, sign}

// 非 uniCloud 环境用 axios 或其他网络请求库
// uniCloud环境用 uniCloud.httpclient 发起网络请求
const res = await uniCloud.httpclient.request(url, {
    data,
    headers:{appid},
    method:'POST',
    dataType:'json',
    contentType:'json'
})

接口规范

• 请求方式：POST
• 请求和返回参数类型均为JSON
• headers = { appid } 请求headers必须为您的appid
• 请求数据需要做md5签名
• 返回值中有code和msg节点，code = 0 表示请求成功，不等于0表示请求失败，msg为请求失败的信息
• 所有参数字符采用utf-8字符集

手把手使用教程

1 下载HBuilderX安装运行，并登录你的开发者账号，在uniCloud web控制台创建好云空间备用；

2 下载插件导入HBuilderX，在uniCloud上点右键选择关联云服务空间或项目，选择你创建的云空间，然后在uniCloud/database/db_init.json 点右键选择初始化云数据库

3 登陆 票帮手 注册并获取你的AppID和AppSeccret并填写到云数据库pbs-config表的第一条记录中，可以采取以下任一方式：

1、可以手动登陆你的云空间修改pbs-config的第一条记录中的appid和secret

2、检查uniCloud/cloudfunctions/api/pbs/pbs.param.json中设置"path":"/init"，然后打开uniCloud/cloudfunctions/api/pbs/api/init.js，将appid和secret的值填写好以后，在uniCloud/cloudfunctions/api/上点右键“运行-本地云函数”，程序会将你的appid和secret更新到pbs-config的第一条记录中

4 在uniCloud部署项目

• 依次上传uniCloud/cloudfunctions/common/下所有公共模块
• 上传uniCloud/cloudfunctions/api云函数

对接流程：

• 在【票帮手】注册账号，获得你的AppID。

• 将appid和secret设置到系统。

• 添加企业客户，调用 pbs.addClient() 直连模式只能添加一家企业，服务商模式可以添加多家不同的企业。

• 开票前调用 pbs.loginEtax() 登录电子税务（需要电子税务账号和密码）指定扫脸或者验证码登录模式

  • 选择验证码模式，等收到验证码，调用 pbs.setEtaxSMS() 设置验证码

  • 选择扫脸模式，会返回qrcode，展示给用户扫码人脸验证（需要用当地税务局的APP扫码）

• 只有以上流程执行成功才能开票、获取发票等接口

• 登录成功调用开票接口 pbs.submitInvoices()，开票如果返回以下code

  • 如果code = NEED_LOGIN，需要重新调用 pbs.loginEtax() 登录电子税务

  • 如果存储了账号密码，会自动调用登录，返回code = NEED_SMS_CODE，需要调用 pbs.setEtaxSMS() 回传短信验证码

  • 如果code = NEED_FACE_VERIFY，同时会返回qrcode，需要用qrcode生成二维码给用户扫码人脸验证（需要用当地税务局的APP扫码）

添加新客户

await pbs.addClient(data)添加企业客户信息到你的账号下

入参data字段说明

省份代码

对应的codes.js在/uniCloud/cloudfunctions/api/config/codes.js

返回值说明

如果添加失败，msg=企业已存在，则表示该企业已经被其他服务商添加到系统，需要联系客户确定是否与原服务商存在合作关系。

插件使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qymc:"企业名称",
    qysh:"企业税号",
    ssdq:"省份编号"
}
const{code,msg,spid} = await pbs.addClient(data)

API调用示例

const config = {
    appid:"您的appid",
    secret:"您的secret"
}
const params = { 
    qymc:"企业名称",
    qysh:"企业税号",
    ssdq:"省份编号"
}
const url = 'https://i.pbs.net.cn/api/addClient'
const time = Date.now()
// 拼合字串
const query = JSON.stringify(params) + `&time=${time}&secret=${config.secret}`
// 创建md5签名
const sign = require('crypto').createHash('md5').update(query).digest('hex')
// 组装post data
data = {...params, time, sign}
const{code,msg,spid}  = await uniCloud.httpclient.request(url, {
    data,
    method:'POST',
    dataType:'json',
    contentType:'json'
})

查询客户列表

await pbs.clients(data) 获取您账号下的客户列表。

入参data字段说明

返回值说明

客户rows信息说明

object说明

插件使用示例

const pbs = require('yun2-pbs-unicloud')
const {pageIndex:1, pageSize:10}
const{code,msg,total,rows} = await pbs.clients(data)
if(code==0)
{
    console.log(rows) // 客户信息
}
else
{
    // console.log(msg)  // 报错原因
}

API调用示例

const config = {
    appid:"您的appid",
    secret:"您的secret"
}
const params = { 
    pageIndex:"1",
    pageSize:"20",
    keywords:"关键字" //非必填，不填写表示查询所有
}
const url = 'https://i.pbs.net.cn/api/clients'
const time = Date.now()
// 拼合字串
const query = JSON.stringify(params) + `&time=${time}&secret=${config.secret}`
// 创建md5签名
const sign = require('crypto').createHash('md5').update(query).digest('hex')
// 组装post data
data = {...params, time, sign}
const res = await uniCloud.httpclient.request(url, {
    data,
    method:'POST',
    dataType:'json',
    contentType:'json'
})

以下接口不再列举API调用示例

登陆电子税务局

await pbs.loginEtax(data)

• 调用此接口会根据不同的登陆模式（短信登陆或扫脸登陆）返回不同的DATA内容；
• 如果验证码登陆时：调用这个接口时，如果data返回的解密后不是手机号，说明已经登陆成功，无需获以验证码（系统已经在登陆状态），同理，扫脸登陆时也是一样。

入参data字段说明

手机卡托管模式，是将手机卡托管在我公司，后期登陆无需人工输入验证码，实现自动登陆，无需再调用该登陆接口。

返回值说明

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh:"企业税号",
    dzswjyh:"电子税务局账号",
    dzswjmm:"电子税务局密码",
    dlfs:"2",
}
const{code,msg} = await pbs.loginEtax(data)

设置电子税务局短信验证码

await pbs.setEtaxSMS(data)

调用登录以后，需要填写手机验证码才能登录，财务人员收到验证码后，在企业内部系统填写验证码，流程与登录电子税务局一致。调用此接口前，必须调用登录接口pbs.loginEtax()

我们提供托管手机卡模式，详情联系客服。

入参data字段说明

返回值说明

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh:"企业税号",
    yzm:"验证码"
}
const{code,msg} = await pbs.setEtaxSMS(data)

返回值说明

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh:"企业税号",
}
const{code,msg} = await pbs.waitEtaxQrcode(data)

以上登录接口成功以后调用以下票据相关接口

开发票（蓝字和红字统一接口）

await pbs.submitInvoices(data) 开红字发票和蓝字发票统一调用本接口，蓝色接口数量和金额为正数，红色数量和金额为负数

入参data字段说明

发票列表数据数组示例

data = [
    {
        "XTLSH": "单据号",
        "KHMC": "客户名称",
        "KHSH": "税号",
        "KHDZ": "地址",
        "KHKHYHZH": "客户银行账号",
        "FPZL": "发票种类",
        "BZ": "备注",
        "KPR": "开票人",
        "SKR": "收款人",
        "FHR": "复核人",
        "QYKHYHZH": "企业开户银行账号",
        "QYDZDH": "企业地址电话",
        "YFPHM": "红冲原发票号",
        "XXBBH": "信息表编号",
        "QDBZ": "清单标志",
        "KHYJ": "客户邮件",
        "KHSJ": "客户手机号",
        "JDC": "机动车标识",
        "DBTS": "代办退税标识",
        "ZSFS":"特定业务标识",
        "ITEM": [
            {
                "CPMC": "产品名称1",
                "CPXH": "产品型号",
                "CPDW": "产品单位",
                "SL": "税率",
                "CPSL": "数量",
                "BHSJE": "不含税金额",
                "SE": "税额",
                "FLBM": "分类编码",
                "XSYH": "税率优惠",
                "LSLBZ": "零税率标识",
                "YHSM": "优惠说明",
                "KCJE":"0"        
            }, 
            {
                "CPMC": "产品名称2",
                "CPXH": "产品型号",
                "CPDW": "产品单位",
                "SL": "税率",
                "CPSL": "数量",
                "BHSJE": "不含税金额",
                "SE": "税额",
                "FLBM": "分类编码",
                "XSYH": "税率优惠",
                "LSLBZ": "零税率标识",
                "YHSM": "优惠说明",
                "KCJE":"0"
        }
    ],
    "FJXX":[
        {
            "MC":"名称"，
            "LY":"内容"
        },
        { 
            "MC":"名称"，
            "LY":"内容"}
    ],
    "TDYW":[
        {
            "BDC_SF":"不动产租赁省份",
            "BDC_XXDZ":"不动产租赁详细地址",
            "BDC_QSRQ":"不动产租赁起始日期",
            "BDC_JZRQ":"不动产租赁截止日期",
            "BDC_KSBZ":"不动产租赁跨市标志",
            "BDC_CQJH":"不动产租赁产权证号",
            "BDC_PJDW":"不动产租赁面积单位",
            "BDCXS_CQZH":"不动产销售产品证号",
            "BDCXS_DQDZ":"不动产销售所在省份地区",
            "BDCXS_XXDZ":"不动产销售详细地址",
            "BDCXS_HTBH":"不动产销售合同编号",
            "BDCXS_XMBH":"不动产销售项目编号",
            "BDCXS_JSJG":"不动产销售计税价格",
            "BDCXS_CJJE":"不动产销售成交价格",
            "BDCXS_KQBZ":"不动产销售跨区标志",
            "BDCXS_MJDW":"不动产销售面积单位",
            "LKYS_CXR":"旅客运输出行人",
            "LKYS_CXRZJLX":"旅客运输证件类型",
            "LKYS_CXRZJHM":"旅客运输证件号码",
            "LKYS_CXRQ":"旅客运输出行日期",
            "LKYS_CFD":"旅客运输出发地",
            "LKYS_DDD":"旅客运输到达地",
            "LKYS_JTGJLX":"旅客运输交通工具类型",
            "LKYS_DJ":"旅客运输等级",
            "HWYS_QYD":"货物运输起运地",
            "HWYS_DDD":"货物运输到达地",
            "HWYS_YSGJ":"货物运输运输工具",
            "HWYS_YSGJTH":"货物运输运输工具牌号",
            "HWYS_YSHWMC":"货物运输货物名称"，
            "GZFW_FSD":"建筑服务发生地"，
            “GZFW_XXDZ”:"发生地详细地址",
            "GZFW_XMMC":"建筑项目名称",
            "GZFW_XMBH":"土地增值税项目编号",
            "GZFW_KSBZ":"跨地市标志"
         },
         {
         }
    }
]

发票列表数据格式说明

列表数据为Array，最大长度100

返回值说明

code说明 详见以下描述和代码说明

注意：

• code = 0时，HaveSave = 0时，说明数据异常，数据没有进行保存，无需调用后续的接口。
• code = 0时，HaveSave = 1时，说明数据正常，但可能是在开票过程中出现异常（例如税务局登陆失效），这时候可以主动调用接口登陆税务局，登陆后调用pbs.resubmitInvoices()系统会重试进行开具。
• code字符串（NEED_LOGIN、NEED_SMS_CODE、NEED_FACE_VERIFY）需要按下表做相应处理
• 唯一能确定开票成功开票的情况： code = 0 并且 successList列表中发票号不为空，如果code = 0并且 successList列表中返回的发票号码是空的，需要用“获取开票结果”查询开票状态。

成功的发票数据示例

successList Array 字段说明

失败的发票数据示例

errorList Array 字段说明

数据错误示例：

{
    "code": 0,
    "msg": "折扣行的产品单位必需是空。",
    "errorList": [
        {
            "XTLSH": "144115188078156755",
            "ErrMsg": "折扣行的产品单位必需是空。 ",
            "HaveSave": "0"
        }
    ],
    "successList": [
    ]
}

发票库存不足：

{
    "code": 0,
    "msg": "发票已经用完，请申领发票",
    "errorList": [
        {
            "XTLSH": "144115188078708534",
            "ErrMsg": "发票已经用完，请申领发票"
        }
    ],
    "successList": [
    ]
}

正常开具：

{
    "code": 0,
    "msg": "成功",
    "errorList": [
    ],
    "successList": [
        {
            "xtlsh": "144115188079268993",
            "fpzl": "026",
            "fpdm": "044002100411",
            "fphm": "22338521",
            "kprq": "20211026",
            "skm": "007+1-75<0-42-+64847*2+5/+*11113*448/482-13>>+0173/9775922*4-<+89/28424/-<087/<8**/<183130*+1*130701+6<+1998<424",
            "jym": "06441947523575629741",
            "jqbh": "237001069144",
            "ewm": "01,01,044002100411,22338521,111.63,20211026,06441947523575629741,2C4A,",
            "url": "/KPGL/PDFXZ?XYM=06441947523575629741&FPZL=026",
            "kpjg": "1",
            "pdfxx": "PDF生成成功",
            "kpfk": "开具成功"
        }
    ]
}

重复提交：

{
    "code": 0,
    "msg": "此单据已经开过发票, FPHM = 03100210041182467316:KPRQ =2021-10-25 00:00:00.000。",
    "errorList": [
        {
            "XTLSH": "144115188079291147",
            "FPHM": "03100210041182467316",
            "KPRQ": "2021-10-25 00:00:00.000",
            "MW": "[MDAqOTM1LTUyPjM8PjI4KzI8LTM5KzQxLy8wODw1MS0qKjM0OTkyMjUzMjE2PCs5ODw+NjcwODAzMjgrKjc1Ny0rMTc1NTYyPDkyLzY5Ny80Kz4qLTkwPjMxKzc2OTwyNDcwMTg0MCoxOS0+MTg0Pg==]",
            "XYM": "06182134178896463325",
            "JQBH": "587005306549",
            "FPZL": "026",
            "ErrMsg": "此单据已经开过发票, FPHM = 03100210041182467316:KPRQ =2021-10-25 00:00:00.000。 ",
            "xtlsh": "144115188079291147",
            "fpzl": "026",
            "fpdm": "031002100411",
            "fphm": "82467316",
            "kprq": "20211025",
            "skm": " ",
            "jym": "06182134178896463325",
            "jqbh": "237001069144",
            "ewm": "01,01,044002100411, 82467316,111.63,20211025, 06182134178896463325,2C4A,",
            "url": "/KPGL/PDFXZ?XYM=06182134178896463325&FPZL=026",
            "kpjg": "1",
            "pdfxx": "PDF生成成功",
            "kpfk": "开具成功"
        }
    ],
    "successList": [
    ]
}

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh:"企业税号",
    data:[
        {
            //发票数据
        }
    ]
}
const{code,msg,successList,errorList} = await pbs.submitInvoices(data)

重新提交待开票的发票列表

await pbs.resubmitInvoices(data) 包含蓝字和红字发票

入参data字段说明

发票列表数据数组说明

返回值说明

code说明

同submitInvoices

如果返回的code不是上面三种情况，具体看返回的msg信息。

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh:"企业税号",
    data : [
        {
            FPZL:"发票种类",
            XTLSH:"单据号"
        },
        {
            FPZL:"发票种类",
            XTLSH:"单据号"
        }
    ]
}
const{code,msg,successList,errorList} = await pbs.resubmitInvoices(data)

获取销项发票列表

await pbs.invoices(data) 分页请求发票列表，传入对应参数，0未开发票、1已开发票、2开票中的发票列表

入参data字段说明

返回值说明

发票列表数据说明

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    //...参数
}
const{code,msg,rows} = await pbs.invoices(data)

将开票中的发票撤回到草稿箱

await pbs.backToDraft(data),将开票中的发票撤回到草稿箱

入参data字段说明

同 pbs.backToDraft(data)

发票列表数据数组说明

返回值说明

将发票从草稿箱删除

await pbs.delFromDraft(data)，将发票从草稿箱删除

入参data字段说明

同 pbs.delFromDraft(data)

发票列表数据数组说明

返回值说明

获取开票结果

await pbs.getInvoiceStatus(data)

入参data字段说明

返回值说明

使用示例

const pbs = require('yun2-pbs-unicloud')
const data = {
    qysh : '企业税号',
    fpzl : '发票种类',
    xtlsh : '单据号'
}
const{code,msg} = await pbs.getInvoiceStatus(data)

获取税务局税种分类名称

await pbs.getEtaxGoodsCates(data)

入参data字段说明

返回值说明

rows数据示例：

{
    "total": "6",
    "rows": [{
        "BM": "1000000000000000000",
        "MC": "货物",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "货物",
        "YPBZ": "0",
        "LCOUNT": 1
    }, {
        "BM": "2000000000000000000",
        "MC": "劳务",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "劳务",
        "YPBZ": "0",
        "LCOUNT": 1
    }, {
        "BM": "3000000000000000000",
        "MC": "销售服务",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "销售服务",
        "YPBZ": "0",
        "LCOUNT": 1
    }, {
        "BM": "4000000000000000000",
        "MC": "无形资产",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "无形资产",
        "YPBZ": "0",
        "LCOUNT": 1
    }, {
        "BM": "5000000000000000000",
        "MC": "不动产",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "不动产",
        "YPBZ": "0",
        "LCOUNT": 1
    }, {
        "BM": "6000000000000000000",
        "MC": "未发生销售行为的不征税项目",
        "SLV": "",
        "ZZSTSGL": "",
        "HZX": "Y",
        "KYZT": "Y",
        "BMJC": "不征税项目",
        "YPBZ": "0",
        "LCOUNT": 1
    }],
    "code": 0,
    "result": true,
    "msg": "成功"
}

使用示例

// 查询等级分类
const pbs = require('yun2-pbs-unicloud')
const data = {
    layer : '0',
    BM : ''
}
await pbs.getEtaxGoodsCates(data)

// 查询第一级分类“货物”的子分类
const pbs = require('yun2-pbs-unicloud')
const data = {
    layer : '1',
    BM : '1000000000000000000'
}
await pbs.getEtaxGoodsCates(data)

查询税务局税种分类名称

允许用户输入关键字查询指定的税种分类 await pbs.searchEtaxGoodsCates(data)

入参data字段说明

返回值说明