ylhc-nuonuo

n8n节点用于集成诺诺开票API（符合官方API规范）

Package Information

Downloads: 1 weekly / 6 monthly
Latest Version: 1.0.2
Author: YLHC

Available Nodes

诺诺开票 icon
诺诺开票
与诺诺开票API交互

Documentation

n8n-nodes-ylhc-nuonuo

这是一个用于 n8n 的社区节点包，用于集成诺诺开票API。

NPM Version

n8n 是一个开源的工作流自动化平台。

功能特性

  • ✅ 电子发票查验
  • ✅ 电子发票开具
  • ✅ 电子发票红冲
  • ✅ 发票开具结果查询
  • ✅ 支持沙箱环境和生产环境
  • ✅ HMAC-SHA1 签名认证

安装

社区节点安装（推荐）

在 n8n 中安装社区节点：

  1. 进入 Settings → Community Nodes
  2. 选择 Install
  3. 输入 n8n-nodes-ylhc-nuonuo
  4. 点击 Install

手动安装

要手动安装此节点，请运行以下命令：

npm install n8n-nodes-ylhc-nuonuo

配置凭证

在使用此节点前，你需要配置诺诺开票API凭证：

  1. 环境: 选择"沙箱环境"或"生产环境"
  2. App Key: 你的应用标识（appKey）
  3. App Secret: 你的应用密钥（appSecret）
  4. Access Token: 访问令牌
  5. 税号: 企业税号

注意: Senid（会话标识）会在每次请求时自动生成，无需手动配置。

获取凭证

  1. 访问 诺诺开放平台
  2. 注册并创建应用
  3. 在应用管理中获取 App Key 和 App Secret
  4. 申请访问令牌（Access Token）和企业税号

使用方法

1. 查验电子发票

查验发票真伪和状态。

必填参数：

  • 发票号码: 发票号码（全电票为20位）
  • 开票日期: 开票日期，格式：yyyy-MM-dd
  • 校验字段:
    • 专用发票/数电纸专/机动车发票/数电机动车发票(纸质)：不含税金额
    • 增值税普通发票/普通发票(电子)/普通发票(卷票)/普通发票(通行费)：校验码后6位

可选参数：

  • 发票代码: 发票代码（全电票为空）
  • 企业税号: 企业税号

示例：

{
  "invoiceNo": "24502000000067087970",
  "invoiceDate": "2024-07-23",
  "optionField": "102460",
  "invoiceCode": "",
  "taxNo": ""
}

参考文档: 诺诺发票查验接口规范

2. 开具电子发票

开具新的电子发票。支持数电票和全电票。

必填参数：

  • 订单号: 企业内部订单号（唯一）
  • 购方名称: 购买方企业名称
  • 发票明细: JSON格式的发票明细数组

注意: 销方税号自动从凭证配置中获取，无需手动输入

可选参数：

  • 开票类型:
    • 1: 蓝票（默认）
    • 2: 红票（数电票冲红请对接数电快捷冲红接口）
  • 发票票种:
    • pc: 电子发票(普通发票)（默认）
    • bs: 电子发票(增值税发票)
    • es: 数电纸质发票(增值税专用发票)
    • ec: 数电纸质发票(普通发票)
  • 购方税号: 购买方纳税人识别号
  • 购方电话: 购买方联系电话
  • 购方手机: 购买方手机号（pushMode为1或2时必填，同时受企业资质是否必填控制）
  • 购方地址: 购买方地址
  • 购方银行账号: 购买方开户行及账号
  • 销方电话: 销售方联系电话
  • 销方地址: 销售方地址
  • 销方银行账号: 销售方开户行及账号
  • 开票员: 开票人员姓名（默认：管理员）
  • 收款人: 收款人姓名
  • 复核人: 复核人姓名
  • 备注: 发票备注信息
  • 推送邮箱: 推送邮箱地址（pushMode为0或2时必填，同时受企业资质是否必填控制）

发票明细示例：

