저는 Finance Ops이고, 개발자는 아닙니다. 그래도 브라우저에서 KoSIT-valid XRechnung 생성기를 만들었습니다
Source: Dev.to
번역할 텍스트가 제공되지 않았습니다. 번역이 필요한 전체 내용을 알려주시면 도와드리겠습니다.
배경
저의 주된 업무는 재무 운영 및 회계이며, 소프트웨어 엔지니어링이 아닙니다. DACH 지역에서는 회계사가 필요로 하는 것과 개발자가 만드는 것 사이의 격차가 실제로 존재하며—비용도 많이 듭니다—그래서 저는 직접 그 격차를 메우기로 결심했습니다.
규제 상황
Germany’s E‑Rechnungspflicht는 이제 이론에 그치지 않는다.
- B2G (Business‑to‑Government) 청구는 수년간 유효한 XRechnung을 요구해 왔다.
- B2B 도입은 단계적으로 진행된다: 2025년부터 수신, 매출 > €800 k인 경우 2027년부터 발행, 그리고 2028년부터 광범위한 채택.
A PDF— even a perfect one—는 충분하지 않다.
기존 솔루션
제가 찾은 모든 도구는 세 가지 범주 중 하나에 해당했습니다:
| 카테고리 | 예시 | 단점 |
|---|---|---|
| 엔터프라이즈 ERP | SAP, DATEV | 전체 XRechnung 지원하지만, 월 수백 유로의 비용이 발생합니다; 팀을 위해 설계되었으며 프리랜서는 대상이 아닙니다 |
| SaaS 인보이스 | Lexoffice, sevDesk | 구독 기반; 인보이스 데이터가 그들의 서버에 저장됩니다; 설계상 락인 발생 |
| CLI 도구 | Open‑source Java/Python libraries | java -jar와 같은 명령줄 도구를 실행할 수 있다고 가정합니다 |
놓친 중간
프리랜서, 1인 컨설팅 업체, 그리고 Kleinunternehmer가 공공기관(예: 함부르크 시청)에 분기별로 청구서를 발행해야 할 때 적합하고 저렴한 솔루션이 부족합니다. 바로 그들을 위해—그리고 저 자신을 위해—이것을 만들었습니다.
솔루션: 브라우저‑네이티브 XRechnung 생성기
- Zero‑server, zero‑account: 모든 처리는 브라우저 내에서 로컬로 수행되며, 데이터가 기기를 떠나지 않습니다.
- 실시간 데모: (로컬‑우선, 추적 없음)
- Validation: KoSIT Validator v1.6.2 (Config v3.0.2) + EN 16931. UBL 2.1 및 UN/CEFACT CII 구문을 모두 지원합니다.
- 소스 코드: (MIT 라이선스)
주요 특성
- Invoice data (client names, project descriptions, amounts, IBANs) 는 높은 신호성을 가집니다.
- XML generation, PDF rendering, 및 pre‑validation 은 브라우저에서 완전히 실행됩니다.
- Network traffic: 외부 요청이 전혀 없습니다 (DevTools 네트워크 탭을 통해 확인).
개발 접근 방식
내 역할은 “하루 종일 코딩”하는 개발자라기보다 아키텍트/오케스트레이터에 가깝습니다. 작업 흐름:
- EN 16931 사양을 읽고 도메인 모델을 TypeScript 타입으로 매핑합니다.
- 사양을 기반으로 검증 규칙을 정의합니다.
- 구문에 구애받지 않는 도메인 모델을 유지하면서 제너레이터를 구현합니다(동일한 Invoice 객체에서 UBL 2.1과 CII를 모두 생성).
AI 지원
구현의 일부는 제 아키텍처 하에 AI(Claude Code / Codex) 도움을 받아 진행했으며, 수동 검토와 검증 루프를 거쳤습니다. 이는 표준에 대한 깊은 이해를 요구했는데, 이해하지 못하는 KoSIT 스키마 검증 오류를 “프롬프트만으로” 넘어갈 수 없기 때문입니다.
가장 어려운 도전 과제
분기 로직 없이도 UBL 2.1과 CII 두 가지 구문을 출력할 수 있는 타입화된 도메인 모델을 구축하는 것이 가장 어려웠습니다. 동일한 인보이스 객체가 두 가지 구문 출력을 생성하도록 하면서 핵심 모델을 깔끔하게 유지하는 것이 핵심 과제였습니다.
배포
master에 대한 모든 푸시가 GitHub Actions 워크플로를 트리거하여 Cloudflare Pages에 빌드 및 배포합니다.- 서버, 컨테이너, 데이터베이스가 전혀 사용되지 않습니다.
- 정적 자산이 Cloudflare 엣지에 캐시되어 거의 제로에 가까운 지연 시간(“파일이 이미 존재합니다”)을 제공합니다.
Lessons Learned
- 전체 EN 16931 + CIUS 컨텍스트를 읽은 후에 코드를 건드리세요.
- XRechnung은 “단순히 독일식 quirks가 있는 XML”이 아닙니다. EN 16931 Core, CIUS, 그리고 KoSIT 프로파일 요구사항을 겹쳐서 적용합니다.
- URN 식별자만으로도 올바르게 맞추는 데 이틀이 걸렸으며, 청구서 데이터가 정확해도 검증 실패의 흔한 원인입니다.
- 타입이 지정된 상수(
constvalues in TypeScript) 덕분에 전체 오류 유형을 제거할 수 있었으며, 사전에 알면 좋습니다.
피드백 요청
XRechnung, EN 16931, 또는 Peppol을 사용해 본 경우:
- 운영 환경에서 가장 자주 보는 검증 오류는 무엇인가요?
- 고객사의 ERP가 UBL 또는 CII를 사용하고 있나요?
- 이 생성기를 여러분에게 유용하게 만들기 위해 꼭 필요한 한 가지 기능은 무엇인가요?
기술 분석
전체 아키텍처 및 코드 walkthrough는 다음에서 확인할 수 있습니다: