Pazar Yeri Muhasebesi için Çift Kayıtlı Defter (Double-Entry Ledger) API'leri

Çoğu pazar yeri bir muhasebe sorunu olduğunu aynı şekilde fark eder: yeni işe alınan bir finans uzmanı gelir, ödemeler tablosunu açar ve bir alıcı ödeme yapmasından fonların platform hesabından çıkmasına kadar geçen sürede satıcıya olan borcu asıl kimin kaydettiğini sorar. Mühendislik ekibi bir transactions (işlemler) tablosunu işaret eder. Finans uzmanı ise bir olaylar tablosunun bir defter seti olmadığını belirtir. Olay verileri ile gerçek muhasebe arasındaki bu uçurumu kapatmak için çift kayıtlı defter (double-entry ledger) API'si geliştirilmiştir.

Bu, düzenleyici boyutları olan teknik bir sorundur. Pazar yerleri başkalarının paralarını tutar, yargı bölgeleri genelinde KDV hesaplar ve satıcılar adına fatura keser. Bunu ev yapımı bir işlemler tablosuyla yapmak; bir denetçi, vergi dairesi veya ciddi bir alıcı kanıt isteyene kadar işe yarar.

Çift kayıtlı defter API'si tam olarak nedir?

Çift kayıtlı defter API'si, HTTP üzerinden sunulan programlanabilir bir muhasebe motorudur. Platformunuzun kaydettiği her finansal olay, dengeli bir yevmiye maddesi olarak yazılır: hesap planındaki adlandırılmış hesaplara gönderilen, toplamda birbirine eşit en az bir borç (debit) ve bir alacak (credit). API, bu dengeyi yazma anında zorlar ve girdileri daha sonra sessizce düzenlenemeyecek şekilde depolar.

"Çift kayıtlı" kısmı, her işlemin en az iki hesabı etkilediğini belirten dört yüz yıllık muhasebe kuralıdır. "API" kısmı, çağrıyı yapanın bir insan muhasebeci değil, ürününüz olduğu anlamına gelir. "Değiştirilemez (immutable)" kısmı ise düzeltmelerin geçmişi düzenleyerek değil, ters kayıtlar (reversing entry) yoluyla yapıldığı anlamına gelir. Bu üç özelliğin birleşimi, ortaya çıkan defterlerin yalnızca derli toplu olmasını değil, aynı zamanda denetime hazır (audit-ready) olmasını sağlar.

Faydalı bir çalışma tanımı:

Çift kayıtlı defter API'si uygulamanızdan finansal olayları kabul eder, her birini tanımlanmış bir hesap planına karşı dengeli bir yevmiye maddesine dönüştürür, bu girdileri değiştirilemez şekilde depolar ve ortaya çıkan defteri, mizanı (trial balance) ve finansal raporları öngörülebilir uç noktalar (endpoint) aracılığıyla sunar.

Nordlet tam olarak bu fikir etrafında inşa edilmiştir: API olarak gerçek defterler; defter, KDV mantığı, faturalandırma ve mutabakat, ürününüzün halihazırda iletişim kurduğu aynı uç nokta seti üzerinden erişilebilir durumdadır.

Pazar yerlerinin neden özellikle buna ihtiyacı var?

Tek satıcılı bir SaaS (hizmet olarak yazılım) genellikle günde bir kez genel bir muhasebe aracıyla senkronizasyon yaparak idare edebilir. Pazar yerleri ise üç nedenden dolayı bunu yapamaz.

Birincisi, paranın tam ortasında yer alırlar. Bir alıcı platforma ödeme yapar, platform fonları tutar ve ardından satıcılara komisyonlar düşülmüş olarak ödeme yapar. Bu hareketlerin her biri, farklı hesapları etkileyen ayrı bir muhasebe olayıdır: nakit, satıcı borçları, platform geliri, ödenecek KDV, iade karşılıkları. Bir status sütununa sahip payments (ödemeler) tablosu bunu yakalayamaz.

