Değiştirilemez (Immutable) Çift Taraflı Defter-i Kebir API'sini Ne Tanımlar?

Bir pazaryeri defter-i kebirini (ledger) tanımlayan unsur, para hareketlerini saklayıp saklamadığı değildir; çoğu sistem bunu yapar. Defteri tanımlayan durumlar şunlardır: Bir ödeme sağlayıcısı aynı webhook bildirimini iki kez gönderdiğinde, satıcıya ödeme yapıldıktan sonra bir iade geldiğinde veya bir denetçi satıcı bakiyesinin mevcut rakama nasıl ulaştığını sorduğunda ne olduğudur. Bu anlar, elinizde değiştirilemez (immutable) çift taraflı bir defter-i kebir mi olduğunu yoksa havalı bir isim verilmiş değiştirilebilir bir alan mı bulunduğunu ortaya çıkarır.

Bir pazaryeri platformu için kısa cevap şudur: Değiştirilemez çift taraflı bir defter-i kebir API'si, finansal açıdan önemli her eventi dengelenmiş bir yevmiye işlemine (journal transaction) dönüştürür, bunu atomik olarak kaydeder, asla üzerine yazmaz ve bakiyeleri türetmenize, harici sistemlerle mutabakat yapmanıza ve geçmişi programatik olarak dışarı aktarmanıza olanak tanır. Geri kalan her şey bu çekirdeğe bağlı detaylardan ibarettir.

Yürüyen bakiye alanı değil, dengelenmiş yevmiye kayıtları

En net test, API'nin bir satıcının bakiyesini nasıl temsil ettiğidir. Bakiye, uygulamanızın doğrudan artırdığı bir sayıdan ibaretse, bu çift taraflı bir defter-i kebir değildir. Bakiye, kaydedilmiş yevmiye satırlarının türetilmiş bir görünümüyse, öyle olabilir.

Her işlemin eşit borç ve alacak kayıtları içermesi gerekir. Bir alıcı, pazaryerinin %15 komisyon aldığı bir sipariş için 100 € ödediğinde, defter-i kebir takas hesabına (clearing account) 100 € borç kaydederken, satıcı borçlarına (seller payable) 85 € alacak ve komisyon gelirine 15 € alacak kaydeder. İki taraf her zaman aynı rakama ulaşacak şekilde dengelenir. Bu yapısal kural, büyük bir hata sınıfını raporlara ulaşmadan önce yakalar.

Bir yevmiye işlemi asgari olarak şunları içermelidir:

• Benzersiz, değiştirilemez bir işlem kimliği (transaction ID)
• Her biri bir hesaba, tutara ve para birimine sahip borç ve alacak satırları
• Bir yürürlük tarihi (effective date) ve deftere kaydetme zaman damgası (posting timestamp)
• Bir işletme eventi türü (satış, iade, ödeme aktarımı, ters ibraz)
• Bir idempotency anahtarı
• Siparişe, ödemeye veya sağlayıcı eventine ait bir kaynak referansı
• Bir durum (beklemede, deftere işlendi, ters çevrildi)
• Bunu oluşturan servis veya kimlik bilgisi

Bu durumda bir satıcının kullanılabilir fonları, uygulama kodunda birinin güncellediği bir değer üzerinden değil, bu satırlara atılan bir sorgu üzerinden elde edilir. Bu durumun önemi şuradan kaynaklanır: Doğrudan mutasyona uğratılmış bir bakiye, her hareketin arkasındaki gerekçeyi kaybeder. Nordlet'in modeli, çift taraflı defter-i kebiri yetkili yazma yolu olarak ele alır: Her belge dengelenmiş yevmiye kayıtları oluşturur ve veritabanının kendisi dengelenmeyen kayıtları reddeder. Bu yaklaşım, muhasebeyi bir pazaryerine entegre eden herkes için doğru varsayılandır.

Telafi edici düzeltmelerle birlikte yalnızca ekleme (append-only) yapılan kayıt

"Değiştirilemez" kavramı, deftere işlenmiş bir yevmiyenin yerinde düzenlenememesi gerektiği anlamına gelir. Hatalar silinerek değil, ileriye dönük düzeltmelerle giderilir. Yanlış bir komisyon kaydı, orijinalini geçersiz kılan bir ters kayıt (reversal) ve ardından istenen sonucu kaydeden düzeltilmiş bir kayıt alır. Her iki kayıt da orijinaline bağlanır ve denetim geçmişi değişikliği kimin, ne zaman başlattığını gösterir.

