Muhasebe API Nedir? Platform Geliştiricileri İçin Teknik Olmayan Bir Rehber

Muhasebe API'sinin net bir tanımı, vergi API'si veya ödeme API'sinden farkları ve bir API ile entegrasyon yapmadan önce neleri kontrol etmeniz gerektiği.

Muhasebe API'si, bir programın başka bir programın defterini tutmasını sağlayan bir arayüzdür. Yazılımınız HTTP üzerinden bir finansal olay iletir; API ise bu olayı bir hesap planına (chart of accounts) göre dengeli çift taraflı yevmiye kayıtlarına (double-entry journal entry) dönüştürür, sessizce değiştirilemeyecek şekilde saklar, vergi muamelesini uygular ve aynı arayüz üzerinden size raporları, belgeleri ve dışarı aktarımları geri sunar.

Bu tanım işin büyük kısmını özetler. Bu makaledeki her şey, bu tanımın doğal bir sonucudur.

Tek cümlelik özet

Muhasebe API'si, uygulamanızdan gelen finansal olayları kabul eder, her birini dengeli bir yevmiye kaydına dönüştürür; vergi muamelesi ve destekleyici kanıtlarıyla birlikte değiştirilemez (immutable) olarak saklar ve elde edilen defteri, belgeleri ile raporları programlanabilir uç noktalar (endpoint) olarak dışarı açar.

Bir ürün kendisini muhasebe API'si olarak adlandırıyor ancak yevmiye kaydı üretmiyorsa, o başka, kulağa hoş gelen bir şeydir. Bu durum mutlaka kötü olduğu anlamına gelmez, yalnızca soracağınız işi yapamayacağı anlamına gelir.

Muhasebe API'si ne değildir?

Genellikle bir projenin ilerleyen aşamalarında, birbiriyle yakın dört ürün kategorisi muhasebe API'leriyle karıştırılır.

Kategori	Ne yapar?	Ne yapmaz?
Vergi hesaplama API'si	Bir işlem için doğru oranı veya vergi tutarını döndürür	Defterinizi tutmaz veya karar arkasındaki kanıtları yasal saklama süresi boyunca depolamaz
Ödeme API'si	Taraflar arasında para transferi yapar ve bu hareketleri raporlar	Kazanılan komisyonu, borçlanılan KDV'yi ya da ödeme ile hak ediş arasındaki satıcı borcunu kaydetmez
Birleştirilmiş (Unified) veya toplayıcı API	Müşterinizin mevcut muhasebe yazılımındaki verileri okur ve yazar	Kayıt sistemi (system of record) olarak hareket etmez; defteriniz her müşterinin halihazırda kullandığı araçta yaşar
Raporlama veya BI API'si	Mevcut bir defterden rakamları okur ve görselleştirir	Rakamların türetildiği kayıtları oluşturmaz

Bunların her birinin gerçek kullanım alanları vardır. Kayıt sistemi olması gereken bir platform, bunun yerine değil, bu sistemin altında bir muhasebe API'sine ihtiyaç duyar.

Bir muhasebe API'sinin yapması gereken beş şey

1. Dengeli kayıtlar tutmak. Her olay, toplamı aynı rakama ulaşan borç (debit) ve alacaklara (credit) dönüşür. %15 komisyon alan bir pazar yerinde bir alıcı 100 € ödediğinde, kayıt 100 €'luk bir takas hesabını (clearing account) borçlandırır, 85 €'luk satıcı borcunu (seller payable) ve 15 €'luk komisyon gelirini alacaklandırır. Bu bir muhasebe ritüeli değildir; bir rapora ulaşmadan önce tüm entegrasyon hatası sınıflarını yakalayan yapısal bir kontroldür.

2. Geçmişi korumak. Kaydedilmiş bir girdi düzenlenmez. Bir hata, orijinaline bağlı olan bir ters kayıt (reversal) artı düzeltilmiş bir kayıt ile düzeltilir. Kapatılmış aylar kilitlenir, böylece bu aylara yeni bir tarih atanamaz.

3. Vergiyi çözmek. AB ticareti için bu durum; tedarik yeri (place of supply), tevkifat (reverse charge), resmi sicilden kontrol edilen KDV kimlik numaraları ve kararı haklı çıkaran kanıtların, hesaplamadan sonra silinmek yerine işlemin yanında saklanması anlamına gelir.