İkincisi, vergi yetki alanları genelinde faaliyet gösterirler. Litvanya, Almanya ve Polonya'da satıcıları ve blok genelinde alıcıları olan bir AB pazar yeri, her işlem için doğru KDV uygulamasını yapmak, VIES üzerinden satıcı KDV numaralarını doğrulamak ve her yerel otoriteyi tatmin edecek beyannameler üretmek zorundadır. Bunu uygulama kodunda doğru yapmak ve ardından ayrı bir muhasebe sistemiyle mutabakatını sağlamak, çoğu pazar yerinin sessizce tökezlediği noktadır.

Üçüncüsü, hacim manuel muhasebe için uygun değildir. Ayda on bin sipariş veren bir platform, on binlerce yevmiye maddesi üretiyor demektir. Bunun uçtan uca otomatikleştirmesi gerekir, aksi takdirde finans ekibi büyümenin önünde bir tıkanıklık yaratır.

Adım adım API'nin çalışması

İşleyiş mekanizması kulağa geldiğinden daha az karmaşıktır. Bir pazar yeri siparişi için tipik akış şöyledir:

1. Platformunuz bir finansal olay üretir. Bir alıcı ödeme işlemini tamamlar. Arka uç sisteminiz (backend) defter API'sini şu bilgilerle çağırır: sipariş ID'si, alıcı, satıcı, brüt tutar, KDV oranı, platform komisyonu, para birimi ve bir idempotency (tekrarsızlık) anahtarı.

2. Defter bir yevmiye maddesi oluşturur. API bu olayı borç ve alacaklara dönüştürür. Doğrudan bir pazar yeri satışı için bu; yoldaki nakit hesabına borç kaydetmek, net tutar için satıcı borçları hesabına alacak kaydetmek, komisyon için platform geliri hesabına alacak kaydetmek ve vergi kısmı için ödenecek KDV hesabına alacak kaydetmek anlamına gelebilir. Hepsi dengelidir. Hepsi atomik olarak işlenmiştir.

3. Girdi, değiştirilemez şekilde yazılır. Gönderildikten sonra girdinin bir tanımlayıcısı ve bir zaman damgası bulunur, düzenlenemez. Bir şeyler yanlışsa, ters bir kayıt ve ardından düzeltilmiş bir kayıt eklersiniz. Denetim izi (audit trail) zaten bu noktaya hizmet eder.

4. Akıştaki sonraki raporlar gerçek zamanlı olarak güncellenir. Mizan, satıcı borç bakiyeleri, KDV özetleri ve gelir tablosu (P&L) yeni girdiyi hemen yansıtır. Gece çalışan bir iş (nightly job), dışa aktarma (export) veya rakamların "uzlaştığı" bir mutabakat penceresi yoktur.

5. Webhook'lar sisteminizi bilgilendirir. sale_invoice.paid veya bank_transaction.matched gibi olaylar uç noktalarınızı tetikler, böylece ürününüz yoklama (polling) yapmadan tepki verebilir. İdempotency anahtarlarıyla birleştirildiğinde bu, yeniden denemelerin güvenli olduğu ve ağ kesintilerinde mükerrer kayıtların sızmayacağı anlamına gelir.

Önemli tasarım noktası şudur: Defter, finansal olarak ne gerçekleştiğinin hakikat kaynağıdır (source of truth). Uygulama veritabanınız ise ürün durumunun hakikat kaynağıdır. İki sistem birbiriyle uyum sağlar çünkü defter, uygulama olaylarından yola çıkılarak yazılır, tersi şekilde değil.

Hesap planı (chart of accounts), tasarım çalışmasının yapıldığı yerdir

Bir pazar yeri için defter kurulumundaki entelektüel çabanın büyük kısmı hesap planında gerçekleşir. Bu; banka başına nakit hesapları, satıcı borç hesapları (genellikle satıcı başına bir tane veya alt defterleri olan toplu bir hesap), kategoriye göre platform geliri, ülke başına ödenecek KDV, iade karşılıkları, ters ibraz (chargeback) karşılıkları vb. borç ve alacakların kaydedildiği adlandırılmış havuzların listesidir.

Pazar yerlerinde tekrarlanan birkaç desen:

• Satıcı fonları bir borçtur (liability), gelir değildir. Satıcılar adına tuttuğunuz para bir borçtur (payable). Bunu gelir olarak ele almak ve ödemeyi daha sonra "giderleştirmek", durum tespit (due diligence) sürecinde ortaya çıkan klasik hatadır.
• KDV, ülke başına ayrı bir borçtur. AB yetki alanlarında faaliyet gösteriyorsanız, beyannamelerin sorunsuz bir şekilde eşleşmesi için ülke başına ayrı ödenecek KDV hesapları istersiniz.
• Komisyonlar ödendikleri anda değil, kazanıldıkları anda modellenmelidir. Tahakkuk esasına dayalı muhasebe (accrual accounting) burada isteğe bağlı değildir.
• İadeler, ters ibrazlar ve anlaşmazlıklar kendi hesaplarına ihtiyaç duyar, böylece gelir tablosu pozitif ve negatif satışların karmaşasını değil gerçekleri yansıtır.

İyi bir defter API'si, ödeme kodunuzun içinde muhasebe mantığını yeniden icat etmek yerine, bu yapıyı bir kez tanımlamanıza ve ardından güvenle veri göndermenize olanak tanır.

Değiştirilemezlik (immutability), dönem kilitleme ve denetçilerin neden önem verdiği

Değiştirilemezlik kulağa bir veritabanı detayı gibi gelebilir. Aslında bu, bir denetçinin onaylayacağı defterler ile onaylamayacağı defterler arasındaki farktır.

Bir pazar yeri geçen çeyreğin girdilerini sessizce düzenleyebilirse, o zaman muhasebe anlamında geçen çeyreğin rakamları bilinemez demektir. Değiştirilemez bir defter, geçmişin geçmiş olduğu kuralını uygular. Düzeltmeler düzeltme olarak görünür. Dönem kilitleme bunu daha da ileri götürür: bir ay kapandıktan sonra, açık bir yeniden açma eylemi (ki bu da kendi başına kaydedilir) yapılmadığı sürece o döneme yeni girdi veya düzenleme yapılamaz.

Sonradan finansman sağlayacak, satılacak veya vergi denetimiyle karşı karşıya kalacak platformlar için bu "güzel olsa iyi olur" türünden bir özellik değildir. Defterleri savunulabilir kılan şey budur. Nordlet'in defteri tam olarak bu etrafında tasarlanmıştır; değiştirilemez çift kayıtlı yapı ve dönem kilitleme sonradan eklenmiş değil, doğrudan içine kurulmuştur.

AB KDV'si: Mühendislik zamanını tüketen kısım

KDV, çoğu pazar yeri muhasebe projesinin bütçe ve zaman sınırlarını aştığı yerdir. Kurallar basitçe "bir yüzde uygulamak" ibaret değildir. Alıcının nerede olduğuna, satıcının nerede olduğuna, neyin satıldığına, satıcının KDV mükellefi olup olmadığına, pazar yerinin 2021 e-ticaret kuralları kapsamında kabul edilen tedarikçi (deemed supplier) olup olmadığına ve yerelde hangi raporlama rejiminin geçerli olduğuna bağlıdır.

AB için ciddi bir defter API'si en az şunları ele almalıdır:

• İdeal olarak sonuçları önbelleğe alınmış ve işlem üzerine damgalanmış şekilde, satıcı ve alıcı KDV numaraları için VIES doğrulaması
• İndirimli oranlar ve muafiyetler dahil ülke bazında KDV oranı mantığı
• Litvanya beyannameleri için i.SAF kayıt üretimi ve diğer üye devletlerin talep ettiği durumlarda eşdeğer yapılandırılmış çıktılar
• Zorunlu elektronik faturaya geçen yargı bölgeleri için Peppol BIS 3.0 e-fatura
• Sınır ötesi B2C satışları için OSS/IOSS yönetimi

Bunu uygulama kodunda, ülke bazında yapmak, kurallar sürekli değiştiği için asla bitmeyen tam bir mühendislik ekibi işidir. Bunu defter katmanına itmek pragmatik bir yaklaşımdır.

Mutabakatın zaman tasarrufu sağladığı nokta

Defter hakikat kaynağı olduğunda, banka mutabakatı aylık bir kabus olmaktan çıkar. Banka ekstresi içeri girer, defter ne olması gerektiğini zaten bilir ve eşleştirme büyük ölçüde otomatiktir.

