Pazar Yerleri İçin Çift Yönlü Defter Defteri (Double-Entry Ledger) API'si Nedir?

Bir pazar yeri, orders (siparişler) tablosunda gayet sağlıklı görünebilir ancak parası konusunda yine de yanılıyor olabilir. Sipariş tablosunda "ödendi" yazıyordur. Satıcı panelinde bir bakiye görünmektedir. Ancak bu tablodaki hiçbir şey, platformun elinde tam olarak ne kadar nakit olduğunu, her bir satıcıya ne kadar borcu bulunduğunu, ödemenin ne kadarının komisyon geliri olduğunu veya artık ne kadar KDV (VAT) ödenmesi gerektiğini kanıtlamaz. Bir çift yönlü defter (double-entry ledger) API'si, bu finansal sonuçları her defasında dengeli bir işlemle doğru bir şekilde kaydetmek için vardır.

Açıkça söylemek gerekirse: Çift yönlü defter API'si, programlanabilir bir muhasebe sistemidir. Uygulamanız sisteme tahsil edilmiş bir ödeme veya onaylanmış bir hakediş ödemesi (payout) gibi finansal bir olay gönderir; defter de bu olayı, adlandırılmış hesaplar arasında eşit borç (debit) ve alacak (credit) içeren bir yevmiye kaydı (journal) olarak işler. Bu sistem para taşımaz; başka bir yerde hareket eden paranın gerçekliğini kayda geçirir.

Burada "çift yönlü defter" ne anlama geliyor?

Defter, en son bakiyeyi tutan bir tablo değil, hesaplardaki değişimlerin kaydıdır. Çalışan bir defterin birbiriyle bağlantılı üç temel fikri vardır:

• Hesap (Account): Ödeme sağlayıcı alacağı, satıcı borcu, komisyon geliri veya ödenecek KDV gibi adlandırılmış bir finansal pozisyon.
• İşlem / Yevmiye (Transaction / Journal): Birden fazla dengeli satır içeren tek bir atomik finansal olay.
• Kayıt / Madde (Entry / Posting): Bu işlemin içindeki tek bir borç veya alacak satırıdır.

Her tasarımı bir arada tutan değişmez kural basittir: Her işlem ve her para birimi için toplam borçlar, toplam alacaklara eşittir. Defter API'leri genellikle dengesiz bir yazma isteğini, depolama alanına ulaşmadan önce reddeder. Modern Treasury belgelerinde bir defter işleminin, eşit toplamlara sahip en az bir borç ve bir alacak içeren iki veya daha fazla hesabı kapsadığını belirtir ve kaydedilmiş bir işlemi değiştirilemez (immutable) olarak ele alır.

Çift yönlü olmak, tam olarak iki satırdan oluşacağı anlamına gelmez. Tek bir pazar yeri satışı genellikle bir borç ve birkaç alacak gerektirir. İnsanların en sık yanlış anladığı nokta budur.

Pazar yerlerinin neden sadece bir ödeme tablosuna değil, bir deftere ihtiyacı var?

Bir pazar yeri, aynı anda birkaç finansal ilişkiyi bir arada yürütür. Alıcı ödeme yapar. Sağlayıcı mutabakatı yapar. Platform fonları geçici olarak kontrol ediyor olabilir. Satıcı bir pay kazanır. Platform bir komisyon alır. Vergi ödenecek hale gelir. Bir miktar yedek akçe (reserve) kesilebilir. Daha sonra bir ödeme işlemi parayı dışarı çıkarır ve iadeler veya ters ibrazlar (chargeback) bunların bazılarını tersine çevirir.

Bir payments tablosu size bir siparişin ticari durumunu söyleyebilir. Ancak şu soruları güvenilir bir şekilde yanıtlayamaz:

• Ne kadar ödeme sağlayıcı alacağı veya nakit var?
• Her satıcıya ne kadar borçluyuz?
• Platformun payına ne kadar gelir düşüyor?
• Hangi ülkede ne kadar KDV ödenmesi gerekiyor?
• İadelere veya uyuşmazlıklara karşı ne kadar yedek tutuluyor?
• Bir hakediş ödemesi, doğru satıcı borcunu azalttı mı?
• Sağlayıcı mutabakatları, platformun beklentileriyle uyuşuyor mu?

Nordlet'in pazar yeri muhasebesi için çift yönlü defter API'leri kılavuzu, meseleyi net bir şekilde ortaya koyar: Uygulama tabloları ürün durumunu açıklarken, defter bu durumun finansal sonuçlarını kaydeder. Ayrıca, ödeme sağlayıcı raporlarının eksiksiz çift yönlü defterler olmadığını, mutabakat için birer girdi teşkil ettiğini de tekrar etmekte fayda var.

Örnek bir pazar yeri satışı

Bir alıcının 100 € ödediğini, satıcının 85 € hak kazandığını ve platform komisyonunun 15 € olduğunu varsayalım. Netlik olması için KDV ve sağlayıcı ücretlerini göz ardı edelim.

Hesap	Borç (Debit)	Alacak (Credit)	Gerekçe
Ödeme sağlayıcı alacağı	100 €		Sağlayıcı, tahsil edilen ödemeyi platforma borçludur
Satıcı borcu		85 €	Platform satıcıya borçludur
Komisyon geliri		15 €	Platform komisyonunu kazanmıştır
Toplam	100 €	100 €	Dengede

Buradaki önemli sınıflandırma, satıcıya borçlu olunan 85 € tutarının platform geliri değil, bir borç (yükümlülük) olmasıdır. UFRS (IFRS) kavramsal çerçevesine göre borç, ekonomik bir kaynağın devredilmesine yönelik mevcut bir yükümlülüktür. Bir pazar yeri, sırf alıcı ödemeyi kendisi üzerinden yaptı diye satıcının satış gelirinin tamamını kendi geliri olarak bildirmemelidir. Ajan, asil veya sorumlu satıcı (deemed supplier) konumunda olmanız muhasebe muamelesini değiştirir ancak defter mekanizması aynı kalır.

Satıcı hakediş almaya hak kazandığında yeni bir gelir kaydedilmez. Borcu kapatırsınız (tasfiye edersiniz):

Hesap	Borç (Debit)	Alacak (Credit)
Satıcı borcu	85 €
Banka veya hakediş takas hesabı		85 €
Toplam	85 €	85 €

Sağlayıcı ödemeyi aktarmadan önce 3 € kesinti yaparsa, nakit hareketi üç satırlık bir yevmiyeye dönüşür: Banka nakdine 97 €, işlem giderine 3 €, ödeme sağlayıcı alacağından çıkış olarak 100 €. Konumdaki her değişikliğin bir kaynağı ve bir hedefi vardır.

API adım adım nasıl çalışır?

1. Uygulamanız bir iş olayını algılar. Bir ödeme tahsil edilir, bir sipariş yerine getirilir, bir hakediş onaylanır, bir iade yapılır, bir ters ibraz açılır veya bir mutabakat gerçekleşir. Veritabanınız operasyonel durumu elinde tutmaya devam eder. Defter ise parasal etkiyi kaydeder.

2. Yapılandırılmış bir istek gönderirsiniz. Bu istek genellikle olay türünü, tutarı ve para birimini, sipariş veya ödeme kimliğini, alıcı ve satıcı tanımlayıcılarını, komisyonu, vergi verilerini, ilgili hesapları, yürürlük ve kayıt tarihlerini, bir idempotency key (tekilleştirme anahtarı) ile sağlayıcı ve ürün kayıtlarına bağlanan meta verileri içerir. Nordlet'in halka açık API örneği; satıcı kimliği, satış türü, tutar, para birimi, KDV ülkesi ve oranı ile birlikte kavramsal bir satış isteğini gösterir.

3. API doğrulama yapar. Borç ve alacakların dengede olup olmadığını, hesapların mevcut ve işlem yapılabilir durumda olup olmadığını, para biriminin desteklenip desteklenmediğini, tutarda hassas alt birim (minor-unit) yönetimi yapılıp yapılmadığını, idempotency key değerinin farklı bir sonuç için yeniden kullanılıp kullanılmadığını, dönemin açık olup olmadığını ve gerekli meta verilerin bulunup bulunmadığını kontrol eder. Başarısız bir kontrol, geride yarım bir yevmiye bırakmaz.

4. Atomik olarak kaydeder. Tüm işlem tek bir bütün olarak yazılır. Eşleşen alacak başarısız olurken borcun kaydedilmesi asla mümkün olmamalıdır. Bir pazar yeri için kısmi bir bölünme, ortada karşılık gelen bir nakit olmaksızın hayali bir satıcı bakiyesi oluşturabilir veya satıcı yükümlülüğü olmaksızın komisyon kaydedilmesine yol açabilir.

5. Bakiyeler ve raporlar defterden türetilir. Kayıttan sonra hesap bakiyelerini, satıcıların bekleyen ve kullanılabilir bakiyelerini, mizanı (trial balance), genel defter (general ledger) hareketlerini, KDV özetlerini ve geçmiş bir tarihteki durumu okuyabilirsiniz. Satıcı bakiyesi, üzerinde değişiklik yapılabilen bir alandan okunmamalı, kayıtlardan yeniden oluşturulabilmelidir.

6. Webhook'lar ürününüzü bilgilendirir. sale_invoice.paid (satış faturası ödendi), kaydedilmiş bir yevmiye, kullanılabilir bir hakediş veya bir mutabakat istisnası gibi olaylar size iletilir. Bunları idempotency (tekrar edilebilir) kurallarına uyarak işleyin. Bir webhook bir bildirimdir, finansal olayı ikinci kez uygulamak için bir izin değildir. API kuralları kapsamları, idempotency key değerlerini, hata biçimlerini ve webhook imzalama detaylarını kapsamlı bir şekilde ele alır.

Satıcı bakiyeleri tek bir sayıdan ibaret değildir

Çoğu pazar yeri, satıcı bakiyesini tek bir rakam olarak ele aldığı için sorun yaşar. Para şu durumlarda bulunmalıdır:

Durum	Anlamı
Beklemede (Pending)	Satıcı hak kazanmış olabilir ancak serbest bırakılma koşulları karşılanmamıştır
Kullanılabilir (Available)	Hakediş ödemesine uygundur
Ayrılmış / Yedekte (Reserved)	İade, geri dönüş veya uyuşmazlıklara karşı alıkonulmuştur
Ödenmiş (Paid out)	Yükümlülük bir transferle kapatılmıştır
Negatif	İadeler, ters ibrazlar veya ücretler mevcut fonları aşmaktadır

Sağlayıcı modelleri bunu yansıtır. Stripe'ın ayrı tahsilatlar ve transferler akışı, bir platformun kendi hesabından tahsilat yapmasına, ardından ücretler, iadeler ve ters ibrazlar platform bakiyesine yansıtılacak şekilde tutarları bağlı hesaplara aktarmasına olanak tanır. Adyen'in pazar yeri modeli, hakediş yapılana kadar fonları tutan kullanıcı bakiye hesaplarını, iade veya ters ibrazlardan kaynaklanan negatif bakiyeleri absorbe edebilen borçlu bakiye hesabından ayırır. Bunlar defteriniz için faydalı girdilerdir. Ancak eksiksiz muhasebe modeliniz bunlar değildir.

Hakedişler ve satıcı kazançları farklı zamanlarda gerçekleşir

Bir satıcı pazartesi günü kazanabilir ve takip eden pazartesi günü ödeme alabilir. Bu noktalar arasında bir sipariş yerine getirilir, bir yedek akçe tutulur, bir hakediş grubu oluşturulur, bir sağlayıcı ücretler düşüldükten sonra net ödemeyi gerçekleştirir ve banka mevduatı hesaba geçer. Bir defter, siparişi nihai bir "ödendi" durumuyla üzerine yazmak yerine her aşamayı korumak zorundadır. Sipariş etkinliği, satıcı hak edişi, mutabakat, hakediş başlatımı ve banka tahsilatı arasındaki zamanlama farklarını açıklamanızı sağlayan şey budur.

İadeler ve ters ibrazlar: Yeniden yazmayın, tersine çevirin

İadeler ve ters ibrazlar, orijinal ödemeye bağlı yeni olaylardır. Değiştirilemez (immutable) bir defterde düzeltmeyi, orijinal kaydın denetim için görünür kalmasını sağlayacak şekilde bir ters kayıt (reversing entry) ve ardından düzeltilmiş bir kayıt ile yaparsınız. Modern Treasury, kaydedilen işlemleri değiştirilemez olarak ele alır ve yeniden denemelerde mükerrer nesneleri önlemek için idempotency key kullanımını destekler.

Bir iade tipik olarak nakiti veya alıcı alacağını azaltır, satıcı borcunu tersine çevirir, politikaya bağlı olarak komisyonun bir kısmını tersine çevirebilir, vergiyi ayarlar ve bir iade yedek akçesini tüketebilir. Bir ters ibraz nakiti veya sağlayıcı alacağını azaltır, satıcı veya platform tarafından borçlanılan bir tutarı yeniden açabilir, bir uyuşmazlık gideri ve sağlayıcı ücreti kaydeder ve fonları bir yedek hesap üzerinden hareket ettirir.

