DİA Web Servisi ile Entegrasyon: Oturum, Kontör ve Çağrı Planı

Masaüstü muhasebe programlarında entegrasyon konuşulurken ilk soru genellikle "veritabanına bağlanabilir miyiz" olur. DİA'da bu soru sorulmaz. Ürün bulutta çalışır, veritabanı sizin sunucunuzda durmaz ve üreticinin geliştirici dokümanında tanımlanan entegrasyon yolu web servistir.

Bu yazı, DİA entegrasyonu planlayan bir firmanın ya da yazılım ekibinin bilmesi gereken üç konuyu anlatıyor: oturum nasıl yönetilir, kontör nasıl tüketilir ve çağrı planı nasıl yapılır.

Web Servis Nasıl Çalışır?

DİA'nın arayüzü JSON tabanlı bir REST servisidir. Bağlantının TLS 1.2 ya da üzeri ile kurulması zorunludur. Eski bir sunucudan ya da eski bir çalışma ortamından çağrı yapılacaksa bu ilk gün kontrol edilir, çünkü ilk bağlantı hatası çoğu zaman koddan değil TLS ayarından kaynaklanır.

Adres, müşteriye özel sunucu koduyla başlayan bir alt alan adı üzerinden kurulur ve modül adıyla devam eder. Kalıbın güncel hâli proje başında üretici dokümanından teyit edilir.

Servis adları düzenli bir kalıbı izler: modül, nesne ve aksiyon alt çizgiyle birleşir.

Modül kodu	Kapsam	Örnek servis
sis	Oturum, kontör, yetki	sis_kontor_sorgula
scf	Cari, stok, fatura	scf_carikart_listele, scf_carikart_ekle
muh	Muhasebe	Aynı kalıp, muh önekiyle

Aksiyonlar her nesnede benzerdir: listele, getir, ekle, guncelle, sil. Bu düzen sayesinde entegrasyon katmanı her servis için ayrı kod yazmak yerine nesne ve aksiyonu parametre olarak alacak biçimde kurulabilir.

Oturum Yönetimi

DİA'da kimlik doğrulama iki aşamalıdır.

1. API anahtarı, kullanıcı adı ve şifreyle oturum açma servisi çağrılır.
2. Servis bir session_id döner. Sonraki her çağrıda bu değer ilk parametre olarak gönderilir.

API anahtarı yalnızca oturum açarken kullanılır. Sonraki çağrılarda taşınmaz.

Oturum bir saat işlemsiz kalırsa düşer. Her çağrı bu süreyi sıfırlar. Bunun iki sonucu vardır.

Yoğun çalışan akışta: Her işlemde yeniden oturum açmak gereksizdir. Mevcut oturum yeniden kullanılır.

Seyrek çalışan akışta: Gece boyunca çağrı yapmayan bir entegrasyon, sabah ilk çağrıda düşmüş bir oturumla karşılaşır. Bu durumun hataya dönüşmemesi için oturum tazeleme mantığı koda yazılır: çağrı oturum hatasıyla dönerse yeniden oturum açılır ve çağrı bir kez daha denenir.

Bağlantı İçin Gerekenler

Bağlantıyı kurmak için dört bilgi gerekir:

• API anahtarı
• Web servis kullanıcı adı ve şifresi
• Firma kodu
• Dönem kodu

Bunlara ek olarak iki ayar kontrol edilir.

Kullanıcı yetkisi. İlgili kullanıcıda "Web Servis Çağırabilir" yetkisinin açık olması gerekir. Bu yetki kapalıyken alınan hata kolayca yanlış yorumlanır ve sorun kodda aranır.

İzin verilen IP'ler. Hesapta izin verilen IP adresleri tanımlıysa çağrılar yalnızca o adreslerden kabul edilir. Entegrasyon bir bulut sunucusunda çalışacaksa çıkış adresinin sabit olması gerekir.

