Kendi kendine barındırılan bir Flask uygulaması Belçika'nın zorunlu Peppol e-fatura kurallarıyla nasıl tanıştı

Bir zorunluluk, hoş bir ekstra olmaktan çıkıp gereklilik haline geldi

1 Ocak 2026'dan bu yana Belçikalı işletmeler B2B faturaları Peppol ağı üzerinden yapılandırılmış e-faturalar olarak göndermek zorunda; bir e-postaya eklenmiş PDF artık geçerli sayılmıyor. Bu değişiklik, ağırlıklı olarak Belçikalı freelancerlar ve ekipler için geliştirilen, içinde faturalama özelliği de barındıran açık kaynaklı ve kendi kendine barındırılan bir zaman takip uygulaması olan TimeTracker'ın geliştiricisini e-fatura desteği eklemeye iten şey oldu. dev.to'daki bir yazıda yazar, işin içindeki standartları, çalışmayı kendi kendine barındırılan bir uygulama için yönetilebilir kılan mimariyi ve beklentiden daha zor olan kısımları belgeliyor. Yazının bir uyarısı var: Bu hukuki ya da vergi danışmanlığı değildir ve okuyucular Belçika FPS Finance'ın resmi kılavuzlarına başvurmalıdır.

Standartların tasfiyesi

Yazı, iç içe geçen kısaltmaları ayırarak başlıyor. EN 16931, Avrupa'nın anlamsal veri modelidir: bir e-faturada hangi alanların bulunması gerektiğini — satıcı, alıcı, KDV dökümü, toplamlar — tanımlar ama bir dosya formatı değildir. UBL 2.1 ve CII, bu veriyi taşıyabilen iki XML sözdizimidir. Peppol BIS Billing 3.0, EN 16931'in üzerine Peppol ağının kurallarını ekler ve UBL ile ifade edilir. Peppol'un kendisi ise taşıma katmanıdır: işletmelerin sertifikalı Access Point'ler üzerinden bağlandığı, sözde 4-köşe modeli denilen bir ağ. Factur-X ve ZUGFeRD ise hibrit bir formattır: içinde gömülü CII XML'i bulunan, insan tarafından okunabilir bir PDF. Peppol UBL isterken Factur-X CII istediği için TimeTracker ikisini de üretiyor.

Access Point olmaya kalkmayın

Prensipte bir uygulama Peppol'u kendisi konuşabilir: alıcıyı SML/SMP dizininde arar ve doğru sertifikalarla imzalarla AS4 üzerinden gönderir. Yazar, aramayı ve gönderimi yapan deneysel bir yerel modül geliştirdi, ancak bu modülde WS-Security, dijital imzalar ve alındı işleme yok ve Access Point sertifikasyonu başlı başına bir iş — freelancerlar tarafından kullanılan kendi kendine barındırılan bir uygulama için yanlış katman.

Önerilen yol ince bir HTTP sözleşmesi. TimeTracker, UBL belgesini oluşturur ve gönderici ile alıcı endpoint ID'leri, belge türü ve süreç ID'si gibi yönlendirme üst verileriyle birlikte bir adapter URL'sine POST eder. Adapter, belgeyi kullanıcının zaten anlaşmalı olduğu sertifikalı Access Point sağlayıcısına iletir. 400 ve üzeri her HTTP durumu bir denemeyi başarısız sayılır ve her deneme saklanır, böylece fatura sayfası tam bir gönderim geçmişi gösterebilir.

Bir köprü sidecar'ı sağlayıcı tuhaflıklarını izole ediyor

Kendi kendine barındıran kullanıcılardan kendi adapter'lerini yazmalarını istemek yerine proje, uygulamanın yanında Docker Compose ile çalışan ve /health, /test ve /send uçlarını sunan küçük bir peppol-bridge servisi ile geliyor. Sağlayıcı farkları köprünün içinde kalır — bir sağlayıcı Bearer token yerine X-Api-Key başlığıyla kimlik doğrulaması yapar — böylece yeni bir sağlayıcı eklemek, faturalama kodunu değiştirmek yerine bir ön ayar eklemek demektir. Bir yönetici kurulum sihirbazı Compose parçasını üretir ve uygulamayı köprüye yönlendirir.

Tanımlayıcılar ve tek anahtarlı uyumluluk

Peppol tarafları bir scheme ID artı bir endpoint ID ile tanımlanır; Belçikalı şirketler için bu genellikle işletme numarasıyla birlikte 0208 şemasıdır. İki ders öne çıkıyor: hatalı biçimlendirilmiş ID'ler aksi halde sağlayıcının API'sinin derinliklerinde yararsız hata mesajlarıyla başarısız olduğu için, sunucudan hiçbir şey çıkmadan önce hem gönderici hem alıcı tanımlayıcılarını doğrulayın; ve endpoint'leri müşteri başına saklayın, gönder düğmesi yalnızca her iki taraf da yapılandırıldığında görünsün.

Çoğu kullanıcı BT-kodları hakkında düşünmek istemez, bu yüzden tek bir yönetici anahtarı zorunlu BIS Billing 3.0 öğelerini ekler — InvoiceTypeCode 380 ve proje adına, sonra fatura numarasına düşen bir alıcı referansı gibi — bir şirket vergi numarası veya endpoint eksik olduğunda uyarılar gösterir ve asıl gönderimi muhasebecisi yapan kullanıcılar için bir UBL İndir düğmesi ekler.

Factur-X: zor olan kısım PDF'ydi

XML'i bir PDF'e gömmek önemsiz görünse de doğrulayıcılar bunun nasıl yapılacağı konusunda katıdır. Dışa aktarma, factur-x.xml'i doğru ilişki, MIME türü ve Factur-X XMP üst verisiyle bir PDF Associated File olarak gömer, dosyayı tek bir pikepdf geçişinde isteğe bağlı olarak PDF/A-3b'ye normalize eder, PDF/A doğrulayıcıları birçok üreticinin varsayılan olarak gömmediği base-14 fontları reddettiği için Liberation fontlarını gömer ve uygunluğu doğrulamak için veraPDF çalıştırabilir. Yazarın bunu yapan herkese kuralı: gürültülü biçimde başarısız olun. Gömme başarısız olursa dışa aktarma durur; kullanıcıya uyumlu sanılan düz bir PDF sessizce üretilmez ve satıcı ya da alıcı ülkesi eksik olduğunda ya da ters vergi uygulaması alıcı vergi numarası olmadan kullanıldığında, gönderim öncesi kontroller indirmeyi engeller.

Neden önemli

Belçika'nın zorunluluğu, işletmelerinin birbirini faturalamak için kullandığı her yazılım için geçerlidir; uyumluluğu adına halledecek bir satıcısı olmayan kendi kendine barındırılan ve açık kaynaklı araçlar dahil. Bu yazı, bu durum için işleyen bir şablondur: Access Point işinden uzak durun, sağlayıcı farklarını bir sidecar'a itin, tanımlayıcıları erken doğrulayın, eksik veriyi gönder düğmesi görünmeden önce ortaya çıkarın ve yalnızca uyumlu görünen dosyalar üretmeyi reddedin. Benzer kuralları benimseyen herhangi bir yetki alanında faturalama özelliklerinin geliştiricileri için, zor kazanılan ayrıntılar — PDF/A için font gömme, gürültülü başarısızlıkla dışa aktarma, müşteri başına endpoint'ler — gerçekten işe yarayan kısımdır.