[
  {
    "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版二联/五联/增值税专用发票）

示例：

{
  "orderNo": "20250623221952851952",
  "taxNum": "338801999999001",
  "billNo": "20230208954578356839",
  "billUuid": "1d7f08b6ddb64cb19b095b0360f074d7",
  "elecInvoiceNumber": "23312000000000540837",
  "invoiceLine": "pc"
}

4. 查询发票列表

查询发票列表信息。支持按不同时间维度查询已开具的发票。

必填参数：

  • 请求类型: 查询时间类型
    • 0: 按发票添加时间查询（默认）
    • 1: 按开票时间查询
    • 2: 按发票状态更新时间查询
  • 开始时间: 时间起始值，格式：yyyy-MM-dd HH:mm:ss
  • 结束时间: 时间结束值（起始时间跨度不能超过10天），格式：yyyy-MM-dd HH:mm:ss
  • 当前页: 当前页码
  • 每页条数: 每页显示的记录条数

注意: 企业税号自动从凭证配置中获取，无需手动输入

示例：

{
  "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. 分页批量查询发票列表

参考文档: 诺诺发票列表查询接口规范

自定义请求体

所有操作都支持"自定义请求体"参数，如果填写此参数，则会忽略其他参数，直接使用自定义的JSON请求体。

查验发票示例：

{
  "invoiceNo": "24502000000067087970",
  "invoiceDate": "2024-07-23",
  "optionField": "102460"
}

开发

前置要求

  • Node.js >= 18.17.0
  • npm 或 pnpm

本地开发

# 克隆仓库
git clone <your-repo-url>
cd n8n-nodes-ylhc-nuonuo

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（监听文件变化）
npm run dev

# 代码检查
npm run lint

# 代码格式化
npm run format

在本地n8n中测试

  1. 构建节点：
npm run build
  1. 创建软链接到本地n8n：
cd ~/.n8n/custom
npm link /path/to/n8n-nodes-ylhc-nuonuo
  1. 重启n8n

API 方法映射

节点操作 API方法 说明
查验发票 nuonuo.OpeMplatform.invoiceInspection 查验电子发票
开具发票 nuonuo.OpeMplatform.requestBillingNew 开具电子发票
查询发票 nuonuo.OpeMplatform.queryInvoiceList 查询发票列表
红冲发票 nuonuo.OpeMplatform.fastInvoiceRed 快速红冲电子发票

错误处理

节点默认在出错时会中断工作流。你可以在节点设置中启用"继续出错时"选项，这样即使请求失败，工作流也会继续执行。

成功响应格式

{
  "success": true,
  "result": {
    // API返回的具体数据
  },
  "code": "E0000",
  "describe": "成功"
}

错误响应格式

当API返回错误时（code不等于E0000）：

{
  "success": false,
  "error": "诺诺API错误 [错误代码]: 错误描述",
  "code": "错误代码",
  "describe": "错误描述",
  "originalResponse": {
    // 原始API响应
  }
}

常见错误代码

  • 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 编码。

注意事项

  1. 请确保在生产环境使用前，先在沙箱环境充分测试
  2. 保护好你的 App Secret 和 Access Token，不要泄露
  3. 发票明细金额需要精确到小数点后两位
  4. 税号格式需要符合国家标准
  5. 部分API可能需要特殊权限，请联系诺诺客服开通

相关链接

许可证

MIT

支持

如有问题或建议，请提交 Issue。

更新日志

1.0.0

  • ✨ 初始版本发布
  • ✅ 支持电子发票查验
  • ✅ 支持电子发票开具（支持多种发票类型）
  • ✅ 支持电子发票红冲（全额/部分红冲）
  • ✅ 支持发票查询
  • ✅ 支持沙箱和生产环境切换
  • ✅ 自动生成Senid（会话标识）
  • ✅ HMAC-SHA1签名认证
  • ✅ 完善的错误处理和响应格式
  • ✅ 支持发票推送（邮箱、手机号）
  • ✅ 支持自定义请求体
  • ✅ 详细的发票明细配置（含税率、规格等）

Discussion