n8n节点用于集成诺诺开票API(符合官方API规范)
npm install n8n-nodes-ylhc-nuonuon8n-nodes-ylhc-nuonuo
bash
npm install n8n-nodes-ylhc-nuonuo
`
配置凭证
在使用此节点前,你需要配置诺诺开票API凭证:
1. 环境: 选择"沙箱环境"或"生产环境"
2. App Key: 你的应用标识(appKey)
3. App Secret: 你的应用密钥(appSecret)
4. Access Token: 访问令牌
5. 税号: 企业税号
注意: Senid(会话标识)会在每次请求时自动生成,无需手动配置。
$3
1. 访问 诺诺开放平台
2. 注册并创建应用
3. 在应用管理中获取 App Key 和 App Secret
4. 申请访问令牌(Access Token)和企业税号
使用方法
$3
查验发票真伪和状态。
必填参数:
- 发票号码: 发票号码(全电票为20位)
- 开票日期: 开票日期,格式:yyyy-MM-dd
- 校验字段:
- 专用发票/数电纸专/机动车发票/数电机动车发票(纸质):不含税金额
- 增值税普通发票/普通发票(电子)/普通发票(卷票)/普通发票(通行费):校验码后6位
可选参数:
- 发票代码: 发票代码(全电票为空)
- 企业税号: 企业税号
示例:
`json
{
"invoiceNo": "24502000000067087970",
"invoiceDate": "2024-07-23",
"optionField": "102460",
"invoiceCode": "",
"taxNo": ""
}
`
> 参考文档: 诺诺发票查验接口规范
$3
开具新的电子发票。支持数电票和全电票。
必填参数:
- 订单号: 企业内部订单号(唯一)
- 购方名称: 购买方企业名称
- 发票明细: JSON格式的发票明细数组
> 注意: 销方税号自动从凭证配置中获取,无需手动输入
可选参数:
- 开票类型:
- 1: 蓝票(默认)
- 2: 红票(数电票冲红请对接数电快捷冲红接口)
- 发票票种:
- pc: 电子发票(普通发票)(默认)
- bs: 电子发票(增值税发票)
- es: 数电纸质发票(增值税专用发票)
- ec: 数电纸质发票(普通发票)
- 购方税号: 购买方纳税人识别号
- 购方电话: 购买方联系电话
- 购方手机: 购买方手机号(pushMode为1或2时必填,同时受企业资质是否必填控制)
- 购方地址: 购买方地址
- 购方银行账号: 购买方开户行及账号
- 销方电话: 销售方联系电话
- 销方地址: 销售方地址
- 销方银行账号: 销售方开户行及账号
- 开票员: 开票人员姓名(默认:管理员)
- 收款人: 收款人姓名
- 复核人: 复核人姓名
- 备注: 发票备注信息
- 推送邮箱: 推送邮箱地址(pushMode为0或2时必填,同时受企业资质是否必填控制)
发票明细示例:
`json
[
{
"goodsName": "技术服务软件开发",
"num": "1",
"price": "1000.00",
"taxExcludedAmount": "1000.00",
"taxRate": "0.06",
"withTaxFlag": 1
},
{
"goodsName": "信息技术服务技术咨询",
"num": "2",
"price": "500.00",
"taxExcludedAmount": "1000.00",
"taxRate": "0.06",
"withTaxFlag": 1
}
]
`
发票明细字段说明:(符合诺诺开票API规范)
- goodsName: 商品或服务名称(必填),格式:大类商品名称(如:技术服务软件开发)
- num: 数量(必填),字符串格式
- price: 单价(必填),字符串格式
- taxExcludedAmount: 不含税金额(必填),字符串格式
- taxRate: 税率(必填),小数格式(如:"0.06" 表示6%,"0.13" 表示13%,"0" 表示0%)
- withTaxFlag: 含税标志(必填),数字类型
- 1: 含税
- 0: 不含税
> 参考文档: 诺诺开票接口规范
$3
对已开具的发票进行红冲(作废)。支持全电发票和数电发票的快速红冲。
必填参数:
- 订单号: 订单号(企业内唯一)
- 红字确认单编号: 红字确认单编号或红电子发票号
- 红字确认单UUID: 红字确认单uuid
> 注意: 销方企业税号自动从凭证配置中获取,需要校验与开具方红字发票的税号一致
可选参数:
- 分机号: 分机号(只能为数载数字)
- 开票员ID: 开票员id(诺诺系统中的id)
- 部门ID: 部门id(诺诺系统中的id)
- 单据时间: 单据时间
- 对应蓝字发票代码: 对应蓝字原值发票代码
- 对应蓝字发票号码: 对应蓝字原值发票号码(传入20位发票号码,则当做数电票码处理)
- 对应蓝字数电票号: 对应蓝字数电票号(蓝票为数电票时,请传入该字段)
- 对应蓝票发票流水号: 对应蓝票发票流水号
- 数电发票票种: bs/pc/es/ec(电子发票/普通发票/数电纸质专票/数电纸质普票)
- 数电纸质发票类型: 04/05/11300(2016版二联/五联/增值税专用发票)
示例:
`json
{
"orderNo": "20250623221952851952",
"taxNum": "338801999999001",
"billNo": "20230208954578356839",
"billUuid": "1d7f08b6ddb64cb19b095b0360f074d7",
"elecInvoiceNumber": "23312000000000540837",
"invoiceLine": "pc"
}
`
$3
查询发票列表信息。支持按不同时间维度查询已开具的发票。
必填参数:
- 请求类型: 查询时间类型
- 0: 按发票添加时间查询(默认)
- 1: 按开票时间查询
- 2: 按发票状态更新时间查询
- 开始时间: 时间起始值,格式:yyyy-MM-dd HH:mm:ss
- 结束时间: 时间结束值(起始时间跨度不能超过10天),格式:yyyy-MM-dd HH:mm:ss
- 当前页: 当前页码
- 每页条数: 每页显示的记录条数
> 注意: 企业税号自动从凭证配置中获取,无需手动输入
示例:
`json
{
"taxnum": "339901999999212",
"requestType": "0",
"startTime": "2019-03-04 00:00:00",
"endTime": "2019-03-09 00:00:00",
"pageNo": "1",
"pageSize": "20"
}
`
使用场景:
1. 查询已开具的发票详细信息
2. 按不同时间维度筛选发票
3. 分页批量查询发票列表
> 参考文档: 诺诺发票列表查询接口规范
$3
所有操作都支持"自定义请求体"参数,如果填写此参数,则会忽略其他参数,直接使用自定义的JSON请求体。
查验发票示例:
`json
{
"invoiceNo": "24502000000067087970",
"invoiceDate": "2024-07-23",
"optionField": "102460"
}
`
开发
$3
- Node.js >= 18.17.0
- npm 或 pnpm
$3
`bash
克隆仓库
git clone
cd n8n-nodes-ylhc-nuonuo
安装依赖
npm install
构建
npm run build
开发模式(监听文件变化)
npm run dev
代码检查
npm run lint
代码格式化
npm run format
`
$3
1. 构建节点:
`bash
npm run build
`
2. 创建软链接到本地n8n:
`bash
cd ~/.n8n/custom
npm link /path/to/n8n-nodes-ylhc-nuonuo
`
3. 重启n8n
API 方法映射
| 节点操作 | API方法 | 说明 |
|---------|---------|------|
| 查验发票 | nuonuo.OpeMplatform.invoiceInspection | 查验电子发票 |
| 开具发票 | nuonuo.OpeMplatform.requestBillingNew | 开具电子发票 |
| 查询发票 | nuonuo.OpeMplatform.queryInvoiceList | 查询发票列表 |
| 红冲发票 | nuonuo.OpeMplatform.fastInvoiceRed | 快速红冲电子发票 |
错误处理
节点默认在出错时会中断工作流。你可以在节点设置中启用"继续出错时"选项,这样即使请求失败,工作流也会继续执行。
$3
`json
{
"success": true,
"result": {
// API返回的具体数据
},
"code": "E0000",
"describe": "成功"
}
`
$3
当API返回错误时(code不等于E0000):
`json
{
"success": false,
"error": "诺诺API错误 [错误代码]: 错误描述",
"code": "错误代码",
"describe": "错误描述",
"originalResponse": {
// 原始API响应
}
}
`
$3
- E0000: 成功
- E1001: 参数错误
- E1002: 签名错误
- E1003: 认证失败
- E2001: 发票不存在
- E2002: 发票已作废
签名算法
本节点使用 HMAC-SHA1 算法生成请求签名,签名参数格式:
`
a=services&l=v1&p=open&k={appkey}&i={senid}&n={nonce}&t={timestamp}&f={content}
`
使用 appSecret` 作为密钥进行 HMAC-SHA1 加密,然后 Base64 编码。