gabrielbuzziv/emissor-nfse-nacional

Emissor de NFS-e Nacional

项目介绍

这是一个自托管的巴西 NFS-e（电子服务发票）开具服务，直接调用国家 NFS-e API，不经过按票收费的中间商。它跑在你自己的 Cloudflare 账号上：Worker 通过 HTTP 接收销售数据，把发票存进 D1 数据库；Container 用你的 A1 证书对 XML 做签名，并通过双向 TLS 与政府系统通信。

使用 Container 的原因是政府服务器在连接已建立后才请求客户端证书（TLS 重协商），而 Workers 的 fetch 做不到这一点。每个请求携带调用方提供的 id，重复请求返回同一张发票，不会重复开具；如果政府的响应丢失，它会先确认发票是否已经开出，再决定是否重发。此外还支持取消发票、生成 DANFSe PDF（政府服务返回时用政府的，否则从已签名 XML 生成，并带公开查询二维码），以及为 PDF 和 XML 生成带签名的公开链接。

适用对象是希望在自己的系统里完成开票、又不想按票付费的服务提供商。README 说明它已为一家 Simples Nacional 的 ME/EPP 在生产环境开票；MEI 和非 Simples 企业虽然遵循官方布局，但尚未在生产环境测试。

快速使用

需要：所在城市已接入国家系统、服务商的 A1 e-CNPJ 证书（.pfx 及密码）、会计提供的税务信息、Cloudflare Workers Paid 账号，以及 Node.js 22.12 以上、pnpm（corepack enable）和本机运行的 Docker。

git clone https://github.com/gabrielbuzziv/emissor-nfse-nacional.git
cd emissor-nfse-nacional
pnpm install
pnpm wrangler login

填写 wrangler.jsonc 中的 vars，至少包括 NFSE_ENVIRONMENT（先用 restricted）、ISSUER_CNPJ、ISSUER_CITY_CODE、ISSUER_SIMPLES_OPTION，以及适用的 Simples 字段。然后部署并建表：

pnpm run deploy
pnpm run migrate

上传证书并创建 API 令牌：

pnpm run certificate caminho/do/certificado.pfx
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
pnpm wrangler secret put API_TOKEN

用 GET /health?deep=1 和 Authorization: Bearer 头检查安装情况，包括证书有效期和城市协议状态。接着在受限环境开一张测试发票并核对返回数据，再把 NFSE_ENVIRONMENT 改为 production、重新部署并开具第一张真实销售发票。响应包含 nfseNumber、accessKey 和 links（pdf、xml、lookup）；HTTP 200 表示已开具，422 表示被拒，202 表示结果未知/处理中，400 表示请求无效。

使用约束

该服务只覆盖常见场景：服务发生在服务商所在城市、ISSQN 应缴且未代扣；无特殊税制、扣除、折扣或发票上单列的联邦税；购买方仅以 CPF/CNPJ 标识且无地址，或不开具购买方；单一 DPS 系列且不做发票替换。取消期限因城市而异，且不支持替换发票。

成本包括每月 5 美元的 Cloudflare Workers Paid 套餐（容器定价）和每年续期的 A1 e-CNPJ 证书。受限环境不包含所有城市，部分用户无法在上线前测试开票。政府通过技术说明更改布局，src/dps.ts 需要跟进。API_TOKEN 只能放在服务端；更换令牌会使已发送的公开链接失效。项目采用 MIT 许可证，与巴西联邦税务局无关，开票责任由开票方承担——税务设置需与会计确认。参见国家 NFS-e 门户和技术文档。

HotRepo 点评

仓库在 2026-11-13 记录为 101 星、14 个 fork，当天首次进入新项目榜，在 2026-11-12T23:02 至 2026-11-13T04:15 UTC 约五小时的窗口内新增 101 星。目前仅此一条快照，只能说明当天的关注度，不能据此判断趋势。技术上值得注意的是拆分架构：Container 专门处理 Workers 运行时无法完成的 TLS 重协商，测试套件依据官方 XSD 校验文档并用 xmlsec1 检查签名——这些具体细节让项目关于生产使用的说法较为可信，但 MEI 和非 Simples 场景未经验证这一点仍然存在。