Ülke Bazlı KDV Raporlamasının ve VIES Doğrulamasının Otomasyonu

Bulut muhasebe API'si kullanarak AB KDV uyumluluğunu pazaryerlerine ve platformlara entegre eden geliştiriciler için pratik bir rehber.

Platform kodundaki KDV hatalarının çoğu tek bir varsayıma dayanır: Geçerli bir VIES sonucunun, satışa sıfır oran (zero-rate) uygulayabileceğiniz anlamına geldiği varsayımı. Öyle değildir ve bu kestirme yola dayanarak sistem inşa etmek, bir denetçi nakliye kanıtı veya tutarlı bir tedarik yeri (place-of-supply) kaydı olmadan AB içi muafiyetin neden uygulandığını sorana kadar düzgün görünen beyannameler üretir. "KDV numarası tutuyor" ile "bu teslimat doğru değerlendiriliyor" arasındaki boşluk, entegrasyonların çoğunun sessizce raydan çıktığı yerdir.

Bu rehber, Nordlet muhasebe API'sini uygulama bağlamı olarak kullanarak bulut muhasebe API'si aracılığıyla ülke bazlı KDV raporlamasının ve VIES doğrulamasının nasıl otomatikleştirileceğini ele almaktadır. Buradaki amaç; daha sonra bir e-tabloda (spreadsheet) toplamları yeniden oluşturmak zorunda kalmadan, satış anında doğru kanıtları yakalayan, değiştirilemez (immutable) defter kayıtları oluşturan ve şemaya ile Üye Devlete göre gruplandırılmış beyannameye hazır veriler üreten bir sistem kurmaktır.

VIES size aslında ne söyler, neyi söylemez

VIES, AB KDV Bilgi Değişim Sistemi'dir (EU VAT Information Exchange System). Bir ülke kodu ve KDV numarası gönderdiğinizde, ilgili ulusal veritabanını gerçek zamanlı olarak sorgular ve bu KDV bilgisinin geçerli mi yoksa geçersiz mi olduğunu döner. Kapsamın tamamı bundan ibarettir. Bir numaranın kayıtlı olduğunu ve Üye Devlet destekliyorsa AB içi ticaret için etkinleştirildiğini doğrular.

Topluluk içi bir teslimatı muaf tutma hakkını tesis etmez. Avrupa Komisyonu bu konuda oldukça açıktır. Geçerli bir VIES yanıtı, birkaç kanıt parçasından yalnızca biridir. Müşterinin gerçek alıcı olduğunu, teslimatın AB içi niteliği taşıdığını, nakliye veya sevkiyat kanıtının mevcut olduğunu ve faturanın gerekli tevkifat (reverse-charge) ibaresini taşıdığını yine de teyit etmeniz gerekir.

Dolayısıyla ilk tasarım kararı yapısal olmalıdır: VIES durumu ile KDV muamelesini ayrı alanlarda tutun. viesStatus: valid değerini doğrudan zeroRated: true değerine asla bağlamayın. Bu iki kavramı tek bir yerde birleştirdiğiniz anda, kanıt sorgulandığında bir muameleyi savunma yeteneğinizi kaybedersiniz.

Entegrasyon kodu yazmadan önce yapılması gerekenler

Herhangi bir uç nokta (endpoint) çağrılmadan önce, raporladığınız şeyin kapsamını tanımlayın. Bu kısım sıkıcıdır ve atlamak pahalıya mal olur.

İşletmenin kurulduğu veya sabit iş yerlerinin bulunduğu ülkeler
KDV kaydının bulunduğu ülkeler
Mal, hizmet, dijital hizmet veya bunların bir karışımının satılıp satılmadığı
İşlemlerin B2B, B2C veya her ikisi olup olmadığı
Yerel kayıtlar, OSS, IOSS, tevkifat veya pazaryeri sorumlu sıfatı (deemed-supplier) kurallarının kullanılıp kullanılmadığı
API'nin üretmesi gereken çıktılar: yerel beyanname verileri, OSS/IOSS verileri, Litvanya'nın i.SAF'ı gibi fatura defterleri, yalnızca defter kayıtları (ledger postings) veya ayrı bir beyanname sağlayıcısı için veri yükleri (payloads)