Mutabakat (Reconciliation): Defteri gerçek parayla buluşturma

Bir defter kendi içinde dengede olabilir ancak dış dünya konusunda hâlâ yanlış veriler içerebilir. Mutabakat; dahili kayıtları, sağlayıcı mutabakat raporları, banka ekstreleri, hakediş dosyaları, iade ve uyuşmazlık kayıtları gibi harici kanıtlarla karşılaştırır.

Çalışan bir döngü şu adımları izler:

1. Mutabakat veya banka toplu dosyasını içe aktarın.
2. Her satırı bir sipariş, ödeme, iade, ücret, hakediş veya uyuşmazlık ile eşleştirin.
3. Beklenen brüt tutarı, kesintileri, yedekleri ve net tutarı karşılaştırın.
4. Onaylanan hareketleri deftere kaydedin.
5. Eşleşmeyen kalemleri adlandırılmış bir geçici hesaba (suspense account) gönderin.
6. İstisnaları inceleyin.
7. Dönemi kilitleyin.

Nordlet'in mutabakat materyalleri tam olarak bunu anlatır; mutabakat dosyalarını içe aktarır, tahsilat ve iade satırlarını eşleştirir ve eşleşmeyen tahsilatları rastgele bir fatura uydurmak yerine geçici hesaba yönlendirir. İki kontrol önemlidir ve hiçbiri diğerinin yerini alamaz: Çift yönlü doğrulama, her yevmiyenin dengede olup olmadığını sorarken; mutabakat, sağlayıcı, banka ve iş olayıyla uyumlu olup olmadığını sorgular.

Doğru yapıp yapmadığınızı belirleyen tasarım detayları

İdempotency (Tekilleştirme). Anahtarı payment_captured:pi_123 gibi kararlı bir olaya bağlayın. Yeniden deneme, ikinci bir yevmiye yerine orijinal sonucu döndürür.

Atomiklik (Atomicity). Bir olayın tüm satırları birlikte kaydedilir ya da hiçbiri kaydedilmez.

Değiştirilemezlik ve ters kayıtlar (Immutability & Reversals). Kaydedilmiş geçmiş, olağan güncellemeler yoluyla düzenlenemez. Düzeltmeler; orijinal tutarı, tarihi, sınıflandırmayı, nedeni ve yapanı koruyan bağlantılı kayıtlar oluşturur.

Hassas para birimi. İkili kayan nokta (binary floating point) kullanılmaz. Bölmeler için tamsayı alt birimleri veya kesin ondalık sayılar, açık para birimi ve belirleyici bir yuvarlama kuralı kullanın. 100 €'yu satıcılar ve ücretler arasında kural olmadan bölerseniz, başıboş kalan bir kuruş bakiyenizi bozar.

Yürürlük ve kayıt tarihleri. Alıcının ödeme yaptığı tarih, satıcının kazandığı tarih, bankanın mutabakat yaptığı tarih ve kaydın işlendiği tarih farklı tarihlerdir. Bunları karıştırmak, dönem raporlamasını ve vergi zamanlamasını güvenilmez hale getirir.

Çoklu para birimi. Borç ve alacaklar bir para birimi içinde dengelenmelidir. Dönüşüm işlemi; ücret, yuvarlama ve olası kur kazanç veya kayıpları için hesaplar içeren açık bir kur olayı gerektirir. Bir currency alanı kabul etmek, bir defteri döviz motoru yapmaz.

Bir defter API'sinin sizin için yapamayacakları

Hesap planınıza o karar vermez. Asil mi yoksa aracı mı olduğunuzu, komisyonun ne zaman kazanıldığını, ödeme sağlayıcı ücretlerini hangi tarafın üstleneceğini, iadelerin komisyonu nasıl etkilediğini ve KDV'nin nasıl hesaplanıp bildirileceğini yine siz belirlemek zorundasınız. Nordlet'in kendi rehberliği; önce para akışlarını haritalandırmayı, hesap planını taslak haline getirmeyi, bir muhasebeciye inceletmeden geçirmeyi, ardından ölçeklendirmeden önce siparişten hakedişe ve mutabakata kadar tam bir akışı uygulamayı önerir.

