Mikro Desktop API ile Entegrasyon: Mimari, Kimlik Doğrulama ve Tuzaklar

Giriş: Neden Mikro ERP Entegrasyonu "Bir Defa Kur, Unutacaksın" Modeli Değil?

Şöyle bir durum düşünün. E-ticaret sitenizden gelen siparişler Mikro'ya otomatik aktarılıyor ve aylardır sorunsuz çalışıyor. Mikro büyük sürüm yükseltmesi alıyor, ertesi sabah aktarım duruyor. Sebep koda sabit yazılmış port numarası: servis artık başka bir portu dinliyor. Birkaç ay sonra Mikro'ya ikinci bir firma ekleniyor, aynı kodda yalnızca firma kodu değiştiriliyor ve bu kez kimlik doğrulama hatası alınıyor.

İki sorunun da kaynağı aynı: Mikro Desktop API, alışılmış veritabanı bağlantısı mantığıyla çalışmıyor. Makinede Windows servisi olarak koşan, JSON ile konuşan bir arayüz. Kimlik bilgisi her istekte gövdede taşınıyor, uç noktalar sürümleniyor, büyük sürüm geçişinde port değişiyor.

Bu yazı, üreticinin yayımladığı dokümanlarda yer alan bilgilere dayanıyor. Doğrulayamadığımız ayrıntıları yazmadık. Alan adları ve istek yapıları için tek doğru kaynak, kurulumunuzdaki sürüme ait API dokümanıdır.

Mikro Desktop API Mimarisi: Windows Servisi, Sabit Olmayan Port ve Sürüm Geçişleri

API-First Duruş ve HTTP Servisi

Mikro tarafında entegrasyonun resmi yolu Mikro Desktop API'dir. JSON ile çalışır; GET, POST, DELETE ve PATCH metotlarını kullanır. Makinede "Mikro Desktop API" adıyla bir Windows servisi olarak koşar.

Bunun pratik anlamı şu: API'nin çalışması Mikro uygulamasının açık olmasına değil, servisin ayakta olmasına bağlıdır. Veritabanı bağlantısını entegrasyon tarafı değil servis yönetir. Siz istek gönderirsiniz, servis sonucu JSON olarak döner.

Sürüme Göre Port Değişimi: V16 vs V17

Servisin dinlediği port sürüme göre değişir:

• Mikro V16: 8084
• Mikro V17: 8094

Port, kayıt defteri üzerinden değiştirilebilir. Değişiklikten sonra servisin yeniden başlatılması ve güvenlik duvarında ilgili iznin tanımlanması gerekir.

Portu koda sabit yazan entegrasyon, V16'dan V17'ye geçişin ertesi günü bağlantı kuramaz. Bu, en kolay önlenebilecek hatadır.

Önerimiz:

1. Port numarasını koda yazmayın, yapılandırma dosyasından okuyun.
2. Sürüm yükseltmesi planlandığında entegrasyonu geliştiren ekibe önceden haber verin.
3. Yükseltmeyi önce test ortamında deneyin.

Windows Servisi Bağımlılığı

Sunucu yeniden başladığında ya da servis durduğunda API erişimi kesilir. Entegrasyonda yeniden deneme ve zaman aşımı mantığı olmalıdır. Başarısız bir istek hemen hata olarak bırakılmaz; kısa aralıklarla birkaç kez yeniden denenir, yine olmazsa kayıt altına alınır ve ilgili kişiye bildirilir. Servisin ayakta olup olmadığını düzenli kontrol eden bir izleme de işe yarar.

Kimlik Doğrulama: Her İstekte Gövdede ve Çok Firmalı Yapının Gerçeği

ApiKey + Çalışma Yılı + Firma Kodu + Kullanıcı + Şifre

Mikro burada alışılmışın dışında bir yol izliyor. V2 ve V3 sonekli uç noktalarda oturum jetonu yoktur. Kimlik bilgisi her isteğin gövdesinde taşınır:

• API anahtarı (ApiKey)
• Çalışma yılı
• Firma kodu
• Kullanıcı kodu
• Şifrenin tarih önekli MD5 özeti