API anahtarı, üretici dokümanına göre DİA'dan e-posta ile talep edilir. Uygulamada bu talebe çoğu zaman firmanın çalıştığı DİA çözüm ortağı aracılık eder. Anahtar gelmeden canlı bağlantı gerektiren işler takvime yazılmaz.

Kontör: Tasarımı Belirleyen Kalem

Birçok serviste tasarımı "saniyede kaç istek atılabilir" sorusu sınırlar. DİA'da sınırlayan şey farklıdır. Üretici dokümanı API çağrıları için işlem sınırı bulunmadığını belirtir. Buna karşılık her web servis çağrısı 0,0125 kontör tüketir. Oturum açma ve kapatma gibi bazı işlemler bu tüketimin dışındadır. Kalan bakiye sis_kontor_sorgula servisiyle sorgulanabilir.

Bu, her çağrının bir maliyeti olduğu anlamına gelir. Veri değişmemiş olsa bile çağrı yapıldıysa kontör düşer.

Örnek bir hesap

Aşağıdaki hesap yalnızca tasarım farkını göstermek içindir. Kontörün parasal karşılığı hesabınızın koşullarına bağlıdır ve burada yer almıyor.

Diyelim ki entegrasyon beş farklı nesneyi izliyor: sipariş, cari, stok, fatura ve tahsilat.

Tasarım	Günlük çağrı	Günlük tüketim
Her nesne dakikada bir yoklanıyor	5 x 1.440 = 7.200	90 kontör
Her nesne 15 dakikada bir, tarih filtresiyle	5 x 96 = 480	6 kontör
Yalnızca iş saatlerinde (10 saat), 15 dakikada bir	5 x 40 = 200	2,5 kontör

Üç tasarım da aynı veriyi taşır. Aradaki fark, boşa yapılan çağrıların sayısıdır. İlk tasarımda gece boyunca hiçbir kayıt değişmese de tüketim sürer.

Tüketimi azaltan tercihler

• Filtreli liste çağrısı. Tüm kayıtları istemek yerine son çalışmadan bu yana değişenler istenir.
• Liste, sonra hedefli getir. Önce liste alınır, ayrıntı yalnızca gereken kayıt için istenir.
• Çalışma saatine göre sıklık. Gece ve hafta sonu için aralık uzatılır.
• Yerel rapor tablosu. Rapor ekranı her açılışta DİA'yı çağırmaz. Veri belirli aralıklarla çekilir ve rapor kendi tablosundan beslenir.
• Tüketimin izlenmesi. Kalan bakiye düzenli sorgulanır ve izleme ekranında gösterilir. Tasarım hatası ilk hafta içinde görünür hâle gelir.

Yazma: Servisler ve Dönen Yanıt

DİA'da yazma resmi olarak desteklenir. Nesneler için ekleme, güncelleme ve silme servisleri tanımlıdır. Ekleme ve güncelleme yanıtında oluşan kaydın anahtar değeri ve işlem mesajı döner.

Bu iki bilgi sağlam bir entegrasyon için gereklidir:

• Anahtar saklanır. Karşı taraftaki kayıt kendi kaydınızla eşleştirilir. Aynı sipariş ağ kesintisi sonrası yeniden gönderilirse ikinci bir kayıt oluşmaması için önce bu eşleşmeye bakılır.
• İşlem mesajı kaydedilir. Reddedilen kayıt sessizce kaybolmaz; sebebiyle birlikte listelenir.

Silme servisi bulunsa da entegrasyon kullanıcısına silme yetkisi vermek zorunlu değildir. İptal ve düzeltme akışları güncelleme üzerinden kurulabilir. Böylece hatalı çalışan bir döngü geri alınamaz bir sonuç üretmez.

Tetikleme mi, Zamanlanmış Çekme mi?

Kontör nedeniyle "değişiklik olduğunda haber ver" yaklaşımı, sürekli sormaktan daha ekonomiktir. DİA'da webhook ile başlatılan türde süreç tanımlanabiliyor; sürece bir geri çağırma adresi ve bir jeton giriliyor.