Vergi sorularını çözmez. KDV; alıcı ve satıcı konumuna, ürün türüne, kayıt durumuna ve sorumlu satıcı kurallarına bağlıdır; AB KDV kılavuzu, sistemin neler türettiğini ve bir insan tarafından incelenmek üzere neleri işaretlediğini ortaya koyar. Nordlet'in KDV kapsamı AB ve AEA odaklıdır, bu nedenle ABD satış vergisine veya Latin Amerika e-furalandırmasına uzanmaz. Ayrıca iade penceresinin kapanıp kapanmadığı, bir hakedişin engellenip engellenmemesi veya bir ödemenin sahte olup olmadığı gibi operasyonel belirsizlikleri de çözmez. Bunlar sizin kararlarınızdır. Defter bunların finansal sonucunu kaydeder.

Nordlet'in konumu

Nordlet, değiştirilemez bir çift yönlü defter, hakedişler, AB KDV yönetimi, REST uç noktaları, tiplendirilmiş SDK'lar ve tek bir yüzeyden erişilebilen webhook'lar içeren, platformlar ve pazar yerleri için tasarlanmış bir muhasebe API'sidir. Onu ayıran temel tercih, üçüncü taraf bir ödeme ekranı yerine doğrudan kendi ürününüze gömülü bir muhasebe sunmasıdır. Bu yazının yazıldığı sırada ürün, tasarım ortaklarına yönelik bir sandbox ortamı ile erken erişim aşamasındadır; bu nedenle ürünü kategorisinin güçlü bir örneği olarak değerlendirin ve taahhütte bulunmadan önce kendi kullanım senaryonuz için üretim olgunluğunu, çalışır süresini (uptime) ve yasal kapsamını değerlendirin.

Pazar yeri ve platform geliştiricileri için yararlı zihniyet modeli, para hareketi ile finansal gerçeklik arasındaki ayrımdır. Sağlayıcınız parayı hareket ettirir. Çift yönlü defter API'si ise kime ne borçlu olduğunuzu, ne kazandığınızı, hangi vergi ve yedekleri taşıdığınızı ve dış dünyanın defterlerinizle mutabık olup olmadığını kaydeder.

FAQ

Çift yönlü defter API'si bir ödeme sağlayıcı ile aynı şey midir?

Hayır. Bir sağlayıcı fonları yetkilendirir, tahsil eder, mutabakatını yapar ve bazen öder. Bir defter API'si ise bu olayların muhasebe sonuçlarını kaydeder. Çoğu pazar yeri ikisini de kullanır; para hareketi için Stripe veya Adyen gibi bir sağlayıcı, defterler için ise bir defter sistemi kullanır.

Sağlayıcımın panelini doğrudan genel defter (general ledger) olarak kullanabilir miyim?

Deneyebilirsiniz, ancak bu durum sonunda bir denetimden (audit) geçemeyecektir. Sağlayıcı raporlaması tahsilatları, ücretleri, transferleri ve mutabakatları gösterir; ancak genellikle tüm satıcı yükümlülüklerinizi, vergi borçlarınızı, sağlayıcı dışı giderlerinizi veya muhasebe düzeltmelerinizi yansıtmaz. Bunu bir mutabakat girdisi olarak değerlendirin.

Dengeli bir defter, defterlerimin doğru olduğu anlamına mı gelir?

Yalnızca kayıtlarınızın borç-alacak kuralını karşıladığını gösterir. Kusursuz dengelenmiş bir işlem bile yine de yanlış hesaba, yanlış satıcıya veya yanlış vergi muamelesiyle kaydedilmiş olabilir. Denge gereklidir ancak yeterli değildir. Geri kalanını yakalayan şey mutabakattır.

Defter değiştirilemez (immutable) ise hataları nasıl düzeltirim?

Ters kayıt (reversing entry) atar ve ardından düzeltilmiş olanı kaydedersiniz. Orijinal kayıt görünür kalır ki bütün mesele de budur. Değiştirilemezlik denetim izini (audit trail) korur, hatalarınızı hapsetmez.

Muhasebe API'si beni otomatik olarak uyumlu (compliant) hale getirir mi?

Hayır. Muhasebe yapısını uygular ve kullanılabilir kayıtlar üretir. Yasal uyumluluk hâlâ bulunduğunuz yargı bölgesine, sözleşmedeki rolünüze, vergi muamelenize, ödeme düzenlemelerine, KYC ve AML süreçlerinize ve raporlama yükümlülüklerinize bağlıdır.

İleri okuma

• Pazar yeri muhasebesi için çift yönlü defter API'leri
• Çift yönlü defterleri tanımlamak, Formance