4. Dışarıdaki para ile mutabakat yapmak. Hiçbir banka ekstresiyle karşılaşmayan defterler birer tahminden ibarettir. API, ekstreleri veya sağlayıcı mutabakatlarını içeri aktarmalı ve bunları kaydedilenlerle eşleştirmelidir.

5. Dışarı aktarmak. Raporlar, belgeler ve denetim dosyaları; bir insan muhasebecinin ve vergi dairesinin kabul edeceği formatlarda olmalıdır.

İlk üçünü yapıp son ikisini yapmayan bir ürün, bir kişinin her ay e-tablolarla (spreadsheet) çalışmasına neden olur.

Bir çağrı gerçekte neye benzer?

İşin mekaniği muhasebenin kendisinden daha basittir. Nordlet API'sinde her işlem, öngörülebilir bir yapıya sahip RPC tarzı bir POST isteğidir:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

Bir satış faturası oluşturur ve ardından bunu düzenlersiniz. Belgeyi düzenlemek muhasebenin gerçekleştiği andır: belge boşluksuz numarasını alır, dengeli yevmiye kaydı işlenir ve KDV satırları bununla birlikte kaydedilir. Platformunuz hiçbir zaman borç ve alacakları elle birleştirmez.

Bu kod parçasındaki üç detay, uç nokta adından daha önemlidir:

Anahtar üzerindeki kapsam (scope). Bir anahtar, sales:write gibi izinler taşır, böylece bir entegrasyon yalnızca ihtiyaç duyduğu erişimi alır.
İşlem tekilliği anahtarı (idempotency key). Aynı istek gövdesini aynı anahtarla tekrar denediğinizde ikinci bir fatura yerine saklanan yanıtı geri alırsınız. Farklı bir gövdeyle aynı anahtarı gönderdiğinizde ise istek sessizce kabul edilmek yerine idempotency_key_reuse hatasıyla reddedilir.
String olarak para birimleri. Tutarlar kayan noktalı sayılar (float) değil ondalık string'lerdir, çünkü float'lar yıl sonunda ortaya çıkan şekillerde kuruş kayıplarına yol açar.

Mimarinizdeki yeri

Uygulamanız ön yüz ve iş olaylarının kaynağı olarak kalmaya devam eder. Muhasebe API'si ise bunun arkasındaki finansal kayıt sistemi haline gelir. Akış genellikle şu şekildedir:

Ürününüzde bir olay gerçekleşir: bir sipariş, iade, hak ediş veya abonelik yenileme.
Arka ucunuz (backend) muhasebe API'sini olay ve bir idempotency key ile çağırır.
API yevmiye kaydını işler, KDV'yi uygular ve kendi kayıtlarınızda saklayacağınız tanımlayıcıları (identifier) döndürür.
sale_invoice.paid gibi bir webhook, durum değiştiğinde sisteminize haber verir; böylece durumları yoklamak (polling) yerine olaylara tepki verirsiniz.
Banka işlemleri bir banka akışı (bank feed) veya ekstre içe aktarımı aracılığıyla gelir ve kaydedilen belgelerle eşleştirilir.
Dönem sonunda, aynı verilerden raporlar ve vergi defterleri üretilir, ardından kapanan ay kilitlenir.

Bu listedeki hiçbir şey, bir insanın muhasebe uygulamasını açmasını gerektirmez. Kategorinin amacı da budur.

Alternatiflerle karşılaştırma

Yaklaşım	Başlama çabası	Denetim konumu	İşlem hacmiyle birlikte ölçeklenme
E-tablolar ve manuel veri girişi	En düşük	Zayıf; geçmiş düzenlenebilir	Hayır
Muhasebe uygulaması artı CSV dışa aktarımları	Düşük	Tamamen disipline bağlı	Kötü; birileri dosyaları içe aktarmalı
Her müşterinin kendi defterine bağlanan toplayıcı API	Orta	Müşterinin aracının sunduğu kadardır	Evet, ancak kayda hiçbir zaman sahip olmazsınız
Gömülü (Embedded) muhasebe API'si	Orta	Defter değiştirilemez ve dönemler kilitliyse güçlüdür	Evet
Kendi defterinizi inşa etmek	En yüksek	Yalnızca kontrolleri de inşa ederseniz güçlüdür	Evet, ve sonsuza kadar siz bakarsınız

