Muhasebe Programı Entegrasyonu: Logo, Netsis, Paraşüt

Muhasebe programı entegrasyonu üç yöntemden biriyle yapılır: bulut programlarda (Paraşüt, Bizim Hesap gibi) programın REST API’si üzerinden, sunucuya kurulu programlarda (Logo, Netsis, Mikro gibi) programın kendi servis katmanı ya da ara veritabanı üzerinden, ikisi de kapalıysa dosya aktarımıyla (XML/CSV klasörü). Yöntem değişse de akan veri hep aynıdır: sipariş, müşteri ve tahsilat kayıtları web tarafından muhasebeye gider; stok, fiyat ve fatura bilgisi muhasebeden geri gelir. Projenin süresini belirleyen şey de API dokümanı değil, iki taraftaki kodların eşleştirilmesidir.

Entegrasyonda hangi veri hangi yöne akar?

Bir muhasebe entegrasyonunu konuşmaya başlarken ilk soru “hangi programı bağlayacağız” değil, “hangi kayıt hangi tarafta doğar” olmalıdır. Teknik olarak bu bir API entegrasyonu işidir; ama sözleşmeye dönüşen kısmı aşağıdaki beş akıştır:

• Sipariş → satış faturası: sitede ya da e-ticarette oluşan sipariş, muhasebede faturaya dönüşür. Kalemler, iskonto, KDV oranı ve kargo bedeli faturaya doğru satırlarda düşmelidir.
• Müşteri → cari kart: yeni müşteri muhasebede cari olarak açılır. Aynı müşteriye ikinci kart açılmasın diye vergi numarası, TCKN ya da e-posta üzerinden bir eşleştirme kuralı belirlenir.
• Stok ve fiyat → siteye: güncel stok ve liste fiyatı muhasebeden siteye yazılır. Burada tek doğruluk kaynağının hangi taraf olduğu baştan karara bağlanmalıdır.
• Tahsilat → muhasebe: sanal POS, havale veya kapıda ödeme tahsilatı ilgili faturaya kapatılır. İade ve kısmi iade ayrı bir akıştır, sonraya bırakılmaz.
• Fatura numarası ve belge → siteye: müşteri kendi hesabından faturasını görebilsin diye numara ve belge bağlantısı web tarafına geri yazılır.

Bu beş akışın hepsine ihtiyacınız olmayabilir. Küçük hacimde yalnızca “sipariş → fatura” yönünü kurup stoku elle yönetmek de geçerli bir karardır; önemli olan hangi yönün otomatik olmadığını bilerek başlamaktır.

Üç yöntem: bulut API, kurulu program, dosya aktarımı

Bulut muhasebe programları modern bir REST API sunar: token ile kimlik doğrulaması yaparsınız, fatura ve cari kayıtlarını JSON olarak gönderirsiniz, dakikada kaç istek atabileceğiniz belgede yazar. Entegrasyonun en hızlı kurulduğu senaryo budur; sunucu, VPN ya da ek lisans gerekmez.

Sunucuya kurulu programlarda tablo değişir. Programın kendi servis katmanı çoğu zaman ayrı lisanslanan bir modüldür ve hangi sürümde nelerin açık olduğu değişir — bu yüzden geliştirmeye başlamadan önce sürüm ve modül bilgisini bayinize teyit ettirin. Servis katmanı yoksa ikinci seçenek ara veritabanı yöntemidir: entegrasyon kayıtları bir kuyruk tablosuna yazar, programın kendi aktarım aracı bu tablodan okur. Canlı muhasebe tablolarına doğrudan kayıt atmak ise yapılmaması gereken şeydir; muhasebe kurallarını ve kayıt bütünlüğünü bozar, üstelik sizi destek kapsamı dışına çıkarır.

