Mikro entegrasyonu: API'ye nasıl bağlanılır, neden tablolara doğrudan yazılmaz?

Mikro API nedir?

Mikro API, Mikro Yazılım’ın sipariş, stok, cari ve fatura işlemlerini HTTP üzerinden JSON ile açan resmi servis katmanıdır. Uygulamanız isteği imzalar, servis isteği Mikro’nun kendi kitaplığına aktarır, kayıt orada oluşur.

Aradaki fark önemli: kayıt veritabanına doğrudan yazılmadığı için stok düşümü, maliyet hesabı ve muhasebe zinciri Mikro’nun kendi kurallarıyla işler. Arayüzden elle girilmiş bir kayıtla aynı davranışı gösterir.

Not: Uç nokta adları, alan setleri ve sürüm numaraları kurulu Mikro sürümüne ve servis paketine göre değişir. Bu yazıdaki değişmez bilgiler Mikro'nun kendi API dokümanına dayanır; örnek istek gövdeleri ise bizim kurduğumuz ara katmanın dış uygulamalara sunduğu sözleşmedir. Kendi kurulumunuzun tam uç nokta listesi için Mikro'nun API başvurusu sonrası verilen dokümanı esas alın.

Kimlik doğrulama akışı

Mikro API klasik “kullanıcı adı + şifre” göndermez. Şifre, tarih ile birleştirilip özetlenerek iletilir; böylece ağdan yakalanan bir istek ertesi gün tekrar oynatılamaz.

1. API anahtarı: İstek başlığında gönderilir. Anahtar hatalıysa servis Geçersiz api key döner.
2. Şifre özeti: Tarih ve şifre birleştirilip özet değeri üretilir, düz şifre gönderilmez.
3. Bağlam alanları: KullaniciKodu, FirmaKodu ve CalismaYili her çağrıda zorunludur.
4. Yalıtım: Anahtar ve şifre yalnızca uygulama sunucusunda durur; tarayıcıya, mobil uygulamaya veya el terminaline hiçbir zaman inmez.

Son madde bir tercih değil, güvenlik şartıdır. API anahtarı istemci tarafına indiğinde tarayıcı geliştirici konsolunu açan herkes şirketin ERP’sine yazma yetkisi kazanır.

Sürüm ve port eşlemesi

Servis, ERP’nin kurulu olduğu yerel sunucuda çalışır ve sürümüne göre ayrı port dinler:

Uç noktalara yeni alan eklendiğinde sürüm numarası artırılarak yayınlanır (V1, V2 gibi). Bu, eski istemcilerin kırılmadan çalışmaya devam etmesini sağlar; entegrasyonunuzu yazarken hangi sürüme bağlandığınızı yapılandırmada sabitleyin.

Projeyi geciktiren asıl kalem: lisans

Teknik ekipler entegrasyonu kod problemi sanır; Mikro tarafında takvimi belirleyen ilk kalem genellikle lisanstır.

• Mikro’nun dikey çözüm iş ortaklarından birini kullanıyorsanız API anahtarı lisansı otomatik atanır.
• Şirketin kendi iç yazılımı için bağlanacaksanız lisans elle tanımlanır ve uç nokta listesi için Mikro’nun API başvuru formu doldurulur.

Bu yüzden proje planında ilk hafta koda değil, başvuruya ayrılır. Başvuru sonuçlanmadan yazılacak kod, hangi uç noktaların açılacağı bilinmeden yazılmış olur.

Neden tablolara doğrudan yazılmaz?

Mikro’nun resmi yolu, kayıtların kendi kitaplığı üzerinden oluşturulmasıdır; SQL ile doğrudan kayıt girişi kullanılmaz. Sebebi tek cümleyle şudur: bir sipariş satırı yalnızca bir satır değildir.

Bir siparişi ERP ekranından girdiğinizde arka planda stok rezervi, cari risk kontrolü, iskonto kademesi, KDV matrahı ve maliyet kaydı zinciri çalışır. INSERT bunların hiçbirini çalıştırmaz. Sonuç, sahada en sık gördüğümüz arıza tablosudur:

• Sipariş listede görünür ama stok düşmemiştir.
• Fatura kesilir, maliyet tablosu boş kalır ve ay sonu kârlılık raporu yanlış çıkar.
• Muhasebe fişi oluşmaz; hata aylar sonra mizanda fark edilir.

Bunlar sessiz hatalardır. Ekranda kırmızı bir uyarı çıkmaz, bu yüzden ilk aylarda entegrasyon “çalışıyor” görünür.

Peki okuma?

Okuma tarafı farklıdır ve burada esneklik vardır: API’nin SQL okuma uç noktası üzerinden SELECT sorgusu çalıştırılabilir. Pratikte doğru bölüşüm şudur:

Kural sadeleştirilirse: okurken SQL serbest, yazarken API zorunlu.