Bu durum önemlidir çünkü OSS her işlemesi gereken kalemi kapsamaz. İşletmenin iş yerinin bulunduğu bir ülkede sağlanan hizmetler, OSS beyannamesine değil, genellikle o ülkenin yerel beyannamesine aittir. İş yerlerini baştan ayrı modelleyin, aksi takdirde toplama (aggregation) aşamasında bu teslimatları yanlış yönlendirirsiniz.

Her ülke için tek bir KDV oranını da koda sabitlemeyin (hard-code). AB'de standart, indirilmiş, süper indirilmiş, otopark (parking), sıfır oranlı ve ürüne özel muameleler bulunur ve bunlar değişir. Belirli bir Üye Devletteki belirli bir ürün için güvenilir kaynak, Komisyon'un TEDB'sine (taxes in Europe database) genel bir bakış sunan ilgili ülkenin vergi idaresidir. Daha sonra yapılacak bir oran tablosu güncellem国的 eski bir işlemin nasıl göründüğünü sessizce yeniden yazmaması için her oran kararının arkasındaki kaynağı ve sürümü kaydedin.

Yalnızca oranı değil, vergi kararını modellemek

Dayanıklı bir entegrasyonun özü, ürünler ile oranlar arasında yer alan bir vergi kategorisi (tax-category) katmanıdır. Ürünleri kategorilere, kategorileri ülkeye özel vergi kodlarına ve ardından yürürlük tarihi olan oranlara (effective-dated rates) eşleyin:

product/service
    → tax category
    → country-specific tax code
    → effective-dated rate and treatment

Raporlama sapmasına neden olan güvenli olmayan yaklaşım ürün SKU'su → %21 KDV biçimidir. Aynı ürün farklı ülkelerde farklı oranlara sahiptir ve bir oran dönem ortasında değişebilir. Nordlet'in kendi KDV uyumluluk rehberi, ürünleri doğrudan yüzdelere bağlamak yerine tam olarak bu kategori tabanlı eşleştirmeyi önermektedir.

Vergi kategorisi taksonominiz kararlı ve dahili olmalıdır: standart oranlı mallar, indirimli oranlı mallar, elektronik yolla sunulan hizmetler, olağan hizmetler, muaf teslimat, sıfır oranlı teslimat, AB içi B2B tevkifatı, AB içi mesafeli satış, IOSS ithalatı, sorumlu sıfatıyla (deemed-supplier) yapılan işlem. Akıştaki her şey bu taksonomiye dayanır.

Asenkron bir kanıt iş akışı olarak VIES doğrulaması

Resmi VIES hizmeti, iki harfli ülke kodu ve KDV numarası alan bir SOAP/WSDL arayüzü sunar. Belgelenmiş hataları hata yönetiminiz açısından önemlidir: geçersiz girdi, küresel ve Üye Devlet eşzamanlılık sınırları (concurrency limits), hizmetin kullanılamaması, Üye Devletin kullanılamaması ve zaman aşımı. Bunları tek bir "başarısız" çuvalı olarak değil, ayrı sonuçlar olarak ele alın.

Yük (load) ve denetim altında ayakta kalan bir iş akışı şu şekildedir:

KDV kimliğini normalize edin: önekini büyük harfe dönüştürün, izin verilen boşlukları veya noktalama işaretlerini kaldırın ve kullanıcının girdiği orijinal değeri ayrı tutun.
Bir ağ çağrısı yapmadan önce ülke kodunu ve numara biçimini yerel olarak doğrulayın.
Normalize edilmiş numarayı VIES'e gönderin.
Normalize edilmiş kimliği, istek ve yanıt zaman damgalarını, geçerli/geçersiz/işlenmemiş (valid/invalid/not-processed) durumunu, ham yanıtı, olası hizmet hatalarını, müşteri ve fatura kimliklerini ile uygulama kararını saklayın.
Başarılı sonuçları tanımlanan, belgelenmiş bir süre boyunca önbelleğe (cache) alın.
Geçici teknik hataları artan bekleme süreleriyle (backoff) yeniden deneyin.
Çözümlenemeyen veya çelişkili durumları manuel incelemeye yönlendirin.
Önbelleğe alınmış bir sonuç eskidiğinde veya kanıtın önem arz ettiği bir işlemden önce yeniden doğrulama yapın.

Nordlet, bir müşteri eklendiğinde bir AB KDV numarasını kontrol eder ve önceki sonuç eskidiyse faturalandırmadan önce yeniden kontrol eder; bu, kontrolün platformda mı yoksa kendi kodunuzda mı yapıldığından bağımsız olarak taklit etmek isteyeceğiniz davranıştır.

Kritik kural: Ödeme adımını (checkout) VIES ile senkronize hale getirmeyin. Bir hizmet kesintisi, geçersiz bir numara değildir. Satış sırasında VIES zaman aşımına uğrarsa, işlemi inceleme için bekletin veya geçici bir durum atayın. Bir Komisyon hizmetinin çalışır durumuna bağlı olarak ödeme adımını bloke etmek bir destek talebi üretir ve iyi bir müşteriyi yanlışlıkla geçersiz olarak sınıflandırmak daha kötüdür.

Doğrulama durumunu muamelenin durumundan ayırmak

Bir VIES sonucuna sahip olduktan sonra, karar motorunun yapacak daha çok işi vardır. Bunları ayrı alanlar olarak saklayın:

{
  "viesStatus": "valid",
  "vatTreatment": "intra_eu_b2b_reverse_charge",
  "evidenceStatus": "reviewed",
  "placeOfSupply": "DE"
}

Tevkifat veya muafiyet uygulamadan önce motor; müşterinin gerçekten alıcı olup olmadığını, müşteri ülkesi ile KDV önekinin tutarlı olup olmadığını, teslimatın AB içi niteliği taşıyıp taşımadığını, özel tedarik yeri kurallarının geçerli olup olmadığını, nakliye kanıtının bulunup bulunmadığını, satıcının sorumlu tedarikçi (deemed supplier) olarak hareket edip etmediğini ve faturanın gerekli ibareyi içerip içermediğini test etmelidir. Bu diğer testlerin hiçbirini geçemeyen geçerli bir VIES durumu yeşil ışık yakmaz.

Fatura anında değiştirilemez bir KDV kararı oluşturmak

Fatura oluşturulduğunda, yalnızca nihai oranı değil, tüm kararı faturanın yanında kalıcı olarak saklayın:

invoice
  ├─ line tax category
  ├─ place of supply
  ├─ VAT scheme
  ├─ country-specific rate
  ├─ rate-table version
  ├─ VIES evidence reference
  ├─ location-evidence references
  ├─ legal-basis reference
  └─ marketplace-role flags

AB fatura kuralları; tedarikçi ve müşteri bilgilerini, fatura numarasını, açıklamayı, matrahı, KDV oranını, KDV tutarını ve herhangi bir tevkifat veya muafiyet bilgisini gerektirir. Alacak dekontları (credit notes) ve düzeltmeler, orijinal faturaya açık bir referans gerektirir.

Nordlet'in defteri değiştirilemezdir (immutable), bu nedenle düzeltmeler, kapalı kayıtlar üzerinde değişiklik yapmak yerine alacak dekontları veya ters kayıtlar gibi yeni girdiler aracılığıyla gerçekleştirilir. Saklama alanınız teknik olarak üzerine yazabilse bile tüketicinizi (consumer) bu modele göre tasarlayın. Kapalı bir faturayı düzenlemek, orijinal beyanname ile düzeltme arasındaki bağlantıyı yok eder; bu tam olarak bir denetçinin takip ettiği soy kütüğüdür.