Üçüncü yöntem, ikisi de mümkün olmadığında kalan dosya aktarımıdır: entegrasyon belirli aralıklarla XML ya da CSV üretir, muhasebe programı bunu içeri alır. Kulağa ilkel gelse de yüksek hacimli, günlük mutabakatla çalışan şirketlerde hâlâ yaygındır. Karşılığında gerçek zamanlı bilgi vermez: stok gün içinde eskir. Aynı tercih e-fatura tarafında da karşınıza çıkar; e-fatura entegrasyonu yazısında portal, özel entegratör ve doğrudan entegrasyon farkını ayrıntılı anlattık.

Entegrasyon projelerinin süresini API dokümanı değil eşleştirme (mapping) belirler. Ürün kodu, birim, KDV oranı, iskonto ve ödeme tipi iki tarafta aynı dili konuşmuyorsa her sipariş elle düzeltilir. Bağlantıyı kurmak bir haftalık işse, eşleştirme ve test genelde iki haftalık iştir.

Bulut programda REST API akışı nasıl kurulur?

Bulut API ile çalışırken kritik nokta faturayı doğrudan sipariş anında göndermemektir. Muhasebe programı bakımdaysa ya da istek limiti dolmuşsa çağrı düşer ve sipariş faturasız kalır. Doğru kurgu şudur: sipariş kapanınca bir kuyruk kaydı oluşur, kuyruğu işleyen görev faturayı gönderir, başarısız istekleri tekrar dener. Aynı siparişin iki kez faturalanmasını engelleyen anahtar da bu akışta durur:

// Kuyruktan çalışır: sipariş kapandığı anda değil, kuyruk sırası gelince.
// Idempotency anahtarı aynı siparişin iki kez faturalanmasını engeller.
async function faturaGonder(order: Order) {
  const res = await fetch(BASE_URL + '/sales_invoices', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + (await getAccessToken()),
      'Content-Type': 'application/json',
      'Idempotency-Key': 'order-' + order.id,
    },
    body: JSON.stringify({
      contact_id: order.accountingContactId, // eşleşen cari kart
      issue_date: order.paidAt.slice(0, 10),
      items: order.lines.map((line) => ({
        product_id: line.accountingProductId, // eşleşen ürün kodu
        quantity: line.qty,
        unit_price: line.unitPriceExclVat, // KDV hariç birim fiyat
        vat_rate: line.vatRate,
      })),
    }),
  });

  // 429 ve 5xx kalıcı hata değildir: kuyrukta bekletip yeniden dene.
  if (res.status === 429 || res.status >= 500) {
    throw new RetryableError('Muhasebe API geçici hata: ' + res.status);
  }

  const invoice = await res.json();
  await saveInvoiceRef(order.id, invoice.id, invoice.number);
}

İki ayrıntı çoğu projede sonradan sorun çıkarır. Birincisi token yenilemesi: erişim tokenı saatlerle ölçülen bir ömre sahiptir, yenileme akışını baştan yazmazsanız entegrasyon bir gece sessizce durur. İkincisi bildirim yönü: pek çok muhasebe programı size webhook göndermez, yani “fatura kesildi mi, tahsilat kapandı mı” bilgisini belirli aralıklarla sormanız (polling) gerekir. Sorgu aralığını istek limitine göre seçin.

Kurulu programda (Logo, Netsis, Mikro) neye hazırlıklı olmak gerekir?

Kurulu programlarda işin yarısı erişim ve yetki konusudur. Geliştirme başlamadan aşağıdaki maddeler netleşmiş olmalı; aksi hâlde ekip haftalarca bekler:

• Sunucuya erişim: VPN ya da statik IP üzerinden kısıtlı port açılması, kimin onaylayacağı.
• Test ortamı: canlı veritabanının kopyası. Test ortamı olmayan entegrasyon canlıda denenir, bu da yanlış fatura demektir.
• Lisans ve modül teyidi: servis/entegrasyon katmanı sürümünüzde açık mı, ek lisans gerekiyor mu.
• Yetki tanımı: entegrasyonun hangi kullanıcı adıyla hangi kaydı açabileceği. Fatura kesme yetkisi ile cari açma yetkisi ayrı yönetilir.
• Hata kanalı: bir kayıt aktarılamadığında bunu kim görecek. Sessizce biriken hata kuyruğu, ay sonunda mutabakat kâbusuna dönüşür.

