巴西经济全靠 SOAP 1.2 跑发票

Every invoice in Brazil's economy runs on SOAP 1.2. We mapped it all

▲ 58lestx34 HN 评论区

在巴西，每一张电子发票的流转都依赖着古老的 SOAP 1.2 协议。为了理清这套复杂的税务系统，开发者整理了一份完整的 Postman 集合，覆盖了 NF-e、NFC-e、CT-e 和 MDF-e 等核心文档类型。这套工具不仅封装了 SEFAZ 的 Web 服务接口，还解决了 mTLS 证书配置、XMLDSig 签名以及各州服务差异等棘手问题。其中，CT-e 和 MDF-e 的分布式服务甚至已在生产环境验证通过。对于需要对接巴西税务系统的开发者来说，这不仅是技术文档的集合，更是避开无数坑的实战指南，揭示了在现代化 API 浪潮下，传统协议如何支撑起一个国家的经济命脉。

巴西经济中的每一张发票都运行在 SOAP 1.2 上，我们将其全部绘制成了地图。
阅读原文 →HN 评论区RSS

HN 评论区

34
  1. pjmlp

    其实也没那么糟，至少 XML 对机器友好，支持 schema 验证，还能写注释，不像它的替代方案，非要重新发现这些功能为何重要。

    至于性能，大家也重新发现它们都不怎么样，于是 gRPC 又去重新发明了 CORBA、COM 和 Sun RPC。

  2. mhl47

    当我们把 ERP 系统部署到巴西子公司时，整个内部咨询团队立刻达成共识：别让我们的脑子被这种复杂性搞坏，赶紧雇个本地咨询团队来帮忙。而那个本地咨询团队反过来也立刻建议我们使用中间件服务商。

  3. Muromec

    这听起来很像乌克兰的收银机。每个零售操作都要经过税务局侧的收银机 API（毕竟谁不想把点现金藏到账外呢，对吧？），不过那边用的是 RESP+JSON，还有一堆帮你跑这套系统的小作坊式服务。如果不是偷偷把整套 PKI 塞进来，其实也没那么难。

  4. lestx

    巴西运行着地球上最大的强制性电子发票系统。在这个 2 万亿美元的经济体中，每一张发票、每一车货物、每一张零售小票都要经过政府的 SOAP 1.2 Web 服务。而且是在 2026 年。

    想集成？文档是四本 PDF 手册，加起来超过 1000 页，分散在不同门户上，关键细节根本没写在任何地方。我们花了好几个小时调试才搞懂的两个例子：货运单（CT-e）和运单（MDF-e）实现了相同的分发规范，但信封格式不兼容（一个包裹了 payload 并要求作者状态码，另一个则拒绝该字段，要求把状态码放在 SOAP 头里）。而且 SOAP action 必须放在 Content-Type 头里；如果你像网上所有 SOAP 教程教的那样发送 SOAPAction 头，服务器会直接拒绝你，还不解释原因。

    所以我们将 4 种文档模型下的全部 29 个 Web 服务映射到了一个 Postman 集合中：现成的信封、针对每个主机的 mTLS 证书配置文档齐全，分发服务也针对生产环境的政府端点进行了验证，而不仅仅是照手册写的。

    哪里可以改进：巴西有 27 个州，其中几个州运行自己的授权者 URL（比如圣保罗州的零售发票）。我们覆盖了共享授权者加上国家环境；州特定的 URL 映射是首要的开放贡献项。该集合由 Python 清单文件生成，所以提 PR 只需改 5 行 diff，不用动 JSON 手术。

    文档 […]

同日更多故事

2026-09-15