Şifre düz metin olarak gönderilmez; o günün tarihiyle birlikte özetlenir. Bunun bir yan etkisi var: gün dönümünde, isteğin hazırlandığı an ile sunucuya ulaştığı an farklı günlere denk gelirse doğrulama başarısız olabilir. Bu durumda önceki günün tarihiyle yeniden denemek gerekebilir.

V1 sonekli metotlar ise farklı çalışır: APILogin ile oturum açılır.

Çok Firmalı/Çok Dönemli Yapıda Ne Değişir?

Bir grupta üç şirket olduğunu ve hepsinin Mikro kullandığını düşünün. Veritabanına doğrudan bağlanan bir yapıda üç ayrı bağlantı tanımı yazardınız. Mikro Desktop API'de adres aynı kalır, değişen isteğin gövdesidir: firma kodu, çalışma yılı ve kullanıcı bilgisi.

Buradan çıkan tasarım kuralı şu: entegrasyon katmanı kimlik bilgisini istek başına üretmelidir. "Kurulumda tek firma var" varsayımıyla yazılan kod, ikinci firma açıldığında baştan elden geçirilir.

Çalışma yılının istekte verilmesinin bir sebebi daha var. Tablo adları dönemle değişmez, ama çalışma yılı devir sırasında ayrı bir veritabanına taşınmış olabilir. Hedef yılı yapılandırmadan okumak bu yüzden önemlidir.

Güvenlik Notu: Kimlik Bilgilerinin Saklanması

API anahtarı ve kullanıcı bilgileri kod deposuna ya da düz metin ayar dosyasına yazılmaz. Erişimi sınırlı bir sır saklama katmanında tutulur. Servise yerel ağ dışından erişilecekse bağlantı VPN ya da şifreli bir kanal üzerinden kurulur; servis doğrudan internete açılmaz.

Serbest SQL Ucu: Sadece Okuma ve Yazmanın Tipli Uç Noktalara Ayrılması

Neden Okuma Açık, Yazma Kapalı?

API içinde SqlVeriOkuV2 adında bir uç nokta var ve bu uca serbest SQL gönderilebiliyor. Üretici bu ucu yalnızca SELECT için belgeliyor. Kayıt oluşturma ve güncelleme ise iş nesnesine özel, tipli uç noktalara bağlı.

Yani üretici okumayı esnek bırakmış, yazmayı kendi çağrılarına yönlendirmiş. "Neden doğrudan tabloya yazmıyorsunuz" sorusunun cevabı Mikro'da bir tercih değil, ürünün tasarım kararıdır.

Bu ayrımın mantığı açık:

1. Doğrulama: Tipli uç noktadan geçen kayıt Mikro'nun kendi kontrollerinden geçer. Hatalı kayıt en baştan reddedilir.
2. Desteklenen kullanım: Belgelenmiş yolun dışına çıkan entegrasyon, sorun çıktığında elinizi zayıflatır.
3. Sürdürülebilirlik: Tipli uç noktalar sürümlenir; değişiklik yönetilen bir şekilde gelir.

Okuma Senaryosu: Özel Raporlar ve Analizler

Serbest SQL ucu, rapor ve analiz işlerinde kullanışlıdır. Stok hareketi, cari bakiye ya da satış verisini birleştirerek sorgulamak gerektiğinde tipli uç nokta bu esnekliği vermez.

Okurken iki Mikro kuralını bilmek gerekir:

• Firma ve şube filtresi: Mikro'da tablo adları düz ve Türkçedir (STOKLAR, CARI_HESAPLAR, STOK_HAREKETLERI). Firma ve şube ayrımı kolonlarla yapılır. Filtreyi unutan sorgu hata vermez, yanlış toplam üretir.
• Kod çözümleme: Pek çok kolon metin değil kod tutar. Üretici bunları çözmek için fonksiyonlar sunar. Kod anlamlarını tahminle tablolamak yerine bu fonksiyonlar kullanılır.