Yazılamayan sistem alanları

Kaydın kimliğini, oluşturan kullanıcıyı ve bütünlük değerini tutan sistem alanlarına dışarıdan veri girilemez; bunları servis kendisi doldurur.

Entegrasyon tasarımında bunun tek pratik sonucu var: bu alanları kendi anahtarınız olarak kullanmayın. Kendi belge numaranızı ayrı bir alanda taşıyın ve mükerrer kayıt kontrolünü o alan üzerinden yapın.

Ara katman: neden doğrudan bağlanmıyoruz

Bulut tarafındaki uygulamayı Mikro API’ye doğrudan bağlamak iki nedenle çalışmaz. Birincisi API yerel sunucuda durur; ikincisi Active-Active kurulum desteklenmez, yani tek örnek çalışır ve o örnek kapandığında yazacak yer kalmaz.

Bu yüzden araya ince bir köprü servis konur:

Örnek: B2B portaldan gelen siparişin Mikro’ya yazılması

Aşağıdaki sözleşme köprünün dış uygulamalara sunduğu arayüzdür; Mikro’nun kendi uç nokta adları kurulumdan kuruluma değişir.

POST /kopru/v1/siparis
Authorization: Bearer <jeton>
Content-Type: application/json

{
  "cariKod": "120.01.0042",
  "belgeNo": "WEB-2026-000118",
  "tarih": "2026-08-28",
  "depoKodu": "01",
  "satirlar": [
    { "stokKodu": "MTL-4512", "miktar": 240, "birim": "AD" },
    { "stokKodu": "MTL-4519", "miktar":  60, "birim": "AD" }
  ]
}

Köprü isteği aldığında sırayla: cari risk limitini ve açık bakiyeyi okur, stok kodlarını ve depodaki kullanılabilir miktarı doğrular, fiyatı cari iskonto kurallarına göre Mikro’dan okur, sonra kaydı API üzerinden yazar. Fiyatı portal tarafında hesaplamaz — iskonto kuralı ERP’de değişince portal yanlış fiyat vermeye başlar.

{
  "durum": "kaydedildi",
  "erpBelgeNo": "SIP2026000004417",
  "uyarilar": [
    { "stokKodu": "MTL-4519", "mesaj": "Talep 60, serbest stok 45. Kalan 15 adet termine bağlandı." }
  ]
}

Cevabın kritik kısmı uyarilardır: sipariş reddedilmez, ama eksik stok da sessizce yutulmaz. Bayi ekranında bu uyarı doğrudan gösterilir; “sipariş geçti ama gelmedi” telefonu böylece hiç doğmaz.

Canlıya almadan önce

Mikro’nun demo kurulumu üzerinde sınırlı sayıda kayıtla (100 kayda kadar) test yapılabilir. Akışı ve alan eşlemesini doğrulamak için yeterlidir; yük ve eşzamanlılık davranışı için canlı benzeri bir kopya gerekir.

Kabul testinde en az şunu bir kez uçtan uca çalıştırın: sipariş → irsaliye → fatura. Sonra tutarları ERP ekranından okuyup entegrasyonun döndürdüğü değerlerle karşılaştırın. Kuruş farkı varsa sebebi neredeyse her zaman iskonto sırası veya KDV yuvarlama kuralıdır ve canlıda düzeltmek çok daha pahalıdır.

Sık karşılaşılan üç hata

1. Fiyatı portalda hesaplamak. ERP’deki iskonto kademesi değiştiğinde portal eski fiyattan satmaya devam eder. Fiyat her zaman ERP’den okunur.
2. Kuyruğu atlamak. API tek örnek çalıştığı için bakım veya yeniden başlatma anında yazma başarısız olur. Kuyruk yoksa sipariş kaybolur.
3. Sistem alanını anahtar yapmak. Servisin kendi doldurduğu alanlara yaslanan eşleştirme, sürüm yükseltmesinde sessizce kopar.

Aynı köprü mantığının diğer programlardaki karşılığı: Logo, Netsis REST API, DİA Web Servis API, SAP Business One Service Layer, Nebim V3 Entegratör ve Paraşüt API.

Mikro’yu değiştirmeden üzerine kurmak

Bu yazıdaki mimarinin amacı Mikro’yu değiştirmek değil. Muhasebe, resmi defter ve cari takip Mikro’da kalır; saha uygulaması, bayi portalı, üretim takibi ve raporlama yanına yazılır. İki sistem tek bir noktada — API köprüsünde — buluşur.

Kendi kurulumunuzda hangi süreçlerin ERP’de kalıp hangilerinin yanına yazılacağını konuşmak için sürecinizi anlatın; ilk görüşme 30 dakika ve ücretsizdir.

---

İlgili Üretim Rehberleri ve Hesaplayıcılar