Kayıt oluşturma (Posting), webhooks ve idempotency

Bir satış, hem ticari işlemi hem de ülkeye ve şemaya göre bölünmüş KDV yükümlülüğünü koruyan çift yönlü muhasebe kayıtları (double-entry accounting entries) oluşturur. Yerel bir satış şu şekilde kaydedilebilir:

Dr Accounts receivable / payment clearing
    Cr Revenue
    Cr VAT payable - DE - domestic

Çıkış KDV'si olmayan ve tevkifat kanıtına referans veren bir AB içi B2B tevkifatlı satış, gelir kaydeder. Kesin hesap planı size aittir; önemli olan raporlama boyutlarının her kayda bağlı kalmasıdır: Üye Devlet, şema, vergi kategorisi, oran, dönem, kaynak fatura ve düzeltme soy kütüğü.

Durum değişikliklerini yoklama (polling) yerine webhooks ile tetikleyin. Nordlet sale_invoice.paid gibi olaylar yayar, iletileri imzalar ve artan bekleme süreleriyle yeniden dener. Her yazma işlemine deterministik bir idempotency anahtarı (idempotency key) verin:

sale:{platform_order_id}:invoice:{invoice_version}

Tüketiciniz de idempotently çalışmalıdır. Bir webhook iki kez gelebilir, geç gelebilir veya orijinal istek zaten başarılı olduktan sonra tetiklenebilir. İmzaları doğrulayın, olay kimliklerini kaydedin, hatalı biçimlendirilmiş olayları karantinaya alın, dayanıklı bir kuyruk (queue) aracılığıyla işleyin ve webhook durumunu bir takvime göre API ile mutabık kılın (reconcile). Daha önce imzalı webhooks ve idempotency anahtarlarıyla çalışmadıysanız, en ince mükerrer kayıt (duplicate-entry) hataları burada yaşanır.

OSS için gruplandırma ve beyannameye hazır çıktılar üretme

Uygun OSS işlemleri için defter verilerini şemaya, tüketim Üye Devletine, teslimat türüne, oran kategorisine, orana, matraha, KDV tutarına, sevkiyat veya iş yeri Üye Devletine, para birimine ve düzeltme dönemine göre gruplandırın.

Birlik (Union) şeması beyannamesi, teslimatları tüketim Üye Devletine göre ayırır ve kimlik tespit Üye Devletindeki hizmetleri, diğer sabit iş yerlerindeki hizmetleri ve farklı Üye Devletlerden sevk edilen malları birbirinden ayırır. Standart ve indirimli oranlar için matrah ve KDV tutarlarını ayrı ayrı raporlar. Muaf ve sıfır oranlı teslimatlar OSS beyannamesinin tamamen dışında tutulur.

İnsanların gözünden kaçan birkaç operasyonel detay:

Birlik ve Birlik dışı OSS dönemleri üçer aylıktır; IOSS ise aylıktır. Beyannameler ve ödemeler takip eden ayın sonuna kadar yapılmalıdır.
İlgili hiçbir teslimat yapılmamış olsa bile her dönem için sıfırlık beyanname (nil return) verilmesi zorunludur. Bir dönem kontrol listesi oluşturun ve otomatik olarak sıfır değer mercancinde bir beyanname oluşturun.
OSS beyannameleri avro cinsinden yapılır; dönüştürme gerektiren durumlarda vergi döneminin son günündeki ECB (Avrupa Merkez Bankası) referans kuru kullanılır. Kaynak para birimini, döviz kurunu, kur tarihini, dönüştürülen tutarı ve yöntemi saklayın.