Bu adımların çoğu, şirket içinde ERP kullanan işletmelerde zaten tanımlıdır. Muhasebe programınızın gerçekte bir ERP’ye dönüşüp dönüşmediğini tartışıyorsanız ERP nedir ve küçük işletmeler için ERP yazıları bu kararı ayrı ayrı ele alıyor.

Entegrasyonu bozan beş klasik hata

• Tek doğruluk kaynağı belirlenmemesi: stok hem sitede hem muhasebede düşülür, birkaç gün içinde iki taraf birbirini tutmaz.
• Vergi ve birim eşleştirmesinin eksik bırakılması: yanlış KDV oranıyla kesilen fatura düzeltme işlemi gerektirir, bu da muhasebenin işini artırır.
• İptal ve iade akışının sonraya bırakılması: canlıya çıktıktan sonraki ilk hafta mutlaka bir iade gelir ve elde kalan fatura elle düzeltilir.
• Kuyruk ve tekrar deneme olmadan doğrudan API çağrısı: muhasebe programı bakıma girdiğinde o saatteki siparişler faturasız kalır.
• Kayıt izinin tutulmaması: hangi siparişin hangi faturaya gittiğini gösteren bir ekran yoksa mutabakat elle yapılır ve entegrasyonun kazandırdığı zaman geri gider.

Bu hataların dördü aynı kökten çıkar: entegrasyon “veri taşıma” işi sanılır, oysa mutabakat işidir. E-ticaret tarafında aynı disiplini kargo entegrasyonu ve pazaryeri entegrasyonu projelerinde de görürsünüz; muhasebe bu zincirin son halkasıdır ve hatalar burada paraya dokunduğu için en pahalı olanıdır.

Süre ve maliyet nasıl hesaplanır?

Muhasebe entegrasyonunun fiyatı tek kalem değildir; üç kalemin toplamıdır. Geliştirme tarafı adam-gün üzerinden hesaplanır ve kalemleri şunlardır:

• Keşif ve eşleştirme: hangi alan neye karşılık geliyor, hangi kayıt hangi tarafta doğuyor. Projenin en kısa ama en belirleyici aşaması.
• Geliştirme: kuyruk, tekrar deneme, kayıt izi ve hata ekranı dâhil. Tek yönlü basit bir akış ile stok geri beslemeli iki yönlü akış arasında ciddi fark vardır.
• Test: gerçek veriyle, iade ve iptal senaryoları dâhil. Test ortamı yoksa bu süre uzar.
• Canlıya geçiş ve ilk ay takibi: ilk mutabakat kapanana kadar entegrasyon izlenir.
• Yazılım tarafı dışı kalemler: muhasebe programının modül/lisans ücreti ve varsa entegratör aboneliği.

Adam-gün hesabının nasıl kurulduğunu ve teklifleri karşılaştırırken neye bakmanız gerektiğini özel yazılım maliyeti yazısında ayrıntılı anlattık. Kısa yol şu: teklifte “entegrasyon” tek satırsa henüz kapsam konuşulmamış demektir; hangi akışların hangi yönde çalışacağı maddelenmiş olmalı.

Sonuç

Muhasebe programı entegrasyonu teknik olarak orta zorlukta, operasyonel olarak yüksek hassasiyette bir iştir: bağlantı yöntemini programınız belirler, projenin süresini ise eşleştirme ve mutabakat disiplini belirler. Bulut programda REST API ile hızlı yol alırsınız; kurulu programda erişim, lisans ve test ortamını baştan çözmeniz gerekir. Her iki durumda da kuyruk, tekrar deneme ve kayıt izi olmadan yapılan entegrasyon ilk aksaklıkta elle düzeltmeye döner. Kendi sisteminizi muhasebe tarafına bağlamak için bir yol haritası isterseniz kurumsal çözümler hizmetimize bakabilir ya da teklif alarak kapsamı birlikte netleştirebiliriz.