API, deftere işlenmiş muhasebe kayıtlarına karşı düz UPDATE ve DELETE işlemlerini reddetmelidir. Tutar, hesap ve zaman damgaları dokunulmaz kalmak şartıyla, bir destek talebi referansı gibi finansal olmayan meta veriler eklemenize izin verebilir.

İnsanların birbirine karıştığı üç şeyi ayırmak faydalı olacaktır:

• Operasyonel değiştirilemezlik: Uygulama kullanıcıları deftere işlenmiş satırları değiştiremez veya silemez.
• Denetim değiştirilemezliği: Sistem, geçmişin değiştirilmediğini kanıtlayabilir.
• Yasal saklama: Kayıtlar, yürürlükteki yasaların gerektirdiği süre boyunca saklanır.

Katı izinlere, yedeklemelere ve disiplinli ters kayıt iş akışlarına sahip, yalnızca ekleme yapılabilen (append-only) ilişkisel bir veritabanı, gerçekten değiştirilemez bir defter-i kebir sunar. Blockchain burada bir zorunluluk değildir ve AB muhasebe verileri için genellikle eklediği kurcalamaya karşı koruma avantajından daha fazla gizlilik ve düzeltme sorunu ortaya çıkarır.

Atomiklik ve idempotency

Bir pazaryeri eventinin atomik olarak deftere işlenmesi gerekir. Ya yevmiye satırlarının tümü onaylanır ya da hiçbiri onaylanmaz. 100 €'luk tahsilatı kaydettikten sonra 15 €'luk komisyonu kaydetmemek, birinin daha sonra çözmesi gereken dengesiz ve yanıltıcı bir sonuç doğurur. Nordlet bunu uygulama katmanının altında zorunlu kılar: Ertelenmiş bir veritabanı tetikleyicisi (trigger), onay anında her kaydın dengeye sahip olup olmadığını kontrol eder, böylece dengesiz bir işlemin onaylanması imkansız hale gelir.

Idempotency, entegrasyonların çoğunun sessizce bozulduğu noktadır. Ödeme sistemleri ağ hatalarında yeniden deneme (retry) yapar ve mutabakat dosyaları tekrar oynatılır. Kiracıya (tenant) veya hesaba göre kapsamlandırılmış bir idempotency anahtarı olmadığında, yeniden denenen tek bir istek mükerrer muhasebe kaydı oluşturur. Aynı anahtarla gelen mükerrer bir istek, ikinci bir işlem yerine orijinal işlemi döndürmelidir.

Anahtar; orijinal evente, event türüne, sağlayıcının event kimliğine, tüzel kişiliğe ve istek veri yükünün (payload) bir karmasına (hash) bağlanmalıdır. Aynı anahtar farklı bir tutar veya para birimiyle gelirse, API bunu bir çakışma olarak ele almalı ve yeni veri yükünü sessizce kabul etmek yerine reddetmelidir. Sessiz kabul, denetim izlerinin bozulmasına yol açar. Nordlet'in Idempotency-Key başlığı tam olarak bu şekilde çalışır: Aynı anahtar ve veri yüküyle yapılan bir yeniden deneme, saklanan yanıtı tekrar oynatır; farklı veri yüküne sahip aynı anahtar ise idempotency_key_reuse hatasıyla reddedilir. Bu, mutabakat üzerinde olağanüstü etkisi olan küçük bir özelliktir.

Çok taraflı bölmeli muhasebe (Split accounting)

Bir pazaryeri siparişi tek bir hareketten ibaret değildir. Tek bir satış; alıcı fonlarını, satıcı gelirlerini, pazaryeri komisyonunu, ödeme işleme ücretlerini, komisyon KDV'sini, kargoyu ve rezervleri ilgilendirebilir. Defter-i kebir, bunları tek bir net rakamda toplamak yerine ayrı tutan hesap yapılarına ihtiyaç duyar.

Üzerinde durulması gereken yaygın bir varsayım şudur: Bir ödeme sağlayıcısının "bölünmüş ödeme aktarımı" (split payout) özelliği, pazaryeri muhasebesiyle aynı şey değildir. Parayı alıcılar arasında bölmek nakit akışı sağlar. Bu, kazanılan komisyonun, tahsil edilen KDV'nin, borçlu olunan iadelerin veya tutulan rezervlerin eksiksiz ve değiştirilemez bir kaydını vermez. Kendi defter-i kebirinize sahip olmanız ve bunu sağlayıcıyla mutabık kmanız yine de gerekir.

Bir pazaryeri defter-i kebiri, birden fazla satıcı bakiyesini de birbirinden ayırt etmelidir:

Bakiye Durumu	Neyi Temsil Eder?
Beklemede (Pending)	Bir evente bağlı olan ancak henüz çekim için uygun olmayan fonlar
Kullanılabilir (Available)	Serbest bırakma, rezerv, iade ve anlaşmazlık kurallarını geçen fonlar
Tutulan / Rezerve Edilen (Held / reserved)	Ters ibrazlar, iadeler veya sahtecilik kontrolleri için alıkonulan tutarlar
Ödenen (Paid out)	Satıcıya aktarılan tutarlar
Negatif / Tahsil Edilebilir (Negative / recoverable)	İadeler veya ücretler kullanılabilir fonları aştığında satıcının borçlu olduğu tutarlar

Paranın beklemede durumundan kullanılabilir duruma geçmesi, yeniden etiketlenmiş bir alan olmaktan öte, bizzat dengelenmiş bir yevmiye işlemi olmalıdır.

Ters kayıtlar, iadeler ve negatif bakiyeler

Pazaryeri para akışları her iki yöne de, genellikle sıra dışı bir şekilde akar. En zorlu durumlar, ödeme aktarımından sonra yapılan iadeler ve haftalar sonra gelen ters ibrazlardır. Ciddi bir defter-i kebir, bir satıcının kullanılabilir bakiyesi bir iadeyi karşılayamadığında ne olacağını tanımlar: Negatif bir bakiye oluşturur, tutarı satıcı alacaklarına (receivables) taşır, bir rezervden çeker veya sonraki ödeme aktarımlarını kısıtlar.

Bu eventlerin her biri orijinal işlem referansını içermeli ve bunu korumalıdır. Defter-i kebir, bir iadenin muhasebe sonucunu kaydeder; pazaryerinin iade politikasını veya yasal sorumluluğunu belirlemez. Bu sınırın net tutulması, kafa karıştırıcı pek çok tasarım tartışmasını önler.

Para birimleri ve hassasiyet

Sınır ötesi pazaryerleri açık para birimi yönetimi gerektirir. Tutarlar ISO 4217 para birimi kodlarını ve tam bir temsiliyet (tamsayı alt birimleri veya sabit hassasiyetli ondalık dizeler) kullanmalıdır, asla kayan noktalı sayılar (floats) kullanılmamalıdır. Sessiz yuvarlama yapılmamalıdır. Dönüşüm gerçekleştiğinde defter-i kebir; orijinal tutarı, döviz kurunu (FX rate), kur kaynağını, zaman damgasını ve ortaya çıkan tutarı korumalı, yuvarlama farkları ise belirlenmiş bir hesaba işlenmelidir.

Dengelenmiş tek bir işlem, açık bir döviz kuru mekanizması olmaksızın farklı para birimlerini karıştırmamalıdır. Aksi takdirde, raporlarınız ay sonunda izlenmesi zor şekillerde gerçeklikle çelişecektir.

Harici sistemlerle mutabakat

Kendi içinde dengelenmiş bir defter-i kebir tek başına yetkili değildir. Dış dünya ile uyuşmalıdır: Ödeme sağlayıcı işlemleri, sağlayıcı ücretleri, mutabakat raporları, banka ekstreleri, ödeme aktarımı dosyaları ve ters ibraz raporları.

Olgun bir API; içe aktarılan harici eventleri ve eşleşti, kısmen eşleşti, eşleşmedi, mükerrer, tutar uyuşmazlığı ve inceleme gerekiyor gibi eşleşme durumlarını destekler. Mutabakat farkları, açık istisna kayıtları veya muhasebe girdileri oluşturmalıdır. Defter-i kebir geçmişini asla sessizce yeniden yazmamalıdır. Nordlet'in banka mutabakatı ve ödeme eşleştirmeye yaklaşımı bu ilkeye dayanır: İçe aktarılan ekstreler daha önce içe aktarılanları atlar; ödeme önerileri tutar, referans, karşı taraf ve IBAN'a göre puanlanır; tek tıkla eşleştirme rutin durumları ele alır ve istisnalar örtbas edilmek yerine yüzeye çıkarılır.

API'nin uyması gereken AB sınırları ve uyamayacağı noktalar

Pazarlama iddialarının gerçekliğin önüne geçme eğiliminde olduğu alan burasıdır. Bir defter-i kebir AB yükümlülüklerine yardımcı olur, ancak tek başına bunları karşılamaz.