Performans sorumluluğu sorguyu yazandadır. Filtresiz ve geniş sorgular hem servisi hem veritabanını yorar.

Yazma Senaryosu: Tipli Uç Noktalar

Uç noktalar iş nesnesi bazında adlandırılır ve sürüm soneki taşır. Cari tarafında CariKaydetV2, CariGuncelleV2, CariListesiV2 ve CariListesiV3 bunun örnekleridir. e-Dönüşüm tarafında mükellef sorgulama ve fatura PDF alma uçları da API içindedir.

Yazarken dikkat edilecek bir Mikro kuralı daha var: tarih alanları, aksi belirtilmedikçe saat bilgisi içermemelidir. Tarih alanına saatli değer yazan entegrasyon hata almaz, ama gün bazlı raporlar bozulur. Yazma katmanına eklenecek ilk kontrollerden biri budur.

Hangi alanların zorunlu olduğu ve isteğin tam yapısı, kullandığınız sürümün API dokümanından okunur.

Uç Nokta Sürümleme: V1/V2/V3 Sonekleri ve Kırıcı Değişiklikler

Neden Sürümleme Önemli?

Uç noktalar V1, V2, V3 sonekleriyle yaşar. Eski sürümdeki bir uca bağlı kalan entegrasyon, yeni sürümle gelen alanları görmez. Çalışmaya devam eder, ama eksik çalışır.

Kırıcı Değişikliklerin İlan Edilmemesi

Üreticinin değişiklik kayıtlarında kırıcı değişiklikler ayrı bir etiketle işaretlenmiyor. Sürüm notunun içinde diğer maddelerle aynı görünürlükte duruyor. Örneğin v17.05e sürümünde hizmet, stok ve masraf kalemlerinin aynı JSON yapısında gönderilmesine geçildi. İstek gövdesini eski yapıya göre kuran bir entegrasyon bu değişiklikten doğrudan etkilenir.

Çözüm: Regresyon Testi

Her sürüm yükseltmesinden önce test ortamında şu kontroller yapılır:

1. Tüm yazma işlemleri örnek kayıtlarla yeniden denenir.
2. Okuma sorgularının döndürdüğü alanlar ve tipleri kontrol edilir.
3. Hata mesajları kayıt altına alınır.
4. Sürüm notları, kullanılan uç noktalar açısından gözden geçirilir.

Sürüm Yükseltme Stratejisi

Yeni bir uç nokta sürümü çıktığında hemen geçmek yerine:

1. Paralel test: Eski ve yeni sürüm test ortamında yan yana çalıştırılır, sonuçlar karşılaştırılır.
2. Alan eşleme: Eklenen ya da değişen alanlar belirlenir.
3. Yapılandırma: Uç nokta sürümü koda gömülmez, yapılandırmada tutulur.

API Key Başvuru Süreci ve Entegrasyon Hazırlığı

Nasıl API Key Alınır?

Mikro Desktop API kullanmak için API Key gerekir. Anahtar başvuruyla alınır:

1. Üreticinin API Başvuru Formu doldurulur.
2. API Kullanıcı Sözleşmesi onaylanır.
3. Anahtar, başvuru sahibinin hesabına tanımlanır.

Önemli bir ayrıntı: API'de bulunmayan bir tablo ya da alan ihtiyacı doğarsa, bu talep de aynı form üzerinden üreticiye iletilir. API yüzeyi sabit ve sınırsız değildir; üreticinin onayına bağlı bir kapsamdır.

Başvuru süreci proje takviminin ilk kalemidir. Anahtar ve kapsam netleşmeden geliştirme takvimi vermek tahmin olur.

Test Ortamı ve Üretim Ortamı

Yazma işlemlerini canlı firmada denemeyin. Test için ayrı bir firma ve ayrı bir kullanıcı tanımlanır; geliştirme boyunca kayıtlar oraya yazılır. Böylece yanlışlıkla canlı veriye yazma riski ortadan kalkar.

Entegrasyon Öncesi Kontrol Listesi