• OEE ve Makine Duruş Kaybı Hesaplayıcı — Tezgâh duruşlarının yıllık maliyetini ve OEE skorunu hesaplayın.
• Atölye Teklif Süresi ve Kaçan Sipariş Hesaplayıcı — WhatsApp ve telefonda fiyat verirken kaybolan usta saatlerini ölçün.
• MES ve Üretim Takip Yazılımı Fiyatları 2026 — Tezgâh veri toplama ve Andon panoları maliyet analizi.
• En İyi Fason ve Atölye Takip Programları — Excel, Logo ve özel fason portalı karşılaştırması.

Sıkça sorulan sorular

Mikro API nedir?

Mikro API, Mikro Yazılım'ın kendi iş kurallarını çalıştıran resmi REST servisidir. Veri alışverişi JSON ile yapılır. Sipariş, stok, cari ve fatura kayıtları bu servis üzerinden okunur ve yazılır; kayıt oluşturma işlemi Mikro'nun kendi kitaplığı üzerinden yürüdüğü için arayüzden elle girilmiş bir kayıtla aynı denetim davranışına sahiptir.

Mikro API'de kimlik doğrulama nasıl yapılır?

İstek başlığında bir API anahtarı gönderilir. Şifre alanı düz metin değildir: tarih ile şifre birleştirilip özet (hash) değeri üretilir ve o gönderilir. Ayrıca kullanıcı kodu, firma kodu ve çalışma yılı alanları her istekte zorunludur. Anahtar hatalıysa servis 'Geçersiz api key' hatası döner.

Mikro API'yi kullanmak için ayrı lisans gerekir mi?

Evet, bir lisanslama adımı vardır. Mikro'nun dikey çözüm iş ortaklarını kullananlara API anahtarı lisansı otomatik atanır. Şirketin kendi iç yazılımı için bağlanacaksanız lisans elle tanımlanır ve uç nokta listesi için Mikro'nun API başvuru formunun doldurulması gerekir. Bu adım çoğu projede takvimi belirleyen ilk kalemdir.

Mikro tablolarına doğrudan SQL ile kayıt yazılabilir mi?

Mikro'nun resmi entegrasyon yolu bu değildir: kayıtlar Mikro'nun kendi kitaplığı üzerinden oluşturulur, SQL ile doğrudan kayıt girişi kullanılmaz. Doğrudan INSERT/UPDATE yapmak maliyet, stok ve muhasebe zincirini yürüten iş kurallarını atlar; kayıt veritabanında görünür ama arkasındaki hesaplar oluşmaz. Okuma tarafı farklıdır: API'nin SQL okuma uç noktası üzerinden SELECT sorgusu çalıştırılabilir.

Mikro API hangi sürümlerde ve hangi portta çalışır?

Servis, ERP'nin kurulu olduğu yerel sunucuda çalışır ve sürümüne göre ayrı port dinler: v16 için 8084, v17 için 8094. Uç noktalara yeni alanlar eklendiğinde sürüm numarası artırılarak (V1, V2 gibi) yayınlanır, böylece eski istemciler kırılmaz.

Mikro API'de yazılamayan alanlar var mı?

Evet. Kaydın kimliğini, oluşturan kullanıcıyı ve bütünlük değerini tutan sistem alanlarına dışarıdan veri girilemez. Bu alanları servis kendisi doldurur. Entegrasyonu tasarlarken bu alanları kendi anahtarınız olarak kullanmayın; kendi belge numaranızı ayrı bir alanda taşıyın.

Mikro API yüksek erişilebilirlik (Active-Active) kurulumunu destekler mi?

Desteklenmez. API, ERP'nin bulunduğu yerel sunucuda tek örnek olarak çalışır. Bu yüzden bulut tarafındaki uygulamanız API'ye doğrudan bağımlı kurulmamalı: araya kuyruk konur, servis erişilemezken istekler birikir ve bağlantı geldiğinde sırayla işlenir.

Mikro entegrasyonunu canlıya almadan nasıl test ederim?

Mikro'nun demo kurulumu üzerinde sınırlı sayıda kayıtla (100 kayda kadar) test yapılabilir. Bu, akışı ve alan eşlemesini doğrulamak için yeterlidir; yük ve eşzamanlılık davranışı için canlı benzeri bir kopya gerekir. Test aşamasında sipariş, irsaliye ve fatura zincirini uçtan uca bir kez çalıştırıp tutarları ERP ekranıyla karşılaştırın.

İlgili rehberler

• Logo ve Netsis entegrasyon rehberi: REST API, Objects ve özel web/mobil arayüz köprüsü
• DİA Web Servis API: kendi yazılımınızı DİA'ya nasıl bağlarsınız?
• Nebim V3 Entegratör REST API: perakende ERP'nizi dış sistemlere nasıl bağlarsınız?

Hizmet sayfası: Entegrasyon hizmeti