Kendi sisteminizi kurmak bazı ekipler için geçerli bir seçenektir. Bu durum pazar yerleri için inşa et veya satın al rehberimizde daha ayrıntılı olarak ele alınmıştır.

Entegrasyondan önce neleri kontrol etmelisiniz?

Bakiye türetiliyor mu yoksa saklanıyor mu? Bir satıcı bakiyesinin yevmiye satırları üzerinde bir sorgu mu yoksa birisinin güncellediği bir sütun mu olduğunu sorun. Bunlardan yalnızca biri denetimden sağ çıkar.
Yeniden deneme (retry) durumunda ne olur? Aynı isteği iki kez gönderin ve kayıtları sayın.
Onaylanmış (posted) bir kaydı düzenleyebilir misiniz? Yanıt belgelendirilmiş bir düzeltme yoluyla hayır olmalıdır.
Kilitli bir dönem gerçekten de bir kaydı reddediyor mu? Sandbox ortamında deneyin. Nordlet, kilitli bir döneme tarihlenmiş bir kayıt için 409 hatası döndürür.
Para birimi nasıl temsil ediliyor? Ondalık string'ler mi yoksa tamsayı alt birimler mi? Asla float olmamalıdır.
Denetim kaydında (audit record) ne var? Aktör, işlem, varlık ve değişikliğin kendisi; log dosyalarına gömülmek yerine sorgulanabilir olmalıdır.
Oran limitleri (rate limit) nelerdir? Nordlet, API anahtarı başına dakikada 300 isteğe izin verir ve kalan bütçenizi yanıt başlıklarında bildirir. Rakam ne olursa olsun, senkronizasyonunuzu tasarlamadan önce bunu bilin.
Verilerinizi nasıl dışarı aktarırsınız? Bir muhasebeciye teslim edebileceğiniz formatlarda raporlar, belgeler ve yevmiyeler.

Bunların her biri bir sandbox şirketine karşı bir öğleden sonra test edilebilir. Sağlayıcı özellik listeleri kanıt değildir; tekrarlanabilir bir test kanıttır.

FAQ

Muhasebe API'si ile muhasebe yazılımı aynı şey midir?

Arayüzü yer değiştirmiş muhasebe yazılımıdır. Geleneksel muhasebe yazılımı defterin önüne bir insan koyarken, muhasebe API'si kodunuzu oraya koyar. Alttaki yükümlülükler, çift taraflı kayıt yapısı ve raporlar aynıdır.

Kullanırsam yine de bir muhasebeciye ihtiyacım var mı?

Evet. Bir API kaydı, hesaplamayı ve raporlamayı otomatize eder. Sınıflandırma, karşılıklar veya belirli bir sözleşmenin nasıl ele alınması gerektiği konusunda yargı kararları vermez ve çoğu ülkede yasal hesaplarınızı imzalamaz veya beyanname vermez.

Çift taraflı muhasebeyi anlamadan bir muhasebe API'si kullanabilir miyim?

Kısmen. İyi bir API, fatura gibi bir ticari belgeden yevmiye kayıtlarını sizin için oluşturur. Ancak bir raporu okurken veya bir denetçiye bakiyeyi açıklarken hesapların ne anlama geldiğini yine de anlamanız gerekir.

Muhasebe API'si ile defter (ledger) API'si arasındaki fark nedir?

Bir defter API'si hesaplar arasındaki dengeli hareketleri kaydeder. Muhasebe API'si bunu yapar ve üzerine yasal katmanı ekler: yasal numaralandırmaya sahip belgeler, KDV muamelesi, vergi defterleri, duran varlıklar, dönem kapanışı ve bir bölgenin beklediği raporlar. Her muhasebe API'si bir defter içerir; ancak her defter bir muhasebe sistemi değildir.

Entegrasyon ne kadar sürer?

İlk çalışan akış için (müşteri oluşturma, fatura düzenleme, ödeme alma, yevmiye kaydını görme) yazılımlar için uygun bir SDK ve sandbox ile haftalar yerine günler planlayın. İadeleri, düzeltmeleri, çoklu para birimini, mutabakatı ve dönem kapanışını kapsayan bir prodüksiyon entegrasyonu daha büyük bir iştir ve dürüst tahmin, ürününüzün bu durumlardan kaç tanesini gerçekten ürettiğine bağlıdır.