Çıktılar asla yan bir e-tablodan değil, kilitli defterden gelmelidir. E-tablo toplamları düzeltmeleri, sevkiyat ülkelerini, oranları ve kanıtları kaybeder. Bir çıktı; beyanname dönemini, şemayı, tüketim Üye Devletini, sevkiyat ülkesini, teslimat kategorisini, oranı, matrah ve KDV tutarlarını, para birimini ve uygulanan döviz kurunu, cari dönem ve önceki dönem düzeltme tutarlarını, kaynak fatura kimliklerini, alacak dekontu referanslarını ve mutabakat toplamlarını içerir.

API'nin burada ne sunduğu konusunda net olun. Nordlet, önceki dönem düzeltmeleri dahil faturalardan ve defterden OSS ve IOSS beyannamelerini hesaplar, Litvanya (FR0600), Almanya (UStVA) ve Polonya (JPK_V7M) için yerel beyanname paketleri gönderir ve Litvanya için VMI uyumlu i.SAF defterleri üretir. Bu, beyannameye hazır veridir. Tek bir API çağrısı her ülkenin KDV beyannamesini her ulusal ağ geçidi (gateway) üzerinden dosyalayamaz ve hiçbir beyanname sizin adınıza bir makama sunulmaz. Muhasebeyi, beyanname üretimini, çıktıyı, ağ geçidi gönderimini ve ödeme onayını sisteminizde ayrı durumlar olarak tutun. AB KDV motoru rehberi, motorun hangi durumları çözdüğünü ve uyarılarının nerede tetiklendiğini belgelemektedir.

Dönemi kilitlemek

İnceleme ve onay sonrasında, faturaları defter kayıtlarıyla mutabık kılın, defter KDV bakiyelerini beyanname veri setiyle eşleştirin, beyannameyi dışarı aktarın, beyanname ve ödeme referanslarını kaydedin ve ardından dönemi kilitleyin. Nordlet, API aracılığı da dahil olmak üzere kilitli bir aya yapılan kayıtları engeller. Kilitleme sonrasındaki düzeltmeler, orijinal belgeye ve etkilenen beyanname dönemine açık bağlantılarla sonraki bir döneme girilir.

Sık görülen hata modları ve bunlardan kaçınma yolları

Hata modu	Neden gerçekleşir	Azaltma yöntemi
Geçerli bir VIES sonucunu sıfır oran uygulamak için yeterli görmek	VIES muafiyet haklarını tesis etmez	Sonucun yanında müşteri, teslimat, nakliye ve fatura kanıtlarını saklayın
Geçersiz bir sonucu kayıt olmamanın kanıtı olarak değerlendirmek	Numara AB içi ticaret için etkinleştirilmemiş olabilir veya veritabanı gecikiyor olabilir	Geçersiz, işlenmemiş ve teknik hatayı ayırt edin; anlaşmazlıkları incelemeye yönlendirin
Ödeme adımını VIES ile senkronize hale getirmek	Eşzamanlılık sınırları, zaman aşımları, kesintiler	Asenkron doğrulama, kısa ömürlü önbellekleme, artan bekleme süreleri, geçici durumlar
Sonuçları sonsuza kadar önbellekte saklamak	Kayıt ve etkinleştirme durumu değişir	Zaman damgalarını ve son kullanma tarihlerini saklayın; eski olduğunda faturalandırmadan önce yeniden kontrol edin
Ürünleri doğrudan KDV yüzdelerine eşlemek	Oranlar ve muafiyetler ülkeye ve tarihe bağlıdır	Üründen kategoriye, kategoriye ülkeden özel koda ve yürürlükteki orana giden yapı
OSS'yi e-tablolardan yeniden oluşturmak	Toplamlar düzeltmeleri, sevkiyat ülkelerini, kanıtları atlar	Her girişte boyutların yer aldığı değiştirilemez defterden türetin
Yerel iş yeri hizmetlerini OSS'ye dahil etmek	Belirli hizmetler yerel beyannameye aittir	İş yerlerini ayrı modelleyin, toplama işleminden önce şemaya göre yönlendirin
Sıfır beyannameleri atlamak	OSS her dönem beyanname gerektirir	Bir kontrol listesi oluşturun ve sıfır değerli beyannameleri otomatik olarak oluşturun
Düzeltme için kapalı faturaları düzenlemek	Beyanname-düzeltme bağlantısını yok eder	Sonraki bir dönemde alacak dekontları ve ters kayıtlar kullanın