Bunun gerçekçi versiyonu "sıfır manuel iş" değildir. "İstisnaların kendi kendine yüzeye çıkmasıdır." Sorunsuz bir şekilde eşleşen işlemlerin yüzde doksanı için tek tıkla mutabakat akışı ve insan kararı gerektiren yüzde onluk kısım için bir kuyruk, iyi tasarlanmış bir mutabakat API'sinin sunduğu şeydir. Akıllı ödeme eşleştirme; kısmi ödemeleri, fazla ödemeleri ve her durum için bir insanın kurallar yazmasına gerek kalmadan birden fazla faturayı kapsayan ödemeleri ele alır.

Tedarikçi ve satıcı ödemeleri için SEPA dışa aktarımı (pain.001 formatı) giden tarafındaki döngüyü kapatır. Ürününüzde ödemeleri onaylarsınız, defter SEPA dosyasını üretir, bankanız bunu işler ve ortaya çıkan hareket otomatik olarak mutabık kılınır.

Oluşturmak mı, satın almak mı, gömmek (embed) mi?

Pazar yeri ekipleri genellikle üç yolu değerlendirir. Önemli olan eksenlerde nasıl karşılaştırıldıklarına bakalım:

Yaklaşım	Üretime geçiş süresi	Denetime hazır olma	AB KDV yönetimi	Ürününüzün içine uyum sağlama
Kendi defterinizi oluşturmak	12 ila 24+ ay	Tamamen ekibinize bağlı	Ülke bazında siz inşa edersiniz	Evet
Xero / QuickBooks ile senkronize etmek	Haftalar	Muhasebe tarafı için iyi, pazar yeri akışları için zayıf	Kısmi, eklentiler gerektirir	Hayır, ayrı bir araçta yaşar
Bir defter API'si gömmek (örn. Nordlet)	Haftalar	Değiştirilemez defter ve dönem kilitleme ile yerleşik	VIES ve i.SAF dahil, AB için yerleşik	Evet, API ve SDK'lar aracılığıyla

Muhasebe sizin ürününüzse kendiniz inşa etmek savunulabilirdir. Diğer herkes için matematik nadiren tutar. Geleneksel bir muhasebe aracına senkronize etmek tekil tüzel kişiliğe sahip işletmeler için işe yarar ancak pazar yeri akışları altında zorlanır: bölünmüş ödemeler, satıcı alt defterleri, ülke başına KDV ve platformun kabul edilen tedarikçi olduğu senaryolar, tek bir şirketin defterleri için tasarlanmış araçlarla temiz bir şekilde eşleşmez.

API odaklı bir defteri entegre etmek, modern platformların çoğunun üzerinde uzlaştığı yoldur. Defterler ürününüzün deneyimi içinde yaşar, satıcılar kendi finansal durumlarını sizin arayüzünüzde görür ve uyumluluk yükü altyapı katmanında ele alınır.

Bir defter API'sini değerlendirirken nelere dikkat edilmeli?

Satıcı görüşmeleri (vendor call) sırasında açık tutmaya değer kısa bir kontrol listesi:

• Düzenlenebilir satırlar yerine, ters kayıt düzeltmeleri içeren değiştirilemez çift kayıtlı depolama
• Günlüğe kaydedilmiş yeniden açma eylemleri içeren dönem kilitleme
• Her yazma uç noktasında idempotency anahtarları
• Yalnızca yoklama API'si değil, ürününüzün tepki vermesi gereken olaylar için webhook'lar
• Ekibinizin fiilen kullandığı dillerde tür güvenli (typed) SDK'lar
• VIES, i.SAF veya eşdeğerleri ve OSS/IOSS dahil ülke bazında KDV mantığı
• Birden fazla tüzel kişilik işletiyorsanız veya planlıyorsanız çoklu şirket desteği
• Geliştiricileri, muhasebecileri ve izleyicileri ayıracak kadar ayrıntılı rol tabanlı erişim
• Büyük raporlar hazır olduğunda webhook bildirimleri ile birlikte XLSX, PDF ve JSON formatlarında rapor dışa aktarımları
• Basitleştirilmiş bir demo değil, üretim davranışını birebir yansıtan bir test ortamı (sandbox)

