내가 Medusa v2용 Lexware Office 통합을 만든 방법
Source: Dev.to
소개
저는 뮌헨에서 꽃가게를 운영하고 있으며 최근 전체 전자상거래 시스템을 Medusa v2 로 이전했습니다. 가게, 구독 서비스, 대시보드 – 모든 것이 이제 Medusa에서 구동됩니다.
완전히 빠져 있던 한 가지가 있었습니다: 독일 소기업에서 가장 많이 쓰이는 회계 소프트웨어 Lexware Office 와의 연동. 주문이 들어올 때마다 수동으로 청구서를 만들었습니다. 하루에 5~10건의 주문이 있으면 금방 지치게 됩니다.
그래서 저는 LexBridge 를 만들었습니다 – 전체 청구서 발행 워크플로우를 자동화하는 오픈소스 Medusa v2 플러그인입니다.
기능
고객이 주문을 하면 플러그인은:
- Lexware에서 고객을 조회하거나(또는 새 연락처를 생성)
- 모든 라인 아이템, 세율, 결제 조건을 포함한 청구서를 생성하고
- Lexware에서 최종 PDF를 다운로드하고
- 데이터베이스에 청구서 레퍼런스를 저장합니다
모든 설정은 Medusa Admin UI를 통해 구성할 수 있으며, 설치 후 코드 변경이 필요 없습니다.
까다로운 부분
독일 세율
독일은 식품/꽃에 대해 7 %, 그 외에는 19 %의 세율을 적용합니다. 하나의 주문에 서로 다른 세율을 가진 상품이 포함될 수 있습니다. 플러그인은 taxRateOverride 콜백을 지원하여 라인 아이템별로 직접 로직을 정의할 수 있게 합니다.
결제 수단별 결제 조건
PayPal로 결제하는 고객은 “즉시 결제”가 되어야 하고, 청구서 결제 B2B 고객은 “14일”이 되어야 합니다. 플러그인은 결제 제공자별로 이를 설정할 수 있게 합니다.
Lexware API 특성
API는 초당 2회 요청 제한이 있으며 503 오류가 자주 발생합니다. 플러그인은 지수 백오프와 자동 재시도를 통해 이를 처리합니다.
멱등성
Medusa는 order.placed 이벤트를 여러 번 발생시킬 수 있습니다. order_id에 대한 고유 제약 조건을 두어 주문당 하나의 청구서만 생성되도록 보장합니다.
무료와 프로
- 핵심 기능 – 완전히 무료이며 오픈소스(MIT 라이선스).
- 프로 티어 – 신용 메모, 드라이‑런 모드, 웹훅 동기화, 이메일 알림 등 고급 기능을 추가합니다. 이 소액 유료 티어는 지속적인 개발을 지원하면서 기본 기능은 모두에게 무료로 제공됩니다.
기술 스택
- Medusa v2 모듈에 커스텀 서비스, 구독자, Admin UI 포함
- TypeScript 전면 사용
- 데이터베이스에 저장된 API 키를 위한 AES‑256‑GCM 암호화
- SMTP 이메일 전송을 위한 Nodemailer
- Medusa 고유 UI 컴포넌트로 만든 Admin UI
사용해 보기
npm install medusa-lexbridge- GitHub:
- Website:
- npm package:
독일/DACH 지역에서 Medusa 상점을 운영하면서 Lexware를 사용하고 있다면, 많은 수작업을 절감할 수 있을 것입니다. 피드백과 기여를 언제든 환영합니다!