Önce ne yapardık

Bu entegrasyona yarın başlayacak olsaydık, tek bir raporlama uç noktasına dokunmadan önce vergi kategorisi katmanını ve KDV karar kaydını inşa ederdik. Taksonomiyi kararlı hale getirin, ürünleri kategorilere eşleyin ve karar kaydının ham ülke sinyallerini ve bir tedarik yerinin seçilme nedenini yakalamasını sağlayın. VIES, kayıt oluşturma, OSS gruplandırma, çıktı alma gibi diğer her şey bu modelin doğru olmasına bağlıdır.

Ardından VIES'i dört durumu ayrılmış asenkron bir kanıt adımı olarak kurgular ve üretime yakınlaştırmadan önce çirkin durumlar (zaman aşımı, işlenmemiş sonuçlar, uyumsuz önekler) için senaryolar içeren bir sandbox şirketinde çalıştırırdık. Yukarıdaki hata modları, veri modeli ilk kayıttan itibaren kanıt ve raporlama boyutlarını taşıyorsa neredeyse tamamen önlenebilirdir.

FAQ

Geçerli bir VIES yanıtı, AB içi B2B satışına sıfır oran uygulayabileceğim anlamına mı gelir?

Hayır. VIES, bir KDV numarasının kayıtlı olduğunu ve desteklendiği durumlarda AB içi ticaret için etkinleştirildiğini doğrular. Topluluk içi bir teslimatı muaf tutma hakkı ek kanıtlara bağlıdır: müşterinin gerçek alıcı olması, nakliye veya sevk kanıtı, doğru tedarik yeri ve gerekli fatura ibaresi. VIES sonucunu karar olarak değil, bir girdi olarak saklayın.

VIES doğrulaması ödeme adımını (checkout) bloke etmeli mi?

Etmemelidir. VIES zaman aşımına uğrayabilir veya eşzamanlılık sınırlarına takılabilir ve bir kesinti geçersiz bir numara ile aynı şey değildir. Satışı başarısız kılmak yerine asenkron olarak doğrulayın, başarılı sonuçları belgelenmiş bir süre için önbelleğe alın, geçici hataları yeniden deneyin ve belirsiz durumları geçici bir durumla inceleme için bekletin.

Bulut muhasebe API'si KDV beyannamelerimi otomatik olarak verebilir mi?

Defterden hesaplanan, düzeltmelerin dahil olduğu ve şemaya ile Üye Devlete göre gruplandırılmış beyannameye hazır veriler üretebilir. Her ulusal beyanname ağ geçidi üzerinden gönderim yapıp yapamayacağı ürüne ve ülkeye bağlıdır. Nordlet OSS ve IOSS beyannamelerini hesaplar, Litvanya, Almanya ve Polonya için yerel beyanname paketleri gönderir ve Litvanya için VMI uyumlu i.SAF defterleri üretir, ancak sizin adınıza vergi dairesine hiçbir şey sunmaz. Tek bir çağrının her yerde beyanname verdiğini varsaymak yerine muhasebeyi, beyanname üretimini, çıktıyı, ağ geçidi gönderimini ve ödemeyi ayrı durumlar olarak ele alın.

Dönem kilitlendikten sonra yapılan düzeltmeleri nasıl ele almalıyım?

Orijinal belgeye ve etkilenen beyanname dönemine açık bağlantılarla sonraki bir dönemde bunları kaydedin. Nordlet, API aracılığı da dahil olmak üzere kilitli bir aya yeni kayıt yapılmasını engeller, bu nedenle düzeltmeler düzenlemeler yerine alacak dekontları veya ters kayıtlar aracılığıyla akar. Bu, orijinal beyanname ile düzeltme arasındaki soy kütüğünü korur.