1. Ürün ve sürüm: Run, Jump, Fly ya da Jump Bulut; V16 mı V17 mi?
2. API Key: Başvuru yapıldı mı, anahtar tanımlandı mı?
3. Port: Servisin dinlediği port doğrulandı mı?
4. Yapı: Kaç firma ve kaç çalışma yılı aktif?
5. Kapsam: İhtiyaç duyulan veri API üzerinden erişilebilir mi?
6. Test firması: Tanımlandı mı?
7. Dayanıklılık: Yeniden deneme, zaman aşımı ve hata kaydı kodda var mı?

Jump Bulut kullanıyorsanız bunu baştan belirtin. Üretici bulut sürüm için ayrı bir çağrı koleksiyonu yayımlıyor; masaüstü ile bulut yüzeyi birebir aynı varsayılmamalı.

D'Cloud Software'in Mikro Entegrasyon Yaklaşımı

D'Cloud Software, Mersin merkezli bağımsız bir yazılım firmasıdır. Mikro bayisi değiliz; lisans, kurulum ve program desteği yetkili bayinizde kalır. Mikro entegrasyonlarında şu ilkelerle çalışırız:

1. Sürüm Bağımsız Mimari

Port, uç nokta sürümü ve kimlik bilgisi gibi değişmeye açık her şey yapılandırma katmanında tutulur. Yükseltme sonrası yapılacak iş kod değişikliği değil, ayar güncellemesidir.

2. Firma Bazlı Kimlik Yönetimi

Çok firmalı yapıda kimlik bilgileri şifreli olarak saklanır ve istek başına üretilir. Yeni firma eklendiğinde kod değişmez.

3. Tipli Uç Noktalar İçin Model Sınıfları

Kullanılan her uç nokta için istek yapısını yansıtan model sınıfı yazılır. Yanlış alan adı ya da tip, kod yazılırken yakalanır.

4. Yükseltme Öncesi Regresyon Turu

Kritik senaryolar otomatik testlerle kapsanır ve her yükseltme öncesinde test ortamında çalıştırılır.

5. 15 Gün Ücretsiz Hata Düzeltme

Teslimden sonraki 15 gün içinde çıkan hatalar ücretsiz düzeltilir. Sürüm notlarını izlemek ve yükseltme öncesi regresyon turu çalıştırmak sürekli bir iştir; sözleşmede ayrı bir bakım kalemi olarak yazılır.

Örnek Senaryolar: Mikro Entegrasyonunda Tipik Sorunlar ve Çözümler

Aşağıdaki senaryolar varsayımsaldır; belgelenmiş davranışların pratikte nasıl karşınıza çıkabileceğini göstermek için yazılmıştır.

Senaryo 1: E-Ticaret - Mikro Sipariş Aktarımı

Bir perakende firması e-ticaret siparişlerini Mikro'ya aktarıyor. V16'dan V17'ye geçişten sonra aktarım duruyor.

Sorun: Port koda sabit yazılmış. Servis artık 8084 yerine 8094'ü dinliyor.

Çözüm: Port yapılandırmadan okunur. Servisin ayakta olup olmadığını düzenli kontrol eden bir izleme eklenir; erişim kesildiğinde sorumlu kişiye bildirim gider.

Senaryo 2: Üretim Firması - Malzeme Çıkışı Entegrasyonu

Bir üretim firması hammadde tüketimini Mikro'ya kaydediyor. Yükseltmeden sonra bazı kayıtlar reddedilmeye başlıyor.

Sorun: Entegrasyon eski sürümdeki uç noktanın istek yapısını kullanıyor; yeni sürümde yapı değişmiş.

Çözüm: İstek yapısı güncel sürüme göre düzenlenir. Kayıt Mikro'ya gönderilmeden önce zorunlu alanları kontrol eden bir doğrulama adımı eklenir; eksik alan varsa kayıt gönderilmez ve sebebi yazılır.

Senaryo 3: Holding - Çok Firmalı Konsolidasyon Raporu

Bir grup, beş şirketin Mikro verisini tek bir rapor panelinde topluyor.

