我如何为 Medusa v2 构建 Lexware Office 集成

Source: Dev.to

介绍

我在慕尼黑经营一家花店，最近把整个电商系统迁移到了 Medusa v2。店铺、订阅服务、后台——一切现在都运行在 Medusa 上。

唯一完全缺失的东西是：与 Lexware Office（德国小企业最流行的会计软件）的连接。每笔订单都需要手动创建发票。每天 5–10 笔订单，这工作很快就会让人厌倦。

于是我打造了 LexBridge——一个开源的 Medusa v2 插件，能够自动化整个开票流程。

功能概述

当客户下单时，插件会：

• 在 Lexware 中查找客户（若不存在则创建新联系人）
• 根据所有商品行、税率和付款条件生成发票
• 从 Lexware 下载完成的 PDF
• 将发票引用存入数据库

所有配置均可通过 Medusa 管理后台完成——安装后无需修改代码。

难点

德国税率

德国对食品/花卉适用 7 % 税率，对其他商品适用 19 % 税率。一次订单中可能包含不同税率的商品。插件支持 taxRateOverride 回调，允许你为每个商品行自定义逻辑。

按支付方式设置付款条件

使用 PayPal 支付的客户应“立即到期”，而使用发票付款的 B2B 客户则应“14 天后到期”。插件可以针对不同支付提供商进行配置。

Lexware API 的怪癖

该 API 的速率限制为 每秒 2 次请求，且经常返回 503 错误。插件通过指数退避和自动重试来处理这些情况。

幂等性

Medusa 可能会多次触发 order.placed 事件。对 order_id 的唯一约束确保每个订单只会生成一张发票。

免费版与专业版

• 核心功能 – 完全免费且开源（MIT 许可证）。
• 专业版 – 增加了信用凭证、干运行模式、Webhook 同步和邮件通知等高级功能。这个小额付费层用于支持持续开发，同时保持核心功能对所有人免费。

技术栈

• Medusa v2 模块，包含自定义服务、订阅者和管理后台 UI
• 全程使用 TypeScript
• 使用 AES‑256‑GCM 加密存储在数据库中的 API 密钥
• Nodemailer 负责 SMTP 邮件发送
• 管理后台使用 Medusa 原生 UI 组件构建

尝试使用

npm install medusa-lexbridge

• GitHub:
• Website:
• npm package:

如果你在德国/DACH 区域运营 Medusa 商店并且需要对接 Lexware，这个插件可能会为你省下大量手动工作。欢迎提供反馈和贡献代码！