Bunun her nesne için kullanılabilen genel bir bildirim mi, yoksa belirli süreçlerle sınırlı bir tetikleyici mi olduğunu doğrulayabildiğimiz kaynaklarda net göremedik. Kapsamı kurulumda teyit edilir.

Bu belirsizlik nedeniyle tasarım iki katmanlı kurulur. Tetikleme kullanılabiliyorsa ana yol odur. Arkada, seyrek çalışan ve dar filtreli bir mutabakat turu kaçan kayıtları yakalar.

Başlamadan Önce Kontrol Listesi

1. API anahtarı talep edildi mi
2. Web servis kullanıcısı açıldı mı, "Web Servis Çağırabilir" yetkisi verildi mi
3. Firma kodu ve dönem kodu belli mi
4. İzin verilen IP tanımı var mı, entegrasyonun çıkış adresi sabit mi
5. Hangi nesneler okunacak, hangileri yazılacak
6. Her nesne için kabul edilebilir gecikme ne kadar
7. Kontör bakiyesini kim izleyecek

Altıncı madde çağrı planının temelidir. Stok bakiyesinin 15 dakika gecikmeyle güncellenmesi kabul edilebiliyorsa dakikada bir yoklamaya gerek yoktur.

Sıkça Sorulan Sorular

DİA veritabanına doğrudan bağlanılabilir mi?

Hayır. DİA bulutta çalışır ve veritabanı müşterinin erişimine açık değildir. Üreticinin geliştirici dokümanında tanımlanan entegrasyon yolu web servistir.

Kontör biterse entegrasyon durur mu?

Çağrılar kontör tükettiği için bakiyenin izlenmesi gerekir. Bakiye bittiğinde nasıl davranıldığı hesabınızın koşullarına bağlıdır ve DİA çözüm ortağınızla teyit edilir. Entegrasyon tarafında bakiye belirli bir eşiğin altına indiğinde uyarı üretilmesi önerilir.

Oturum neden aniden düşüyor?

Oturum bir saat işlemsiz kalırsa düşer. Seyrek çalışan akışlarda bu beklenen bir durumdur. Çözüm, oturum hatası alındığında yeniden oturum açıp çağrıyı tekrarlayan bir mantığın koda yazılmasıdır.

Birden fazla firma ve dönem aynı entegrasyonla yönetilebilir mi?

Yönetilebilir. Firma kodu ve dönem kodu çağrının bağlamını belirler. Bu iki değer koda sabit yazılmaz, yapılandırmadan okunur. Yeni bir firma ya da dönem açıldığında kod değişikliği gerekmez.

DİA çözüm ortağı mısınız?

Hayır. D'Cloud Software hiçbir yazılım üreticisinin bayisi ya da çözüm ortağı değildir. API anahtarı, lisans ve kontör tarafı DİA ve çözüm ortağınızın alanıdır. Bizim yaptığımız iş, belgelenmiş web servis üzerinden çalışan entegrasyonu geliştirmektir.

Teslimden sonra destek nasıl işliyor?

Teslim sonrası 15 gün ücretsiz hata düzeltme sözleşmeye yazılır. Çağrı hatalarının ve tüketimin sürekli izlenmesi ayrı bir bakım maddesinde tanımlanır.

Sonuç

DİA'da entegrasyon tek bir yoldan, web servis üzerinden kurulur. Oturumun bir saatlik işlemsizlik süresi ve her çağrının kontör tüketmesi, tasarımı baştan belirleyen iki kuraldır. İyi bir DİA entegrasyonu kodla değil, çağrı planıyla başlar: hangi veri, hangi sıklıkta, hangi filtreyle.

DİA hesabınızı e-ticaret sitenize, saha uygulamanıza ya da üretim ekranlarınıza bağlamak istiyorsanız, çağrı planını birlikte çıkarmak için iletişime geçin.