Sorun: Kimlik bilgileri koda yazılmış. Yeni şirket eklendiğinde kod değişikliği gerekiyor.

Çözüm: Kimlik bilgileri şifreli bir depoda tutulur ve firma koduna göre istek başına üretilir. Yeni şirket eklemek bir kayıt tanımlamaktan ibaret olur. Firma filtresi veri erişim katmanında kural hâline getirilir.

SSS: Mikro Desktop API Entegrasyonu Hakkında Sıkça Sorulan Sorular

Mikro Desktop API entegrasyonu ne kadar sürer ve maliyeti nedir?

Kapsama bağlıdır. Tek yönlü bir sipariş aktarımı ile çok firmalı, çok modüllü bir entegrasyon aynı iş değildir. Süre ve bedel, keşif görüşmesinde ürün, sürüm ve kapsam netleştikten sonra yazılı olarak verilir ve sözleşmede sabitlenir.

Mikro sürüm güncellemesi entegrasyonu etkiler mi?

Etkileyebilir. Büyük sürüm geçişinde port değişir: V16'da 8084, V17'de 8094. Uç noktalar da sürümlendiği için eski uca bağlı kalan entegrasyon yeni alanları görmez. Port ve uç nokta sürümünü yapılandırmada tutmak ve yükseltme öncesi regresyon testi çalıştırmak bu riski azaltır.

Mikro Desktop API kullanmak için lisans ücreti var mı?

API kullanımı API Key gerektirir ve anahtar başvuruyla alınır. Ücret ve paket koşulları konusunda bağlayıcı bilgi üreticide ve yetkili bayinizdedir. Bayi olmadığımız için bu konuda sizin adınıza taahhüt vermiyoruz; başvuru sürecinde teknik olarak yanınızda oluruz.

Mikro veritabanına doğrudan bağlanıp SQL yazamaz mıyız?

Okuma için sorgu yazılabilir. Üretici, API içindeki serbest SQL ucunu yalnızca SELECT için belgeliyor. Kayıt oluşturma ve güncelleme ise tipli uç noktalara bağlı. Biz de bu tasarıma uyuyoruz: okumada esnek, yazmada ürünün kendi çağrılarıyla çalışıyoruz.

Çok firmalı yapıda aynı entegrasyon kodu kullanılabilir mi?

Evet. Adres aynı kalır; firma kodu, çalışma yılı ve kullanıcı bilgisi istek gövdesinde değişir. Önemli olan, bu bilgilerin güvenli saklanması ve istek başına üretilmesidir.

Entegrasyon hata verdiğinde destek süreci nasıl işler?

Teslimden sonraki 15 gün içinde çıkan hatalar ücretsiz düzeltilir. Sonrası için bakım sözleşmesi yapılabilir. Entegrasyonda hata kaydı tutulduğu için sebep çoğu zaman kayıttan okunur. Sorun ürün tarafındaysa çözüm yetkili bayinizle birlikte yürütülür.

Sonuç: Mikro Entegrasyonunda Sürdürülebilir Mimari ve Gerçekçi Beklentiler

Mikro Desktop API, okumayı esnek bırakan ve yazmayı tipli uç noktalara bağlayan, belgelenmiş bir arayüz. Bir kez kurulup unutulacak bir yapı değil: port sürümle değişiyor, uç noktalar sürümleniyor, kırıcı değişiklikler ayrıca ilan edilmiyor.

Sağlam bir entegrasyon için:

• Port ve uç nokta sürümünü koda yazmayın.
• Kimlik bilgisini istek başına üretin ve güvenli saklayın.
• Serbest SQL'i yalnızca okuma için kullanın.
• Tarih alanlarına saat yazmayın, kod değerlerini ürünün fonksiyonlarıyla çözün.
• Her yükseltmeden önce regresyon testi çalıştırın.
• API Key başvurusunu projenin ilk adımına koyun.

Kurulumunuzu birlikte değerlendirmek için iletişim formu ya da WhatsApp üzerinden ücretsiz keşif görüşmesi talep edebilirsiniz.