KDV (VAT). Defter-i kebir; yetki alanı (jurisdiction), oran, vergi kategorisi ve oranın nasıl belirlendiği gibi vergiyle ilgili boyutları korumalıdır. Satıcının alıcıya yaptığı satış ile pazaryerinin komisyonunu birbirinden ayırt etmeli, ücretler üzerinden alınan KDV ile yalnızca aradan geçen (pass-through) tutarları ayrıştırmalıdır. Nordlet, ülke bazında KDV hesaplamalarını, VIES doğrulamasını ve i.SAF beyannamesi üretimini, AB pazaryerlerinin karşılaştığı OSS ve IOSS senaryoları ile birlikte yönetir. Defter-i kebiri bir vergi tavsiyesi olarak değil, bir kanıt ve vergi motoru olarak değerlendirin.

DAC7. Platform raporlama kuralları, satıcı kimliği, yetki alanı, işlem toplamları, ücretler, iadeler ve ödeme aktarımları arasında güvenilir bağlantılar gerektirir. Dengelenmiş bir defter-i kebir işlem kanıtını üretir; bir satıcının raporlanabilir olup olmadığını belirlemez ve KYC, sisteme alım (onboarding) ya da raporlama iş akışının yerini almaz. İşlem muhasebesini ve düzenleyici raporlamayı ayrı konular olarak tutun.

PSD2 ve fon saklama (fund custody). Para hareketlerini kaydetmek, lisanslı bir ödeme hizmeti olmak veya fonları güvence altına almakla aynı şey değildir. Defter-i kebir, fon akışını ve tarafları açık hale getirmelidir. Tek başına ödeme hizmetleri yetkilendirmesi sağlayamaz veya nakdin belirli bir hesapta tutulduğunu kanıtlayamaz. Bu durum, düzenleyici rolünüzün ve ödeme hizmeti sağlayıcınızın (PSP) bir meselesidir.

GDPR (KVKK muadili). Değiştirilemezlik, veri koruma ilkeleriyle gerçek bir gerilim yaratır. En güvenli mimari, parasal gerçekleri değiştirilemez çekirdekte tutar ve kişisel verileri bunun dışında bırakır. Yevmiye satırlarında kararlı (stable) takma ad (pseudonymous) içeren satıcı ve müşteri referansları kullanın. Değiştirilebilir kişisel detayları, kendi saklama ve silme iş akışına sahip, ayrı ve erişim kontrollü bir sistemde saklayın. "Değiştirilemez" kelimesi, her ödeme veri yükünü sonsuza dek saklama izni değildir.

Bir defter-i kebir API'sini değerlendirmek için kontrol listesi

Özellik etiketleri ucuzdur. Bunun yerine davranışı bir sandbox ortamında test edin. Şu senaryoları çalıştırın ve kanıtları kontrol edin:

• Satıcı ve pazaryeri arasında bölüştürülmüş 100 €'luk bir siparişi deftere işleyin ve açık hesapların yer aldığı dengelenmiş bir yevmiye olduğunu doğrulayın.
• Aynı isteği iki kez gönderin ve tek bir işlem gerçekleştiğini, mükerrer kayıt olmadığını doğrulayın.
• Deftere işlenmiş bir girdiyi düzenlemeyi deneyin ve bunun reddedildiğini veya finansal olmayan meta verilerle sınırlandırıldığını doğrulayın.
• Yanlış bir komisyonu düzeltin ve buna bağlı bir ters kayıt ile düzeltilmiş bir girdi oluştuğunu doğrulayın.
• Ödeme aktarımından sonra kısmi iade gerçekleştirin ve gerektiğinde satıcı alacağı veya negatif bakiye içeren izlenebilir bir iade olduğunu doğrulayın.
• Bir sağlayıcı webhook bildirimini tekrar oynatın ve mükerrer tespitini doğrulayın.
• Çok para birimli bir mutabakatı işleyin ve döviz kuru detayları ile dönüşüm muhasebesini doğrulayın.
• Dönem sonunda bir satıcı bakiyesini sorgulayın ve belgelenmiş bir kesim noktasıyla (cut-off) yeniden üretilebilir bir sonuç aldığınızı doğrulayın.
• Bir sağlayıcı mutabakatını içe aktarın ve geçmişi sağlam bırakan bir istisna durumuyla eşleşme gerçekleştiğini doğrulayın.
• Bir aylık aktiviteyi dışarı aktarın ve eksiksiz, sayfalandırılmış, yinelenebilir bir çıktı elde ettiğinizi doğrulayın.

En güçlü kanıt, dokümantasyon artı yeniden üretilebilir bir testtir. "Gerçek zamanlı", "denetime hazır" ve "değiştirilemez" gibi kelimeler; arkalarındaki veri modeli, hata semantiği ve saklama davranışı olmadan hiçbir şey ifade etmez.