Bir satıcı teknik bir görüşmede ilk üçünü gösteremezse, geri kalanının bir önemi yoktur.

İlk olarak ne yapardım?

Bir pazar yeri bu çalışmaya sıfırdan başlıyorsa, en çok sancı önleyecek sıra şöyledir:

1. Herhangi bir kod yazmadan önce tahta üzerinde gerçek para akışlarını çizin. Kim kime borçlu, hangi anda, hangi para biriminde, hangi KDV uygulamasıyla.
2. Bu haritadan hesap planını taslak haline getirin. Satıcı borçları, platform geliri, ülke başına ödenecek KDV, karşılıklar. Üretime girmeden önce bir muhasebeciye inceletin.
3. Defter katmanını seçin. Oluşturun, senkronize edin veya entegre edin. Ekibinizin gerçekten hangisini sunabileceği ve koruyabileceği konusunda dürüst olun.
4. Uçtan uca tek bir akışı uygulayın: siparişten faturaya, ödemeden mutabakata. Dengelendiğini kanıtlayın. Ardından ölçeklendirin.
5. İlk ay sorunsuz bir şekilde kapanır kapanmaz dönem kilitlemeyi açın. Disiplin katlanarak artacaktır.

Bunu doğru yapan ekipler, defteri bir raporlama son düşüncesi olarak değil, temel altyapı olarak ele alır. Değişim budur ve bir denetçi, yatırımcı veya vergi yetkilisiyle yapılan finans sohbetini uzun değil kısa kılan şey de budur.

FAQ

Çift kayıtlı defter API'si bir muhasebe entegrasyonu ile aynı şey midir?

Hayır. Bir entegrasyon, verileri genellikle bir gecikmeyle ürününüzden harici bir muhasebe aracına senkronize eder. Defter API'sinin kendisi muhasebe sistemidir, doğrudan ve gerçek zamanlı olarak buraya yazılır. Bu ayrım önemlidir çünkü entegrasyonlar sınırlarda güvenilirliğini kaybeder: kısmi ödemeler, çoklu para birimi, pazar yeri bölünmeleri. Bir defter API'si bunları yerel olarak kaydeder.

Stripe veya Adyen'in raporlarını kullanamaz mıyız?

Ödeme işlemcisi raporları, işlemciden ne geçtiğini söyler. Bunlar çift kayıtlı defterler değildir. Henüz ödenmemiş satıcı borçlarınızı, ülkeler arası KDV yükümlülüklerinizi veya ödeme işlemcisi dışındaki giderlerinizi bilmezler. Bunlar deftere giren girdilerden sadece biridir, onun yerini alamazlar.

Pratik anlamda değiştirilemezlik (immutability) ne kadar değiştirilemezdir?

Girdiler düzenlenemez. Düzeltmeler, orijinaline atıfta bulunan yeni girdilerdir. Bu bir teknoloji kararı değil, tasarım kararır. Yetkin herhangi bir defter bunu zorunlu kılar. Önem önemsenmelidir çünkü "bankayla eşleşmesi için düzenledik" ifadesi, defterleri güvenilmez kılan kalıbın ta kendisidir.

AB dışındaki pazar yerleri ne olacak?

Çift kayıtlı defter mekanizmaları evrenseldir. Vergi mantığı ise değildir. AB KDV'sine göre ayarlanmış bir defter API'si AB ağırlıklı operasyonları iyi yönetecektir ve AB dışı işlemleri destekleyebilir, ancak birincil pazarınız ABD satış vergisi veya Latin Amerika e-fatura rejimleriyse, taahhütte bulunmadan önce belirli uyumluluk kapsamını doğrulayın.

Uygulama fiilen ne kadar sürer?

Temiz bir olay modeline sahip bir pazar yeri için, bir defter API'sini entegre etmek uçtan uca tek bir akışı çalıştırma noktasına gelene kadar tipik olarak birkaç haftalık bir mühendislik çalışması gerektirir. Geçmiş veriler dahil eski bir yapıdan tam geçiş daha uzun sürer. Değişken neredeyse her zaman API'nin kendisi değil, mevcut verilerin durumudur.