İlk olarak neleri kontrol ederdik?

Yarın bir pazaryeri için bir defter-i kebir API'si değerlendirecek olsaydık, başka hiçbir şeye bakmadan önce iki şeyle başlardık. İlk olarak, bir satıcı bakiyesinin değiştirilebilir bir alandan değil, yevmiye satırlarından türetildiğini kanıtlardık; çünkü akıştaki her şey buna bağlıdır. İkinci olarak, aynı webhook bildirimini tekrar oynatır ve tam olarak tek bir muhasebe sonucu elde edildiğini doğrularardık. Bu iki test, temel tasarımın kalitesi hakkında herhangi bir özellik listesinden çok daha fazlasını söyler.

Bundan sonra, ekibinizin ne kadar hızlı ürün çıkaracağı açısından API odaklı hususlar önem kazanır: Tipli SDK'ler, sale_invoice.paid gibi eventler için webhook bildirimleri, çalışan bir sandbox ortamı ve kapanan ayları korumak için dönem kilitleme. Nordlet bu model etrafında inşa edilmiştir; API üzerinden sunulan özellik seti ile uygulama üzerinden sunulan özellik seti aynıdır. Bu da bir platformun, üçüncü taraf bir ödeme çözümünü harici olarak eklemek yerine denetime hazır defterleri kendi ürünü içinde çalıştırmasına olanak tanır. Böyle bir defter-i kebirin bir pazaryeri yığınına nasıl uyduğunun daha geniş bir resmi için, pazaryeri muhasebesi için çift taraflı defter-i kebir API'leri kılavuzumuza göz atın.

SSS

Çift taraflı kayıt (double-entry), muhasebemin doğru olduğunu garanti eder mi?

Hayır. Bir defter-i kebir; yanlış hesaplara kayıt yaparken, yanlış KDV uygulaması izlerken veya fonları yanlış satıcıya atfederken de mükemmel bir şekilde dengelenebilir. Denge, aritmetik hataları ve bir işlemin eksik taraflarını yakalayan yapısal bir kuraldır. İş mantığınızın eventi doğru şekilde eşleyip eşlemediği hakkında hiçbir şey söylemez. Bu nedenle gerçek senaryolara karşı sandbox testi yapmak, tek başına bakiye kontrolünden çok daha önemlidir.

Bir ödeme sağlayıcısının defter-i kebiri bir pazaryeri için yeterli midir?

Genellikle hayır. Bir PSP, fonları kendi sistemi içinde takip eder; bu da para hareketi ve ödeme aktarımı için yararlıdır. Pazaryerinizin komisyon geliri, satıcı yükümlülükleri, ücretler üzerinden KDV, iadeler, rezervler, anlaşmazlıklar ve yönetim raporlaması için yine de kendi kayıtlarına ihtiyacı vardır. İki sistemin mutabık kılınması gerekir ve sağlayıcının görünümünü kendi muhasebeniz olarak ele almak, denetim sırasında ortaya çıkan boşluklar bırakır.

Bir defter-i kebiri değiştirilemez (immutable) kılmak için blockchain'e ihtiyacım var mı?

Hayır. Katı yazma izinlerine, kontrollü düzeltme iş akışlarına, denetim günlüklerine ve güvenilir yedeklemelere sahip, yalnızca ekleme yapılabilen (append-only) ilişkisel bir veri tabanı, size operasyonel ve denetim değiştirilemezliği sağlar. Blockchain, dağıtık kurcalamaya karşı koruma ekler ancak AB muhasebesi ve GDPR gerekliliklerine aykırı olan gizlilik, performans ve düzeltme zorluklarını beraberinde getirir. Çoğu pazaryeri için bu, sahip olmadıkları bir sorunu çözer.

Değiştirilemez bir defter-i kebir, GDPR kapsamında verileri sonsuza kadar saklayabilir mi?

Muhasebe kayıtlarını yasal olarak zorunlu bir süre boyunca saklamakta sakınca yoktur. Defter-i kebir değiştirilemez olduğu için tam kişisel verileri veya ödeme veri yüklerini süresiz olarak saklamak ise yanlıştır. Parasal gerçekleri ve takma ad içeren referansları değiştirilemez çekirdekte tutun, kişisel detayları ise uygun saklama ve silme süreçleriyle ayrı bir sistemde barındırın. Değiştirilemezlik ilkesi, finansal event için geçerlidir, ona eklenen her veri parçası için değil.